loadout-ai 0.1.0 → 0.1.2

package/MASTER_PLAN.md

@@ -1015,13 +1015,19 @@ universal or permanent truth.
       `NOASSERTION` records, before distribution.
 - [ ] `P12-31 [TERRA]` Publish `loadout-ai` to npm and run clean-machine package tests
       from outside the repository on macOS, Windows, Linux, and Node 20/22.
-  - Partial: a real tarball is packed, installed outside the repository, executed,
-    catalog-checked, used for install, and rolled back. CI contains an opt-in OS/Node
-    matrix and an owner-controlled OIDC/provenance release workflow. The hosted
-    macOS/Windows/Linux Node 20/22 matrix passes; actual npm publication and the
-    post-publication clean external package checks remain release-owner actions.
+  - Partial: `loadout-ai@0.1.2` was published publicly on 2026-07-16 while the GitHub
+    repository remained private. Registry metadata, `npx` version/help, and a real
+    read-only Stable preview passed outside the source directory. Patch `0.1.2`
+    adds Codex Desktop detection through its existing `~/.codex` home when the
+    standalone `codex` executable is absent from the user's shell PATH. CI contains an
+    opt-in OS/Node matrix and OIDC/provenance release workflow; clean independent-user
+    installs on Windows/macOS/Linux remain required.
 - [ ] `P12-32 [HUMAN]` Run moderated founder testing on the real Claude and Codex
       profiles with snapshots and explicit rollback checkpoints.
+  - Partial 2026-07-16: the founder ran the published npm CLI against the real macOS
+    profile. Read-only doctor/scan/status/health and snapshot listing completed; the
+    run exposed and regression-tested the Codex Desktop detection fix. A real Stable
+    mutation and rollback remain pending.
 - [ ] `P12-33 [HUMAN]` Run at least ten external user tests spanning new users, power
       users, Windows, macOS, Linux, one-agent, and multi-agent setups.
 - [ ] `P12-34 [SOL]` Public-beta go/no-go review.
@@ -1053,7 +1059,7 @@ universal or permanent truth.
     record.
 - [x] `P13-03 [LUNA]` Rebuild the README and credit every reviewed upstream source.
   - The README is CLI-first, accurately distinguishes preview/network/mutation
-    boundaries, links the daily candidate feed, and avoids claiming npm publication.
+    boundaries, links the daily candidate feed, and records npm publication accurately.
   - `docs/CATALOG.md` links all 50 repositories and all 50 immutable reviewed commits;
     CI prevents silent attribution drift and identifies six `NOASSERTION` records for
     human legal review.
@@ -1156,6 +1162,10 @@ universal or permanent truth.
     1,000 on-disk skills at a 1.29-second p95 on macOS/Node 23.
 - [ ] `P15-06 [HUMAN]` Approve public repository visibility, complete the six
       `NOASSERTION` license decisions, authenticate npm, and publish `loadout-ai`.
+  - Partial 2026-07-16: npm authentication and the public `loadout-ai@0.1.2`
+    publication succeeded. Repository visibility remains private at the owner's
+    request, and the six root-level `NOASSERTION` decisions remain a human release
+    gate; therefore this combined item is not ticked.
 - [x] `P15-07A [TERRA]` Run the hosted macOS/Windows/Linux Node matrix.
   - GitHub Actions run `29502324100` passes fast verification, dashboard browser
     diagnostics, and native install/package flows on Windows, macOS, and Ubuntu with

package/README.md

@@ -6,7 +6,7 @@ Loadout turns the fragmented world of Agent Skills, MCP servers, plugins, and ag
 
 It supports Codex, Claude Code, Cursor, Gemini CLI, OpenCode, Hermes, Windsurf, Cline, GitHub Copilot, Roo Code, Kiro CLI, and Junie on macOS, Linux, and Windows.
 
-> Loadout is in open-source beta and **has not been published to npm yet**. Use `npx .` from a clone today. The intended post-publication command is `npx loadout-ai`; the installed executable will be `loadout`.
+> Loadout is available as a public npm beta: `npm install --global loadout-ai`. The source repository remains private during hackathon testing, while the npm package includes the CLI, documentation, catalog, license, and upstream credit links.
 
 ## Why Loadout exists
 
