loadout-ai 0.3.1 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/CHANGELOG.md +67 -0
  2. package/MASTER_PLAN.md +177 -13
  3. package/README.md +157 -284
  4. package/dashboard/app.js +4 -4
  5. package/dashboard/index.html +4 -4
  6. package/dist/src/cli.js +27 -21
  7. package/dist/src/core/active-policy.js +172 -38
  8. package/dist/src/core/active-set.js +13 -4
  9. package/dist/src/core/adapters.js +10 -0
  10. package/dist/src/core/adopt.js +165 -32
  11. package/dist/src/core/agent-health-score.js +2 -2
  12. package/dist/src/core/catalog-coverage.js +2 -1
  13. package/dist/src/core/catalog-install.js +8 -1
  14. package/dist/src/core/catalog-release.js +2 -1
  15. package/dist/src/core/conformance.js +74 -0
  16. package/dist/src/core/install.js +11 -11
  17. package/dist/src/core/profiles.js +9 -4
  18. package/dist/src/core/ranking.js +1 -1
  19. package/dist/src/core/readme-claims.js +10 -0
  20. package/dist/src/core/readme-facts.js +40 -0
  21. package/dist/src/core/recommend.js +104 -12
  22. package/dist/src/core/runtime-tools.js +5 -2
  23. package/dist/src/core/scheduler.js +2 -1
  24. package/dist/src/core/snapshot.js +58 -13
  25. package/dist/src/core/state.js +8 -1
  26. package/dist/src/core/target-occupancy.js +50 -0
  27. package/dist/src/core/transaction.js +2 -1
  28. package/dist/src/core/uninstall.js +26 -2
  29. package/dist/src/dashboard.js +5 -2
  30. package/dist/src/shared/schemas.js +57 -0
  31. package/docs/FEATURE_TEST_MATRIX.md +16 -0
  32. package/docs/README_RESEARCH.md +36 -0
  33. package/docs/RELEASE_REVIEW.md +31 -5
  34. package/docs/REPOSITORY_STABILIZATION.md +190 -0
  35. package/docs/TESTING.md +50 -0
  36. package/docs/USER_TEST_GUIDE.md +42 -4
  37. package/docs/assets/loadout-hero.svg +259 -0
  38. package/docs/assets/loadout-mark.svg +54 -0
  39. package/docs/evidence/live-checks-2026-07-19.json +22 -0
  40. package/docs/evidence/live-checks.schema.json +28 -0
  41. package/docs/evidence/readme-claims.json +286 -0
  42. package/docs/superpowers/plans/2026-07-19-relatable-readme-hero.md +283 -0
  43. package/docs/superpowers/plans/2026-07-20-project-activation-safety.md +469 -0
  44. package/docs/superpowers/specs/2026-07-19-relatable-readme-hero-design.md +80 -0
  45. package/docs/superpowers/specs/2026-07-20-project-activation-safety-design.md +228 -0
  46. package/package.json +8 -4
  47. package/SIMPLE_PLAN.md +0 -44
  48. package/docs/plans/2026-07-18-release-0.3.md +0 -42
  49. package/docs/superpowers/plans/2026-07-18-cli-ux-polish.md +0 -86
