loadout-ai 0.3.1 → 0.4.0

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 (44) hide show
  1. package/CHANGELOG.md +42 -0
  2. package/MASTER_PLAN.md +86 -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/adapters.js +10 -0
  8. package/dist/src/core/adopt.js +165 -32
  9. package/dist/src/core/agent-health-score.js +2 -2
  10. package/dist/src/core/catalog-coverage.js +2 -1
  11. package/dist/src/core/catalog-install.js +8 -1
  12. package/dist/src/core/catalog-release.js +2 -1
  13. package/dist/src/core/conformance.js +74 -0
  14. package/dist/src/core/install.js +36 -3
  15. package/dist/src/core/profiles.js +9 -4
  16. package/dist/src/core/ranking.js +1 -1
  17. package/dist/src/core/readme-claims.js +10 -0
  18. package/dist/src/core/readme-facts.js +40 -0
  19. package/dist/src/core/recommend.js +9 -3
  20. package/dist/src/core/runtime-tools.js +5 -2
  21. package/dist/src/core/scheduler.js +2 -1
  22. package/dist/src/core/snapshot.js +58 -13
  23. package/dist/src/core/state.js +8 -1
  24. package/dist/src/core/transaction.js +2 -1
  25. package/dist/src/core/uninstall.js +26 -2
  26. package/dist/src/dashboard.js +5 -2
  27. package/dist/src/shared/schemas.js +57 -0
  28. package/docs/FEATURE_TEST_MATRIX.md +16 -0
  29. package/docs/README_RESEARCH.md +36 -0
  30. package/docs/RELEASE_REVIEW.md +31 -5
  31. package/docs/REPOSITORY_STABILIZATION.md +190 -0
  32. package/docs/TESTING.md +50 -0
  33. package/docs/USER_TEST_GUIDE.md +26 -0
  34. package/docs/assets/loadout-hero.svg +259 -0
  35. package/docs/assets/loadout-mark.svg +54 -0
  36. package/docs/evidence/live-checks-2026-07-19.json +22 -0
  37. package/docs/evidence/live-checks.schema.json +28 -0
  38. package/docs/evidence/readme-claims.json +286 -0
  39. package/docs/superpowers/plans/2026-07-19-relatable-readme-hero.md +283 -0
  40. package/docs/superpowers/specs/2026-07-19-relatable-readme-hero-design.md +80 -0
  41. package/package.json +8 -4
  42. package/SIMPLE_PLAN.md +0 -44
  43. package/docs/plans/2026-07-18-release-0.3.md +0 -42
  44. 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
@@ -158,6 +158,32 @@ loadout uninstall --yes
158
158
  To remove the npm command too, use `loadout uninstall --yes --remove-cli`. Complete
159
159
  cleanup deliberately deletes Loadout's snapshots, so it is the last lifecycle test.
160
160
 
161
+ ## Troubleshooting and recovery
162
+
163
+ - **`loadout` is not found after installation:** confirm `npm install --global
164
+ loadout-ai@0.4.0` completed, run `hash -r`, and confirm npm's global binary
165
+ directory is on `PATH`. For a source checkout, run `npm run build` and `npm link`.
166
+ - **A preview asks for `--approve-risk`:** read the reported scripts, domains,
167
+ credentials, binaries, or instruction findings. If you accept that specific plan,
168
+ use the exact rerun command Loadout prints. The flag is not a general safety
169
+ guarantee and should not be added routinely.
170
+ - **Rollback or removal is refused:** preserve the current files. Refusal can mean a
171
+ managed path changed, disappeared, changed type, gained content, or belongs to a
172
+ legacy snapshot without post-mutation evidence. Run `loadout health --explain` and
173
+ inspect the affected path before deciding whether an explicit force option is
174
+ appropriate; do not delete the path merely to make the command pass.
175
+ - **A fetch, discovery, or update check fails:** retry only after checking network,
176
+ proxy, DNS, and source-host access. Local inventory, library, health, rollback, and
177
+ offline fixture tests remain separate; an unavailable live check is not a pass.
178
+ - **You need diagnostics:** run `loadout doctor`, `loadout health --explain`, and
179
+ `loadout status`. Redact usernames, local paths, repository names, tokens, and agent
180
+ state before sharing output.
181
+ - **You need complete removal:** first preview with `loadout uninstall`, then use
182
+ `loadout uninstall --yes` to remove managed agent files, runtime tools, scheduled
183
+ jobs, cache, snapshots, and state. Add `--remove-cli` only for a global npm install.
184
+ Unmanaged content is preserved, and modified managed files can make cleanup refuse
185
+ until you explicitly review the command's force path.
186
+
161
187
  ## 9. Advanced surface
162
188
 
163
189
  The first help screen deliberately focuses on daily use. Existing advanced