@@ -26,22 +26,19 @@ Loadout gives you:
 
 Loadout does not claim there is one universally “best” configuration. It makes the evidence, trade-offs, and exact filesystem plan visible so the user can decide.
 
-## Run it locally
+## Install from npm
 
-Requirements: Git and Node.js 20 or newer.
+Requirements: Git and Node.js 20 or newer. Pin `0.1.2` while testing the beta so every machine runs the same bytes.
 
 ```bash
-git clone https://github.com/VirajMishra1/loadout.git
-cd loadout
-npm ci
-npm run build
-npx . --help
+npm install --global loadout-ai@0.1.2
+loadout --help
 ```
 
 Start with the unified read-only preview:
 
 ```bash
-npx . upgrade
+loadout upgrade
 ```
 
 `upgrade` detects installed agents, inventories health, scores only evidence it can prove, scans the current project, recommends reviewed sources, fetches exact pinned commits, and prints every target and risk finding. Nothing changes until `--yes` is supplied.
@@ -50,20 +47,20 @@ npx . upgrade
 
 ```bash
 # 1. Preview the strongest low-risk Stable journey. Read-only.
-npx . upgrade --mode stable --project .
+loadout upgrade --mode stable --project .
 
 # 2. Apply exactly the displayed transaction.
-npx . upgrade --mode stable --project . --yes
+loadout upgrade --mode stable --project . --yes
 
 # 3. Inspect and optimize the active set for this project.
-npx . library
-npx . optimize --project .
-npx . optimize --project . --yes
+loadout library
+loadout optimize --project .
+loadout optimize --project . --yes
 
 # 4. Explain health evidence, share a private aggregate card, or undo.
-npx . health --explain
-npx . card
-npx . rollback
+loadout health --explain
+loadout card
+loadout rollback
 ```
 
 `setup`, `scan`, `recommend`, and the other constituent commands remain available for advanced use. `upgrade --json` provides the same deterministic preview for automation.
@@ -73,7 +70,7 @@ npx . rollback
 For a real install-and-rollback exercise that cannot touch your profile:
 
 ```bash
-npx . demo
+loadout demo
 ```
 
 The demo creates a temporary virtual Codex profile, fetches the pinned public Superpowers source, installs discovered skills, verifies managed state, rolls back, and deletes the temporary directory.
@@ -90,10 +87,10 @@ The demo creates a temporary virtual Codex profile, fetches the pinned public Su
 Maximum is a library, not an instruction to activate everything. Use `optimize`, `activate`, `enable`, and `disable` to keep each agent's active set bounded and relevant to the current project. Loadout warns when an active set exceeds 30 skills per agent.
 
 ```bash
-npx . setup --mode maximum
-npx . setup --mode maximum --yes --approve-risk
-npx . optimize --project . --limit 30
-npx . optimize --project . --limit 30 --yes
+loadout setup --mode maximum
+loadout setup --mode maximum --yes --approve-risk
+loadout optimize --project . --limit 30
+loadout optimize --project . --limit 30 --yes
 ```
 
 ## Install a reviewed runtime tool: Graphify
@@ -104,17 +101,17 @@ Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/) first, t
 
 ```bash
 # See every reviewed executable recipe.
-npx . tool
+loadout tool
 
 # Preview the exact artifact, commands, permissions, and Codex target.
-npx . tool graphify --agents codex
+loadout tool graphify --agents codex
 
 # Apply only after reviewing the preview.
-npx . tool graphify --agents codex --yes --approve-risk
+loadout tool graphify --agents codex --yes --approve-risk
 
 # Preview and then remove it, restoring the pre-install snapshot.
-npx . tool graphify --remove
-npx . tool graphify --remove --yes --approve-risk
+loadout tool graphify --remove
+loadout tool graphify --remove --yes --approve-risk
 ```
 
 The same recipe has reviewed registration targets for Claude Code, Cursor, Gemini CLI, OpenCode, Hermes, GitHub Copilot, and Kiro CLI. Pass a comma-separated list such as `--agents codex,claude-code`; Loadout refuses requested agents it cannot detect.