package/docs/README_RESEARCH.md ADDED
@@ -0,0 +1,36 @@
1
+ # README redesign research
2
+
3
+ Research was performed against the current default-branch READMEs on 2026-07-19 and
4
+ recorded at immutable commits so the references remain reproducible.
5
+
6
+ | Repository | README studied | Principle adopted |
7
+ | ---------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
8
+ | Ponytail | [`16f2980`](https://github.com/DietrichGebert/ponytail/blob/16f29800fd2681bdf24f3eb4ccffe38be3baec6b/README.md) | Give the tool an unmistakable identity and memorable line. |
9
+ | uv | [`1535a67`](https://github.com/astral-sh/uv/blob/1535a6767e5ebd77eac2ace0f6cf1a3edc5f681c/README.md) | Define the product immediately, then show installation and observable proof. |
10
+ | bat | [`7895139`](https://github.com/sharkdp/bat/blob/78951393e29bfd2f2a45f4326b9d2bb5e737dd2a/README.md) | Demonstrate the terminal experience before exhaustive platform detail. |
11
+ | fzf | [`b163463`](https://github.com/junegunn/fzf/blob/b163463079e6254b8582b05acefcf187ec160d9b/README.md) | Use recognizable branding and compact capability statements. |
12
+ | ripgrep | [`227381d`](https://github.com/BurntSushi/ripgrep/blob/227381db0ee83dfa4341f1e27ff9617c0f5ad992/README.md) | Prefer technical precision, scoped proof, and explicit limitations. |
13
+ | mise | [`126e775`](https://github.com/jdx/mise/blob/126e7755cc22e36c3d206b650de613951146b5e3/README.md) | Pair a concise purpose with a real demo and copyable quickstart. |
14
+ | Gum | [`716d8b5`](https://github.com/charmbracelet/gum/blob/716d8b5d0221558f944b5a078dbbcca8572534fb/README.md) | Teach one complete use case before listing the command surface. |
15
+ | Starship | [`8f28dfc`](https://github.com/starship/starship/blob/8f28dfcb1ca3242fba00a3cf98c10ee24605c3ed/README.md) | Separate prerequisites, installation, and configuration. |
16
+
17
+ ## Adopted
18
+
19
+ - A small original mark and one memorable product line.
20
+ - A proof-first opening with only CI, Node requirement, and license badges.
21
+ - A real terminal transcript that distinguishes preview from mutation.
22
+ - Installation and a disposable first success near the top.
23
+ - Short summaries with direct links to detailed technical evidence.
24
+ - Explicit boundaries beside the claims they qualify.
25
+
26
+ ## Rejected
27
+
28
+ - Copying another project's mascot, artwork, prose, or layout.
29
+ - Comparative performance charts or speed claims; Loadout has no valid competitor
30
+ benchmark.
31
+ - Screenshot-led presentation without a real product screenshot.
32
+ - `npm install --global loadout-ai@0.3.2`; that version is not currently published.
33
+ - Claims of universal safety, production readiness, human review, benchmarked sources,
34
+ or native execution across every configured agent.
35
+ - Badge arrays, star counters, community/sponsor promotion, animations, and exhaustive
36
+ command or platform tables on the front page.
package/docs/RELEASE_REVIEW.md CHANGED
@@ -1,8 +1,34 @@
1
- # Release review — 2026-07-15
2
-
3
- This review covers the current Loadout implementation, not an aspirational
4
- roadmap. It was performed after the transaction, source-fetch, dashboard, and
5
- adapter test suites passed locally.
1
+ # Release review — historical 2026-07-15 review, updated 2026-07-19
2
+
3
+ ## Current status and evidence boundary
4
+
5
+ The sections below preserve the evidence recorded for the earlier 0.1.0 review; their
6
+ old package version, catalog count, and test totals are historical and must not be read
7
+ as current 0.3.2 results. The checked-in package is now 0.3.2 with a 50-record catalog.
8
+
9
+ On 2026-07-19, the focused v0.3.x regression run passed 58 tests covering the unified
10
+ upgrade, saved-profile updates, complete uninstall, separation of model API access from
11
+ service credentials, and recursively empty skill-directory recovery. The later
12
+ `npm run verify:full` result is bound to exact tested commit
13
+ `8f8eccdd20272ebb88d0339087fc9cd3828e65c9`: its deterministic evidence gate, 552 tests
14
+ with one explicit skip, both CLI product journeys, package smoke, the 1,000-skill
15
+ performance gate, and two Playwright dashboard projects passed. The evidence-only
16
+ follow-up commit that records this statement was not represented as part of that tested
17
+ commit. These local results establish the tested repository behaviors only; they do not
18
+ retroactively establish native-agent recognition, current npm publication, branch
19
+ protection, or an independent security review.
20
+
21
+ The separate [sanitized live-check report](./evidence/live-checks-2026-07-19.json) was
22
+ generated at `2026-07-19T13:45:14.945Z` and records the same repository commit
23
+ `8f8eccdd20272ebb88d0339087fc9cd3828e65c9` as the deterministic run above. At that
24
+ historical observation time, the pinned Stable install and rollback were verified; npm
25
+ returned 404 for `loadout-ai@0.3.2`; and authenticated GitHub access reached the
26
+ repository but branch protection for `main` returned 404. These results can change
27
+ after the timestamp and are not part of the deterministic offline gate.
28
+
29
+ At the time it was written, this review covered the then-current Loadout
30
+ implementation, not an aspirational roadmap. It was performed after the transaction,
31
+ source-fetch, dashboard, and adapter test suites passed locally.
6
32
 
7
33
  ## P4-08: atomic-commit review — accepted with explicit durability boundary
8
34
 
package/docs/REPOSITORY_STABILIZATION.md ADDED
@@ -0,0 +1,190 @@
1
+ # Repository stabilization record
2
+
3
+ Status date: 2026-07-19. This document records evidence gathered while consolidating
4
+ the repository. `MASTER_PLAN.md` is the only active plan; this is an audit record, not
5
+ a second backlog.
6
+
7
+ ## Starting synchronization inventory
8
+
9
+ The investigation fetched all visible branches and tags before making cleanup
10
+ decisions. The starting GitHub default was `main` at
11
+ `189cb7a0e918860fc37bb92639126b93b387abec` (`v0.3.2`).
12
+
13
+ | Local branch/worktree | Starting head | Tracking state | Starting disposition |
14
+ | ------------------------------------------------- | ------------- | ----------------------------------------------------------- | ------------------------------------------- |
15
+ | `codex/readme-truth`, `/tmp/loadout-readme-truth` | `ee8d548` | 29 ahead of `origin/main`, clean | Preserve and integrate |
16
+ | `dev/nitish`, user checkout | `69b8fe7` | one ahead of `origin/dev/nitish`; untracked `.superpowers/` | Preserve user state and safety requirements |
17
+ | local `main` | `d2a11d8` | 101 behind `origin/main` | Fast-forward after integration |
18
+ | local `develop`, `dev/amartya`, `dev/viraj` | `d2a11d8` | stale or merged | Remove after final-main verification |
19
+
20
+ No local commit was treated as remote merely because it existed in a worktree.
21
+
22
+ ## Failure ledger
23
+
24
+ | Failure | Reproduction/evidence | Root cause/classification | Resolution/status |
25
+ | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
26
+ | 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 |
27
+ | 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 |
28
+ | 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 |
29
+ | 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 |
30
+ | `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 |
31
+ | 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 |
32
+ | 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 |
33
+ | 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 |
34
+ | `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 |
35
+ | `main` protection unavailable | GitHub branch-protection endpoint returns 404 | Repository setting/authorization | Absent or not observable; requires owner decision |
36
+
37
+ Internal failed-transaction recovery deliberately restores the pre-mutation snapshot
38
+ without the later-drift guard. The guard applies to user-requested CLI, dashboard, and
39
+ runtime-tool rollback. Legacy snapshots fail closed for those explicit paths.
40
+
41
+ ## Recent Viraj commits and GitHub Actions
42
+
43
+ The recent Viraj changes were inspected as code and exercised locally; commit messages
44
+ were not used as proof.
45
+
46
+ | Commit | Implemented area | Main/Actions evidence |
47
+ | --------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
48
+ | `817c38f` | Public-beta CLI, package, credential, catalog, and release foundation | In `main`; CI run `29486160804` passed |
49
+ | `9798f1c` | Continuous discovery, generated catalog evidence, and snapshot hardening | In `main`; CI run `29491118338` passed |
50
+ | `6994d4e` | Candidate intelligence, signed catalog release, locking, and transaction hardening | In `main`; CI run `29497632211` passed |
51
+ | `41b53e0` | Stable profile, daily autopilot, and release workflow | In `main`; CI run `29502017220` failed on the Windows-only test fixture described above |
52
+ | `c5fe192` | Host-portable snapshot root guard test | In `main`; CI rerun `29502324100` passed |
53
+ | `4e93f5d` | Cross-platform release-matrix documentation | In `main`; CI run `29502646004` passed |
54
+ | `05e52a4` | Expanded Stable profile and reviewed Graphify recipe | In `main`; CI run `29505093720` passed |
55
+ | `f7f53fa` | Release-work documentation clarification | In `main`; CI run `29505532691` was cancelled after a newer push; no product failure was produced |
56
+ | `e35b8ff` | Upgrade, health-score, benchmark-campaign, and discovery foundation | In `main`; CI run `29508916710` passed |
57
+ | `3cb5505` | Trust, intelligence, benchmark, import, and skill-security systems | In `main`; CI run `29520771134` passed |
58
+ | `8e80ab4` | npm beta metadata and package-smoke adjustment | In `main`; CI run `29522705571` passed |
59
+ | `1fe9890` | Codex Desktop installation detection | In `main`; CI run `29524710934` and discovery run `29557150915` passed |
60
+ | `e4e469e` | Credential-aware setup, Maximum quarantine, and managed update scoping | In `main`; CI run `29583273859` passed |
61
+ | `ebb8133` | Unit-level Power quarantine and onboarding rewrite | In `main`; CI run `29585379546` passed |
62
+ | `88466ef` | npm `0.2.0` verification documentation | In `main`; CI run `29586111523` passed |
63
+ | `cf406e8` | Safe Stable/profile setup reruns | In `main`; CI run `29588415904` passed |
64
+ | `a016c0f` | Exact managed-profile reconciliation | In `main`; CI run `29590309101` passed |
65
+ | `33225ef` | Large rollback-snapshot validation | In `main`; CI run `29591059217` passed |
66
+ | `15f36e3` | Pinned Graphify generated fallback | In `main`; CI run `29591567247` passed |
67
+ | `16b8a7e` | Beginner and advanced CLI routing | In `main`; covered by current CLI tests |
68
+ | `31cb755` | Saved-profile updates and complete uninstall | In `main`; its CI job never started because of billing |
69
+ | `56ab3af` | Separation of model API keys from service credentials | In `main`; its CI job never started because of billing |
70
+ | `189cb7a` | Recursively empty skill-directory recovery | In `main`; its CI job never started because of billing |
71
+ | `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 |
72
+ | `5f8e38e` | Transactional installed-profile state and valid live Stable rollback ordering | Integrated into remote `main`; verified again from a fresh clone |
73
+
74
+ Earlier green runs prove their own commits only. They do not prove later commits that
75
+ GitHub never executed. Current local verification and future post-integration Actions
76
+ must remain separately reported.
77
+
78
+ ## Branch cleanup observations during consolidation
79
+
80
+ At the 2026-07-19 consolidation checkpoint, there was one merged PR:
81
+ [#1](https://github.com/VirajMishra1/loadout/pull/1), `dev/nitish` into `develop`,
82
+ merged as `69594f2`; its recorded Linux, macOS, and Windows Node 20/22 jobs passed.
83
+ The authenticated query at that checkpoint returned no open PRs.
84
+
85
+ | Branch | Unique work relative to starting `origin/main` | Final result |
86
+ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
87
+ | `codex/readme-truth` | README evidence, adapter/product-flow coverage, release hardening, safety fixes, and consolidation | Integrated into `main`; local and remote branch deleted |
88
+ | `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 |
89
+ | `codex/cli-ux-polish` | None; tip `31cb755` is in main | Local and remote branch deleted |
90
+ | `codex/fix-large-snapshot-validation` | None; tip `33225ef` is in main | Local and remote branch deleted |
91
+ | `codex/fix-profile-reconciliation` | None; tip `a016c0f` is in main | Local and remote branch deleted |
92
+ | `codex/fix-stable-rerun` | None; tip `cf406e8` is in main | Local and remote branch deleted |
93
+ | `codex/harden-graphify-generated-install` | None; tip `15f36e3` is in main | Local and remote branch deleted |
94
+ | `dev/amartya` | Integrated through `6161c48` and later follow-ups | Local and remote branch deleted |
95
+ | `dev/viraj` | Old main ancestor | Local and remote branch deleted |
96
+ | `develop` | Old integration ancestor | Local and remote branch deleted |
97
+
98
+ Cleanup completed only after the integrated work reached remote `main` and the open-PR
99
+ list was empty. At that checkpoint, Git exposed only local `main`, `origin/main`, and
100
+ the retained release tags. The `/tmp/loadout-readme-truth` worktree had been removed.
101
+ The user's untracked `.superpowers/` directory remained present and ignored by
102
+ `.gitignore`; no user artifact was deleted.
103
+
104
+ ## Planning and dead-file consolidation
105
+
106
+ `MASTER_PLAN.md` is authoritative because Viraj created it, maintained it across the
107
+ project history, linked it from README, and explicitly labeled its top section as the
108
+ active list. The removed files were unreferenced or self-described historical plans
109
+ whose implementation/status had moved elsewhere.
110
+
111
+ | Removed file | Evidence for deletion | Preserved outcome |
112
+ | ---------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------ |
113
+ | `NITISH_MASTER_PLAN.md` | Unreferenced; stale `dev/nitish`/`develop` policy | Durable safety work is in the master plan and implementation |
114
+ | `SIMPLE_PLAN.md` | Duplicate summary that named `MASTER_PLAN.md` canonical | README retains the user-facing summary |
115
+ | `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 |
116
+ | `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 |
117
+ | README truth implementation plan and design | Implemented, reviewed, and encoded by tests/evidence | Current status is in the master plan and release evidence |
118
+
119
+ Operational contracts such as `docs/TESTING.md`, `docs/FEATURE_TEST_MATRIX.md`,
120
+ `docs/RELEASE_REVIEW.md`, policy documents, and machine-readable evidence remain.
121
+
122
+ ## README research and redesign evidence
123
+
124
+ The redesign research is recorded at immutable commits rather than mutable default
125
+ branches:
126
+
127
+ | Repository | Immutable README reference |
128
+ | ---------- | --------------------------------------------------------------------------------------------------------------- |
129
+ | Ponytail | [`16f2980`](https://github.com/DietrichGebert/ponytail/blob/16f29800fd2681bdf24f3eb4ccffe38be3baec6b/README.md) |
130
+ | uv | [`1535a67`](https://github.com/astral-sh/uv/blob/1535a6767e5ebd77eac2ace0f6cf1a3edc5f681c/README.md) |
131
+ | bat | [`7895139`](https://github.com/sharkdp/bat/blob/78951393e29bfd2f2a45f4326b9d2bb5e737dd2a/README.md) |
132
+ | fzf | [`b163463`](https://github.com/junegunn/fzf/blob/b163463079e6254b8582b05acefcf187ec160d9b/README.md) |
133
+ | ripgrep | [`227381d`](https://github.com/BurntSushi/ripgrep/blob/227381db0ee83dfa4341f1e27ff9617c0f5ad992/README.md) |
134
+ | mise | [`126e775`](https://github.com/jdx/mise/blob/126e7755cc22e36c3d206b650de613951146b5e3/README.md) |
135
+ | Gum | [`716d8b5`](https://github.com/charmbracelet/gum/blob/716d8b5d0221558f944b5a078dbbcca8572534fb/README.md) |
136
+ | Starship | [`8f28dfc`](https://github.com/starship/starship/blob/8f28dfcb1ca3242fba00a3cf98c10ee24605c3ed/README.md) |
137
+
138
+ `docs/README_RESEARCH.md` records the adopted principles and rejected patterns. The
139
+ front page should present the bounded product journey and link to evidence, not repeat
140
+ an exhaustive manual. In particular, the complete adapter table belongs in
141
+ `docs/FEATURE_TEST_MATRIX.md`, not on the front page. A compact front-page support
142
+ summary must continue to distinguish configured target paths and disposable
143
+ filesystem tests from unverified native-agent recognition and execution.
144
+
145
+ ## Dated external observations before the README redesign
146
+
147
+ These observations were captured on 2026-07-19 before README-redesign work began.
148
+ They are a historical checkpoint, not claims about repository state when this document
149
+ is later read.
150
+
151
+ - GitHub repository: the private fork was `reddynitish/loadout`; its default branch
152
+ was `main` at `18757d4`. The earlier `VirajMishra1/loadout` observations in this
153
+ record describe the upstream repository at the time of consolidation.
154
+ - Branches and PRs: `codex/readme-redesign` was the local work branch; the
155
+ authenticated check found no open pull requests in the fork at that time.
156
+ - npm: the registry exposed versions through `0.3.1`; `0.3.2` was not verified as
157
+ published.
158
+ - GitHub Actions: fork CI run
159
+ [`29704170975`](https://github.com/reddynitish/loadout/actions/runs/29704170975) passed
160
+ for `main` at `18757d4`. The upstream billing-blocked runs above were historical
161
+ evidence only and did not describe the fork's CI capability.
162
+ - Branch protection: the authenticated protection endpoint returned HTTP 403 stating
163
+ that the private repository requires GitHub Pro or public visibility for the
164
+ feature. Protection was unavailable under the observed repository plan; this was
165
+ not a product-runtime result.
166
+ - Native application consumption of every configured adapter path was unverified;
167
+ disposable filesystem lifecycle evidence did not establish native-host support.
168
+
169
+ ## Local verification after consolidation
170
+
171
+ On 2026-07-19, `npm run verify:full` completed successfully on macOS with Node 25.4.0:
172
+
173
+ - formatting, lint, type checking, build, catalog/discovery evidence, README claims,
174
+ and release claims passed;
175
+ - 112 Vitest files passed with 589 tests passing and one intentionally skipped;
176
+ - CLI and README product flows passed;
177
+ - packaged CLI smoke passed;
178
+ - the 1,000-skill scan benchmark passed at 240.5 ms p95 across seven CLI runs; and
179
+ - both desktop Chromium and mobile Chromium dashboard tests passed.
180
+
181
+ The fresh-clone live Stable gate also installed four pinned packages and completed
182
+ state and filesystem rollback assertions at `5f8e38e`. An initially considered
183
+ state-ignore fix was rejected during independent review because restoring an old
184
+ registry while leaving later package files could orphan installations. The final fix
185
+ keeps exact `state.json` and managed-root drift protection, includes installed-profile
186
+ state in transaction post-evidence, and uses strict LIFO ordering in the live flow.
187
+
188
+ An npm dry-run contained 137 entries, included this record and `MASTER_PLAN.md`, and
189
+ excluded every deleted plan. These local results do not substitute for GitHub Actions,
190
+ the unpublished `0.3.2` npm tarball, native-host acceptance, or branch protection.
package/docs/TESTING.md CHANGED
@@ -31,6 +31,56 @@ This test does not use the dashboard, network, mock command output, or any real
31
31
  profile. It is a required CI gate on Ubuntu; the manual cross-platform workflow runs
32
32
  the broader native filesystem suite.
33
33
 
34
+ The README journey is a separate deterministic gate. It compiles an isolated build,
35
+ installs a local reviewed fixture into disposable Loadout/user homes, checks its
36
+ manifest, lock, hashes, privacy card, activation, and rollback, then deletes the
37
+ fixture and build:
38
+
39
+ ```bash
40
+ npm run test:e2e:readme
41
+ ```
42
+
43
+ ### README product-flow verification contract
44
+
45
+ The README gate is a mixed core-integration/CLI flow, not a claim that two complete
46
+ native-agent journeys run end to end. It deliberately:
47
+
48
+ - compiles into an isolated temporary build instead of trusting the repository's
49
+ existing `dist` tree;
50
+ - redirects Loadout state, user-home, and project paths to disposable directories;
51
+ - uses a checked-in offline fixture, so its normal result does not depend on the
52
+ network or mutable upstream repositories;
53
+ - calls the core planner and installer directly to verify fixture planning, library
54
+ installation, manifest and lock generation, recorded hashes, and audit state; and
55
+ - starts CLI subprocesses to verify optimize preview/apply, privacy-safe card
56
+ rendering, and rollback restoration through the packaged command boundary.
57
+
58
+ The executable outcome assertions also require isolated-build and offline-fixture
59
+ mode, created state directories, persisted install records, file hashes, snapshots,
60
+ library transitions, manifest/lock consistency, an unmanaged sentinel that survives,
61
+ and byte restoration after rollback.
62
+
63
+ These checks prove Loadout's behavior against disposable filesystem targets. They do
64
+ not prove that every native agent recognizes or executes an installed skill, that a
65
+ live catalog is reachable, that the current npm package is published, or that third-party content
66
+ is universally safe. The opt-in `LOADOUT_TEST_LIVE_CATALOG=1` extension separately
67
+ checks the current pinned Stable sources and remains network-dependent.
68
+
69
+ Run `npm run verify` for formatting, lint, types, deterministic evidence checks, all
70
+ Vitest suites, both CLI journeys, package smoke, and the performance gate. Run
71
+ `npm run verify:full` only when Playwright Chromium is installed and the optional
72
+ dashboard browser test is also wanted.
73
+
74
+ Current npm publication, the current pinned Stable repositories, and GitHub repository
75
+ settings are external state. Check them separately with:
76
+
77
+ ```bash
78
+ npm run check:live -- --npm --stable-install --github
79
+ ```
80
+
81
+ Each requested check reports `verified`, `failed`, or `not-verified`; missing access is
82
+ not converted into a pass.
83
+
34
84
  ## 1. Build the exact npm package entry point
35
85
 
36
86
  ```bash
package/docs/USER_TEST_GUIDE.md CHANGED
@@ -26,15 +26,19 @@ Loadout-managed skills from your own pre-existing skills. `health` checks local
26
26
  loadout catalog --json
27
27
  loadout candidate list --limit 10
28
28
  loadout recommend --project .
29
- loadout optimize --project .
29
+ loadout optimize --project . --agents codex,claude-code --limit 30
30
30
  loadout tool
31
31
  loadout tool graphify
32
32
  ```
33
33
 
34
34
  Run the project commands from the project you care about, or replace `.` with its
35
- absolute path. `optimize` is still a preview until `--yes` is supplied. `tool
36
- graphify` is also a preview; Graphify is a reviewed runtime tool and does not
37
- need an OpenAI or Anthropic API key for its code-only install.
35
+ absolute path. `recommend` labels ordinary skill libraries separately from MCP or
36
+ runtime integrations that require explicit setup. `optimize` is still a preview
37
+ until `--yes` is supplied. Its limit applies separately to every agent and includes
38
+ both Loadout-managed and pre-existing unmanaged skills, so Claude and Codex can
39
+ receive different numbers of additions. `tool graphify` is also a preview; Graphify
40
+ is a reviewed runtime tool and does not need an OpenAI or Anthropic API key for its
41
+ code-only install.
38
42
 
39
43
  ## 3. Open the optional dashboard
40
44
 
@@ -64,6 +68,10 @@ loadout setup --mode power --agents codex,claude-code
64
68
  loadout setup --mode maximum --agents codex,claude-code
65
69
  ```
66
70
 
71
+ Maximum stores reviewed copies in Loadout's disabled library; it does not expose the
72
+ whole catalog to each agent. Follow it with `loadout optimize --project .
73
+ --agents codex,claude-code --limit 30` to preview a compact project-aware working set.
74
+
67
75
  At the API-access question, choose `None` unless you separately pay for a
68
76
  provider API. A ChatGPT Plus or Claude Pro subscription is not an API key. Core
69
77
  skill profiles do not require one; credentialed MCP and runtime operations stay
@@ -158,6 +166,36 @@ loadout uninstall --yes
158
166
  To remove the npm command too, use `loadout uninstall --yes --remove-cli`. Complete
159
167
  cleanup deliberately deletes Loadout's snapshots, so it is the last lifecycle test.
160
168
 
169
+ ## Troubleshooting and recovery
170
+
171
+ - **`loadout` is not found after installation:** confirm `npm install --global
172
+ loadout-ai@0.4.1` completed, run `hash -r`, and confirm npm's global binary
173
+ directory is on `PATH`. For a source checkout, run `npm run build` and `npm link`.
174
+ - **A preview asks for `--approve-risk`:** read the reported scripts, domains,
175
+ credentials, binaries, or instruction findings. If you accept that specific plan,
176
+ use the exact rerun command Loadout prints. The flag is not a general safety
177
+ guarantee and should not be added routinely.
178
+ - **Rollback or removal is refused:** preserve the current files. Refusal can mean a
179
+ managed path changed, disappeared, changed type, gained content, or belongs to a
180
+ legacy snapshot without post-mutation evidence. Run `loadout health --explain` and
181
+ inspect the affected path before deciding whether an explicit force option is
182
+ appropriate; do not delete the path merely to make the command pass.
183
+ - **Activation reports fewer additions for one agent:** this is expected when that
184
+ agent already has unmanaged or managed skills. `--limit` is a total per-agent
185
+ ceiling, not a request to add that many new skills. Recursively empty rollback
186
+ directories do not consume capacity and are safe for Loadout to reuse.
187
+ - **A fetch, discovery, or update check fails:** retry only after checking network,
188
+ proxy, DNS, and source-host access. Local inventory, library, health, rollback, and
189
+ offline fixture tests remain separate; an unavailable live check is not a pass.
190
+ - **You need diagnostics:** run `loadout doctor`, `loadout health --explain`, and
191
+ `loadout status`. Redact usernames, local paths, repository names, tokens, and agent
192
+ state before sharing output.
193
+ - **You need complete removal:** first preview with `loadout uninstall`, then use
194
+ `loadout uninstall --yes` to remove managed agent files, runtime tools, scheduled
195
+ jobs, cache, snapshots, and state. Add `--remove-cli` only for a global npm install.
196
+ Unmanaged content is preserved, and modified managed files can make cleanup refuse
197
+ until you explicitly review the command's force path.
198
+
161
199
  ## 9. Advanced surface
162
200
 
163
201
  The first help screen deliberately focuses on daily use. Existing advanced