package/docs/assets/loadout-hero.svg ADDED
@@ -0,0 +1,259 @@
1
+ <svg
2
+ xmlns="http://www.w3.org/2000/svg"
3
+ viewBox="0 0 960 300"
4
+ role="img"
5
+ aria-labelledby="loadout-hero-title loadout-hero-description"
6
+ >
7
+ <title id="loadout-hero-title">Choose an intentional agent loadout</title>
8
+ <desc id="loadout-hero-description">
9
+ A developer moves an extension from scattered configuration tiles into
10
+ organized managed equipment slots.
11
+ </desc>
12
+ <style>
13
+ svg {
14
+ color: #1f2328;
15
+ }
16
+ .quiet {
17
+ opacity: 0.48;
18
+ }
19
+ .soft {
20
+ opacity: 0.09;
21
+ }
22
+ .mid {
23
+ opacity: 0.72;
24
+ }
25
+ .line {
26
+ fill: none;
27
+ stroke: currentColor;
28
+ stroke-linecap: round;
29
+ stroke-linejoin: round;
30
+ }
31
+ @media (prefers-color-scheme: dark) {
32
+ svg {
33
+ color: #f0f6fc;
34
+ }
35
+ .soft {
36
+ opacity: 0.13;
37
+ }
38
+ }
39
+ </style>
40
+
41
+ <!-- Loose, unmanaged configuration -->
42
+ <g class="line quiet" stroke-width="2">
43
+ <path d="M38 80C96 63 126 124 188 104S258 78 286 119" />
44
+ <path d="M47 221C96 183 128 235 179 202S247 174 286 204" />
45
+ <path d="M78 47C91 96 62 141 105 176S175 199 213 239" />
46
+ <path d="M205 53C177 91 219 133 187 158S122 167 88 211" />
47
+ </g>
48
+ <g class="line" stroke-width="2.5">
49
+ <g transform="rotate(-8 91 100)">
50
+ <rect
51
+ class="soft"
52
+ x="43"
53
+ y="72"
54
+ width="96"
55
+ height="56"
56
+ rx="10"
57
+ fill="currentColor"
58
+ />
59
+ <rect x="43" y="72" width="96" height="56" rx="10" />
60
+ <path d="M61 99l9-8m-9 8l9 8m18-16h29" />
61
+ </g>
62
+ <g transform="rotate(7 197 83)">
63
+ <rect
64
+ class="soft"
65
+ x="153"
66
+ y="57"
67
+ width="88"
68
+ height="52"
69
+ rx="10"
70
+ fill="currentColor"
71
+ />
72
+ <rect x="153" y="57" width="88" height="52" rx="10" />
73
+ <path d="M174 74v18m0-9h15m14-9v18m-7-9h14" />
74
+ </g>
75
+ <g transform="rotate(-5 113 190)">
76
+ <rect
77
+ class="soft"
78
+ x="64"
79
+ y="161"
80
+ width="98"
81
+ height="58"
82
+ rx="10"
83
+ fill="currentColor"
84
+ />
85
+ <rect x="64" y="161" width="98" height="58" rx="10" />
86
+ <path d="M86 179l-8 11 8 11m53-22l8 11-8 11m-34 4l15-30" />
87
+ </g>
88
+ <g transform="rotate(9 213 193)">
89
+ <rect
90
+ class="soft"
91
+ x="170"
92
+ y="166"
93
+ width="86"
94
+ height="54"
95
+ rx="10"
96
+ fill="currentColor"
97
+ />
98
+ <rect x="170" y="166" width="86" height="54" rx="10" />
99
+ <circle cx="190" cy="193" r="5" />
100
+ <circle cx="233" cy="181" r="5" />
101
+ <circle cx="233" cy="205" r="5" />
102
+ <path d="M195 191l33-9m-33 13l33 9" />
103
+ </g>
104
+ </g>
105
+ <g class="line" stroke-width="2.5">
106
+ <path d="M48 232v24h12" />
107
+ <path d="M64 232h12v24H64zM80 232h12v24H80z" />
108
+ <path d="M108 232H96v12h12v12H96" />
109
+ <path d="M124 232h-12v24h12m-12-12h10" />
110
+ </g>
111
+
112
+ <!-- Developer selecting one extension tile -->
113
+ <g class="line" stroke-width="3">
114
+ <circle class="soft" cx="333" cy="91" r="28" fill="currentColor" />
115
+ <circle cx="333" cy="91" r="28" />
116
+ <path d="M310 87c10-14 34-18 46-2M319 99c8 7 18 7 27 0" />
117
+ <path d="M331 119v61m-1-41l-40 3-28-17" />
118
+ <path d="M331 138l33-9 29 15" />
119
+ <path d="M315 180l-16 38m48-38l17 38" />
120
+ <path d="M282 125l-13 3 7 10" />
121
+ <rect
122
+ class="soft"
123
+ x="253"
124
+ y="111"
125
+ width="43"
126
+ height="31"
127
+ rx="7"
128
+ fill="currentColor"
129
+ />
130
+ <rect x="253" y="111" width="43" height="31" rx="7" />
131
+ <path d="M265 127h19m-9-8v16" />
132
+ </g>
133
+ <g class="line mid" stroke-width="3">
134
+ <path d="M283 226h119l18-47h-97" />
135
+ <path d="M298 227v22m89-22v22" />
136
+ <path d="M351 165h48" />
137
+ </g>
138
+
139
+ <!-- Management boundary and placement cue -->
140
+ <path
141
+ class="line quiet"
142
+ d="M456 39v222"
143
+ stroke-width="2"
144
+ stroke-dasharray="7 10"
145
+ />
146
+ <g class="line" stroke-width="3">
147
+ <path d="M403 125c30-18 48-23 72-13 14 6 22 18 31 28" />
148
+ <path d="M493 137l15 5-3-15" />
149
+ </g>
150
+ <g class="line" stroke-width="2.5">
151
+ <path d="M478 48V26l6 12 6-12v22" />
152
+ <path d="M494 48l6-22 6 22m-9-8h6" />
153
+ <path d="M510 48V26l12 22V26" />
154
+ <path d="M526 48l6-22 6 22m-9-8h6" />
155
+ <path d="M554 33v-7h-12v22h12V38h-6" />
156
+ <path d="M570 26h-12v22h12m-12-11h10" />
157
+ <path d="M574 26v22h5c9 0 9-22 0-22z" />
158
+ </g>
159
+
160
+ <!-- Calm, organized loadout rail -->
161
+ <rect
162
+ class="soft"
163
+ x="486"
164
+ y="75"
165
+ width="438"
166
+ height="154"
167
+ rx="25"
168
+ fill="currentColor"
169
+ />
170
+ <rect
171
+ class="line mid"
172
+ x="486"
173
+ y="75"
174
+ width="438"
175
+ height="154"
176
+ rx="25"
177
+ stroke-width="2.5"
178
+ />
179
+ <path class="line quiet" d="M508 244h394" stroke-width="2.5" />
180
+ <g class="line" stroke-width="3">
181
+ <g>
182
+ <rect
183
+ class="soft"
184
+ x="510"
185
+ y="103"
186
+ width="68"
187
+ height="96"
188
+ rx="13"
189
+ fill="currentColor"
190
+ />
191
+ <rect x="510" y="103" width="68" height="96" rx="13" />
192
+ <path d="M530 141l10 10-10 10m18 0h12" />
193
+ </g>
194
+ <g>
195
+ <rect
196
+ class="soft"
197
+ x="591"
198
+ y="103"
199
+ width="68"
200
+ height="96"
201
+ rx="13"
202
+ fill="currentColor"
203
+ />
204
+ <rect x="591" y="103" width="68" height="96" rx="13" />
205
+ <path
206
+ d="M620 132v12m11-12v12m-17 0h23v9c0 8-5 14-12 14s-12-6-12-14v-9m12 23v7"
207
+ />
208
+ </g>
209
+ <g>
210
+ <rect
211
+ class="soft"
212
+ x="672"
213
+ y="103"
214
+ width="68"
215
+ height="96"
216
+ rx="13"
217
+ fill="currentColor"
218
+ />
219
+ <rect x="672" y="103" width="68" height="96" rx="13" />
220
+ <circle cx="693" cy="151" r="6" />
221
+ <circle cx="720" cy="133" r="6" />
222
+ <circle cx="720" cy="169" r="6" />
223
+ <path d="M698 147l17-11m-17 19l17 11" />
224
+ </g>
225
+ <g>
226
+ <rect
227
+ class="soft"
228
+ x="753"
229
+ y="103"
230
+ width="68"
231
+ height="96"
232
+ rx="13"
233
+ fill="currentColor"
234
+ />
235
+ <rect x="753" y="103" width="68" height="96" rx="13" />
236
+ <path
237
+ d="M785 128c-8 0-9 5-9 12v4c0 5-3 7-8 7 5 0 8 2 8 7v4c0 7 1 12 9 12m4-46c8 0 9 5 9 12v4c0 5 3 7 8 7-5 0-8 2-8 7v4c0 7-1 12-9 12"
238
+ />
239
+ </g>
240
+ <g class="quiet">
241
+ <rect
242
+ x="834"
243
+ y="103"
244
+ width="68"
245
+ height="96"
246
+ rx="13"
247
+ stroke-dasharray="7 7"
248
+ />
249
+ <path d="M855 151h26" />
250
+ </g>
251
+ </g>
252
+ <g fill="currentColor">
253
+ <circle cx="544" cy="245" r="4" />
254
+ <circle cx="625" cy="245" r="4" />
255
+ <circle cx="706" cy="245" r="4" />
256
+ <circle cx="787" cy="245" r="4" />
257
+ <circle class="quiet" cx="868" cy="245" r="4" />
258
+ </g>
259
+ </svg>