@@ -124,10 +121,10 @@ The same recipe has reviewed registration targets for Claude Code, Cursor, Gemin
 The bundled catalog currently contains **50 credited public repositories** across **37 categories**: **31 have skill components** and **19 are MCP-only**. All 50 are technically screened and pinned; four sources currently satisfy the stricter Stable recommendation policy. See every linked source, license status, component type, and pinned commit in **[Catalog and upstream credits](./docs/CATALOG.md)**.
 
 ```bash
-npx . catalog
-npx . catalog --coverage
-npx . catalog --history superpowers
-npx . search playwright
+loadout catalog
+loadout catalog --coverage
+loadout catalog --history superpowers
+loadout search playwright
 ```
 
 Catalog admission is evidence-based. Every bundled record has an exact GitHub commit and repository-relative component evidence. Loadout reports separate trust stages—`discovered`, `inspected`, `human-reviewed`, `benchmarked`, and `recommended`—instead of calling every pinned record “best.” Stars are one bounded ranking input, not an installation threshold or a substitute for source review. Missing evidence receives no score, archived projects are not auto-selected, and unrelated categories are never presented as head-to-head alternatives.
@@ -147,38 +144,38 @@ Discovery is deliberately separate from installation. It gathers leads and expla
 
 ```bash
 # GitHub defaults to a rolling 180-day discovery window.
-npx . discover --source github
+loadout discover --source github
 
 # Public Hacker News API: current stories that link to GitHub.
-npx . discover --source hacker-news --min-score 20
-npx . discover --source hacker-news --query codex,mcp,agent
+loadout discover --source hacker-news --min-score 20
+loadout discover --source hacker-news --query codex,mcp,agent
 
 # skills.sh install telemetry (requires its request-scoped VERCEL_OIDC_TOKEN,
 # or uses the last complete local cache).
-npx . discover --source skills-sh --limit 50
+loadout discover --source skills-sh --limit 50
 
 # Official MCP Registry identity and distribution metadata.
-npx . discover --source mcp-registry --limit 50
+loadout discover --source mcp-registry --limit 50
 
 # Query all four sources independently and retain partial results.
-npx . discover --source all --queue --json
+loadout discover --source all --queue --json
 
 # Inspect the deduplicated review queue.
-npx . review-queue
+loadout review-queue
 
 # Triage today's generated feed with disclosed evidence.
-npx . candidate list --limit 20
+loadout candidate list --limit 20
 
 # Clone one lead, pin its commit, and statically inspect its real contents.
-npx . candidate inspect owner/repository --output ./candidate-dossier.json
+loadout candidate inspect owner/repository --output ./candidate-dossier.json
 ```
 
 Install both daily read-only jobs with one command:
 
 ```bash
-npx . autopilot --time 09:00       # preview both jobs
-npx . autopilot --time 09:00 --yes # install both native schedules
-npx . autopilot --remove --yes     # remove both schedules
+loadout autopilot --time 09:00       # preview both jobs
+loadout autopilot --time 09:00 --yes # install both native schedules
+loadout autopilot --remove --yes     # remove both schedules
 ```
 
 Autopilot installs native schedules on macOS, Linux, and Windows using the pinned npm launcher for this Loadout version. It refreshes the local discovery/review queue and checks pinned package updates every day. It never installs a candidate, promotes a catalog record, or applies an update without a later explicit command and approval. Catalog membership changes only through a verified signed release.
@@ -190,12 +187,12 @@ Candidates stay in the review queue until a human decision. Shortlisting is not
 After a human reviews that dossier, Loadout can create a catalog-record proposal without editing the catalog:
 
 ```bash
-npx . candidate propose ./candidate-dossier.json \
+loadout candidate propose ./candidate-dossier.json \
   --id reviewed-id --category workflow \
   --platforms windows,macos,linux
 
 # Persist only after human review; this still does not mutate the catalog.
-npx . candidate propose ./candidate-dossier.json \
+loadout candidate propose ./candidate-dossier.json \
   --id reviewed-id --category workflow \
   --platforms windows,macos,linux \
   --approve --output ./reviewed-id.proposal.json
@@ -206,13 +203,13 @@ See [Candidate intelligence and catalog trust](./docs/CANDIDATE_INTELLIGENCE.md)
 ## Know what is already installed
 
 ```bash
-npx . status
-npx . versions
-npx . doctor
-npx . health --explain
-npx . capabilities
-npx . compare <skill-name>
-npx . adopt <skill-name> --agent codex
+loadout status
+loadout versions
+loadout doctor
+loadout health --explain
+loadout capabilities
+loadout compare <skill-name>
+loadout adopt <skill-name> --agent codex
 ```
 
 `versions` invokes only bounded read-only `--version` commands with a sanitized environment. `health --explain` shows every scored dimension, cap, evidence item, uncertainty, and remediation; absent evidence receives zero rather than an invented neutral score.
@@ -224,14 +221,14 @@ npx . adopt <skill-name> --agent codex
 The cache, reviewed library, installed state, and active agent directories are separate states. Loadout can therefore retain a broad reviewed library while exposing only a small working set.
 
 ```bash
-npx . recommend --project .
-npx . activate --project . --limit 30
-npx . optimize --project .
-npx . optimize --project . --yes
-npx . disable <package-or-package/skill>
-npx . disable <package-or-package/skill> --yes
-npx . enable <package-or-package/skill>
-npx . enable <package-or-package/skill> --yes
+loadout recommend --project .
+loadout activate --project . --limit 30
+loadout optimize --project .
+loadout optimize --project . --yes
+loadout disable <package-or-package/skill>
+loadout disable <package-or-package/skill> --yes
+loadout enable <package-or-package/skill>
+loadout enable <package-or-package/skill> --yes
 ```
 
 Dry-run is the default for mutations. Activation refuses unmanaged packages, drifted files, incomplete library copies, quarantined entries, and occupied targets.
@@ -246,19 +243,19 @@ Loadout separates four actions that other installers often blur together:
 4. optionally launch one exact reviewed artifact for a bounded JSON-RPC connection check.
 
 ```bash
-npx . mcp --repository upstash/context7
-npx . mcp-recipe playwright --config ./mcp.json
-npx . mcp-recipe playwright --config ./mcp.json --verify
-npx . mcp-recipe playwright --connect --approve-risk
+loadout mcp --repository upstash/context7
+loadout mcp-recipe playwright --config ./mcp.json
+loadout mcp-recipe playwright --config ./mcp.json --verify
+loadout mcp-recipe playwright --connect --approve-risk
 ```
 
 Credential-bearing recipes can reference the native OS credential store. Secrets are accepted through stdin, never written into Loadout JSON state, and injected only into the approved child process:
 
 ```bash
 printf '%s' "$GITHUB_PERSONAL_ACCESS_TOKEN" \
-  | npx . credentials set loadout.github --stdin
+  | loadout credentials set loadout.github --stdin
 
-npx . mcp-recipe github-readonly --connect --approve-risk \
+loadout mcp-recipe github-readonly --connect --approve-risk \
   --credential GITHUB_PERSONAL_ACCESS_TOKEN=keychain:loadout.github
 ```
 
@@ -267,14 +264,14 @@ Native backends are macOS Keychain, Linux Secret Service, and Windows Credential
 ## Reproducible team loadouts
 
 ```bash
-npx . init --name my-team
-npx . add superpowers
-npx . lock
-npx . sync --manifest loadout.json       # preview
-npx . sync --manifest loadout.json --yes # apply transactionally
-npx . audit --manifest loadout.json --lock loadout.lock
-npx . export team.loadout.json --manifest loadout.json --lock loadout.lock
-npx . import team.loadout.json            # preview
+loadout init --name my-team
+loadout add superpowers
+loadout lock
+loadout sync --manifest loadout.json       # preview
+loadout sync --manifest loadout.json --yes # apply transactionally
+loadout audit --manifest loadout.json --lock loadout.lock
+loadout export team.loadout.json --manifest loadout.json --lock loadout.lock
+loadout import team.loadout.json            # preview
 ```
 
 Manifests resolve catalog packages, Git repositories, local sources, and exact registry descriptors. Dependency cycles, incompatible versions, missing requirements, unsafe paths, and portable exports containing absolute local package paths are rejected. Imports do not silently replace files and snapshot destinations before an approved overwrite.
@@ -282,12 +279,12 @@ Manifests resolve catalog packages, Git repositories, local sources, and exact r
 ## Updates, evidence, and recovery
 
 ```bash
-npx . alerts
-npx . update
-npx . update --package <package-id> --apply
-npx . watch
-npx . rollback
-npx . audit --manifest loadout.json --lock loadout.lock
+loadout alerts
+loadout update
+loadout update --package <package-id> --apply
+loadout watch
+loadout rollback
+loadout audit --manifest loadout.json --lock loadout.lock
 ```
 
 Updates are planned before they are applied. Loadout checks managed hashes, reviewed commits, archive status, staleness evidence, permission changes, and replacement evidence. It will not treat a newer commit or a faster-growing repository as automatically safer or better.
@@ -299,8 +296,8 @@ Updates are planned before they are applied. Loadout checks managed hashes, revi
 Loadout now includes the versioned [Evaluation Protocol v1](./docs/EVALUATION_PROTOCOL_V1.md). A campaign can be validated, deterministically scheduled, and worst-case priced without contacting a model provider:
 
 ```bash
-npx . benchmark plan ./campaign.json
-npx . benchmark plan ./campaign.json \
+loadout benchmark plan ./campaign.json
+loadout benchmark plan ./campaign.json \
   --run-id first-run --output ./benchmark-run.json --json
 ```
 
@@ -309,10 +306,10 @@ Planning rejects unbounded or edited metadata and writes a resumable, content-fr
 Generate or compare privacy-safe aggregate artifacts:
 
 ```bash
-npx . report --json > before.json
-npx . card --output LOADOUT_CARD.md
-npx . report --json > after.json
-npx . compare-loadouts before.json after.json
+loadout report --json > before.json
+loadout card --output LOADOUT_CARD.md
+loadout report --json > after.json
+loadout compare-loadouts before.json after.json
 ```
 
 The card excludes project paths and names, prompts, code, filenames, repository names, and credentials. Its Agent Health Score reports evidence coverage and explicitly does not claim universal quality or task improvement.
@@ -334,7 +331,7 @@ The card excludes project paths and names, prompts, code, filenames, repository
 | Kiro CLI       | Yes, at `~/.kiro/skills`               | Skills only                                                                                    |
 | Junie          | Yes, at `~/.junie/skills`              | Skills only                                                                                    |
 
-Run `npx . capabilities` for the authoritative `native`, `adapted`, or `unsupported` matrix used by the planner itself. `npx . capabilities --gaps` turns every unsupported combination into an evidence-gated engineering backlog; unsupported components are skipped rather than falsely converted.
+Run `loadout capabilities` for the authoritative `native`, `adapted`, or `unsupported` matrix used by the planner itself. `loadout capabilities --gaps` turns every unsupported combination into an evidence-gated engineering backlog; unsupported components are skipped rather than falsely converted.
 
 macOS, Linux, and native Windows paths are supported. WSL is intentionally treated as Linux and uses its POSIX `$HOME`; Loadout never silently crosses into the Windows profile under `/mnt/c`. `LOADOUT_USER_HOME` and `LOADOUT_HOME` provide isolated roots for testing.
 
@@ -369,10 +366,10 @@ Read [Compatibility policy](./docs/COMPATIBILITY_POLICY.md), [Active-set contrac
 | Package and registry   | `create`, `pack`, `publish`, `registry-serve`                                        |
 | Operate                | `completion`, `autopilot`, `schedule`, `unschedule`, `tool`, `dashboard`, `serve`    |
 
-Use `npx . <command> --help` for exact options. Shell completion is available for Bash, Zsh, Fish, and PowerShell:
+Use `loadout <command> --help` for exact options. Shell completion is available for Bash, Zsh, Fish, and PowerShell:
 
 ```bash
-npx . completion zsh > ~/.zfunc/_loadout
+loadout completion zsh > ~/.zfunc/_loadout
 ```
 
 ## How it works

package/dist/src/cli.js

@@ -221,7 +221,7 @@ async function runSetup(options) {
         reader?.close();
     }
 }
-const LOADOUT_VERSION = "0.1.0";
+const LOADOUT_VERSION = "0.1.2";
 function durableSchedulerLauncher() {
     return [
         join(dirname(process.execPath), process.platform === "win32" ? "npx.cmd" : "npx"),

package/dist/src/core/paths.js

@@ -15,6 +15,10 @@ export const AGENT_DEFINITIONS = [
         displayName: "Codex",
         binary: "codex",
         directory: [".agents", "skills"],
+        // Codex Desktop owns ~/.codex even when the standalone `codex` binary is
+        // not exposed on the shell PATH. The shared Agent Skills root (~/.agents)
+        // is also valid evidence when it already exists.
+        detectionDirectories: [[".codex"], [".agents"]],
     },
     {
         id: "cursor",

package/package.json

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