loadout-ai 0.2.2 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.3.1 - 2026-07-18
+
+### Fixed
+
+- Distinguish separately billed AI/model API keys from unrelated service credentials.
+  The no-model-key MCP view now correctly includes GitHub read-only while clearly
+  disclosing its GitHub token requirement; `--credential-free` retains the stricter
+  zero-credential filter.
+
+## 0.3.0 - 2026-07-18
+
+### Added
+
+- Add a preview-first `loadout uninstall` that removes managed packages, runtime
+  tools, native daily jobs, library/cache/state, and optionally the global npm CLI.
+- Save the installed Stable, Power, Maximum, or Custom profile and evaluate it on
+  every `loadout update` check.
+- Add explicit whole-profile `loadout update --yes` for reviewed profile drift and
+  safe active-package updates, holding disabled or risky changes for review.
+- Add a pinned Chrome DevTools MCP recipe and `mcp-recipe --no-key` alongside
+  Playwright MCP.
+
+### Changed
+
+- Daily update jobs use the unified profile-and-package update check while remaining
+  read-only.
+- Bound large update checks to four repositories at a time and 30 seconds per network
+  operation, with readable progress in interactive CLI output.
+
+## 0.2.3 - 2026-07-17
+
+### Fixed
+
+- Validate large rollback snapshots in linear, constant-stack time so project-aware activation can safely snapshot large reviewed skills.
+- Preserve strict malformed-base64 rejection without relying on a stack-intensive regular expression.
+- Rewrite every generated Graphify top-level lookup, repair, and optional Gemini install to the reviewed hashed artifact instead of leaving unpinned package fallbacks.
+
 ## 0.2.2 - 2026-07-17
 
 ### Fixed

package/MASTER_PLAN.md

@@ -6,6 +6,66 @@ Category: Developer Tools
 Team size: 3  
 Target submission: July 21, 2026 at 5:00 PM Pacific / July 22 at 4:00 AM Dubai
 
+## Current remaining work (July 18, 2026)
+
+This is the authoritative active list. The long phase history below is retained as
+an engineering record, not a command to build every speculative system before users
+can test Loadout.
+
+### Required before calling the CLI polished for public testing
+
+- [x] `P18-01 [TERRA]` Make the first CLI screen beginner-readable: a read-only
+      `loadout guide`, concise default library summary, focused first-screen help,
+      and retained access to every advanced command through `loadout advanced` or
+      `<command> --help`.
+- [x] `P18-02 [TERRA]` Make core machine output honest: `catalog --json` returns
+      JSON, and `update --package <id>` checks only that package rather than every
+      tracked installation.
+- [ ] `P18-03 [HUMAN+TERRA]` Run the founder acceptance path in
+      `docs/USER_TEST_GUIDE.md` on the real Codex and Claude profiles. Record each
+      observed failure and turn reproducible ones into regression tests.
+- [x] `P18-04 [TERRA]` Bound and explain live network checks in `health --updates`
+      and `watch --once`; they must show progress, a clear timeout, and an actionable
+      result even when a large Maximum library is present.
+- [x] `P18-05 [TERRA]` Make Agent Health distinguish active skills from disabled
+      Maximum-library copies, so a broad download is not presented as a broken active
+      configuration.
+- [x] `P18-06 [TERRA+LUNA]` Audit the local dashboard with real founder state at
+      desktop and mobile widths. Keep it optional, reduce jargon, and only add UI
+      actions that retain preview, explicit acknowledgement, snapshot, and rollback.
+- [x] `P18-07 [TERRA]` Add a concise beginner section to README that links to the
+      testing guide and explains Stable, Power, Maximum, project recommendations,
+      daily discovery, and rollback in plain language.
+- [ ] `P18-08 [HUMAN+TERRA]` Run the full verification gate, publish the next npm
+      patch/minor only after founder acceptance, and test that exact tarball in a
+      fresh terminal.
+
+### Release 0.3 lifecycle hardening
+
+- [x] `P18-09 [SOL+TERRA]` Add preview-first complete uninstall with modified-file
+      protection, native-job cleanup, runtime restoration, guarded state deletion,
+      and optional global npm removal.
+- [x] `P18-10 [TERRA]` Persist the installed profile and make `loadout update`
+      evaluate both profile drift and every managed repository.
+- [x] `P18-11 [SOL+TERRA]` Add explicit bulk safe updates while holding disabled,
+      risky, and failed packages for review; scheduled checks remain read-only.
+- [x] `P18-12 [TERRA]` Add a pinned Chrome DevTools MCP recipe and distinguish
+      separately billed AI/model API keys from unrelated service credentials. The
+      no-model-key inventory includes GitHub read-only with its token disclosed.
+- [ ] `P18-13 [HUMAN+TERRA]` Publish `0.3.1`, then run Stable -> rollback -> Power ->
+      rollback -> Maximum -> project optimization -> dashboard -> complete uninstall
+      against the exact npm package.
+
+### Explicitly deferred (do not expand during this usability pass)
+
+- Hosted accounts, GitHub OAuth, cloud sync, analytics, and enterprise policy.
+- Required API keys, automatic provider spending, or treating chat subscriptions as
+  API access.
+- Automatically installing newly discovered repositories or executing arbitrary
+  third-party installers.
+- A universal quality score, social-network scraping, or support claims for an agent
+  that has not passed a real adapter test.
+
 ## 1. Executive summary
 
 Loadout is a universal extension manager for AI coding agents. It detects the agents
@@ -91,12 +151,11 @@ Loadout wins through:
 - Optional local-folder scan for project-aware recommendations.
 - Clear display of `native`, `adapted`, and `unsupported` components.
 
-### 3.2 Committed full-product scope
+### 3.2 Deferred product exploration (not current launch scope)
 
-These are committed capabilities, not disposable ideas. The team attempts them after
-the submission-critical vertical slice is integrated and passing. Any capability that
-is incomplete at submission must remain behind an experimental flag rather than being
-presented as production-ready.
+These are ideas worth revisiting after the core CLI has passed real founder and
+external user testing. They are not commitments for this hackathon release and must
+not be presented as production-ready simply because a prototype or command exists.
 
 - GitHub OAuth for private repositories and personalized discovery, using minimal
   read-only scopes by default.
@@ -1773,31 +1832,7 @@ small PRs, no long-lived branches.
 
 ## 25. Immediate next tasks
 
-The next engineering wave deliberately precedes npm, Devpost, and repository-visibility
-work. Preserve the Sol/Terra/Luna routing and credit policy above.
-
-1. `P16-02/03`: add a concrete disposable fixture executor and one explicit provider
-   adapter only after the user supplies separate API credit and approves the exact
-   maximum spend. Run provider reconciliation and the hosted Linux/Windows matrix; do
-   not turn Codex subscription or hackathon credit into an assumed API budget.
-2. `P16-04/05`: execute at least five real paired trials per compared candidate, review
-   failures and contamination, sign the resulting evidence, and obtain genuine human
-   license/trust approval before any `benchmarked` or `recommended` transition.
-3. `P16-12`: generate the production Ed25519 key outside the repository, configure the
-   public feed location and secret-backed daily publisher, test first-pin/rotation/
-   recovery operationally, and publish no private or unsigned artifact.
-4. `P16-14`: run the beginner comprehension session for card/compare/badge wording and
-   convert every reproducible misunderstanding into a fixture or copy regression.
-5. `P16-15`: independently review usefulness, license, security, dependencies,
-   Windows behavior, rollback, and removal for a second runtime tool before admission.
-6. `P16-16`: run founder testing first, then implement only observed adapter gaps with
-   official-source evidence, preservation fixtures, transaction coverage, and a real
-   disposable smoke test.
-7. `P16-18`: run the full founder matrix on disposable profiles before the real Codex
-   and Claude profiles, followed by ten external sessions across experience levels and
-   Windows/macOS/Linux. Convert reproducible failures into regression tests.
-8. Rerun `npm run verify`, the complete disposable feature matrix, npm dry-run, hosted
-   cross-platform jobs, and clean external tarball installs after those external gates.
-9. Human release work remains last: P12-30 license decisions, P15-06 public visibility
-   and npm publication, P15-07B clean external installs, branch protection, demo/video,
-   feedback, Devpost fields, and final review.
+Use the `Current remaining work` section at the top of this document. The next action
+is founder acceptance testing with `docs/USER_TEST_GUIDE.md`; do not add a new hosted
+service, provider dependency, or frontend surface until an observed user-testing issue
+justifies it.

package/README.md

@@ -11,7 +11,7 @@ It solves a simple problem: useful skills and MCP tools are scattered across hun
 You need Node.js 20 or newer and Git.
 
 ```bash
-npm install --global loadout-ai@0.2.0
+npm install --global loadout-ai@0.3.1
 loadout --version
 loadout upgrade
 ```
@@ -30,6 +30,19 @@ Every applied change creates a snapshot. Undo the latest change with:
 loadout rollback
 ```
 
+Remove one package with `loadout remove <package>`. Remove everything Loadout owns
+with a preview-first command:
+
+```bash
+loadout uninstall
+loadout uninstall --yes
+loadout uninstall --yes --remove-cli
+```
+
+The first command changes nothing. Complete uninstall preserves unmanaged files and
+stops if a Loadout-managed file contains your edits unless you explicitly add
+`--force`.
+
 ## Choose how much you want
 
 | Mode        | Best for                                     | What happens                                                                                                                                            |
@@ -126,6 +139,11 @@ loadout alerts --updates
 loadout update
 ```
 
+`loadout update` checks the saved Stable, Power, Maximum, or Custom profile plus every
+managed repository. It is read-only. `loadout update --yes` applies reviewed profile
+changes and safe screened updates; anything disabled, risky, or failed is held for
+review. Daily checks never include `--yes`.
+
 The wording matters:
 
 - A **new lead** is interesting enough to inspect, not “must install.”
@@ -166,6 +184,18 @@ loadout setup --mode maximum --api-access openai,anthropic
 
 Loadout never treats API access as permission to install an MCP server. Credentialed MCP tools remain explicit setup steps, and configuration stores an environment-variable or OS-keychain reference rather than the secret value.
 
+See the reviewed MCP recipes that need no separately billed AI/model API key:
+
+```bash
+loadout mcp-recipe --no-key
+```
+
+This includes Playwright MCP, Chrome DevTools MCP, and GitHub's read-only MCP. Loadout
+shows non-AI credentials separately: GitHub MCP needs a GitHub token, while the two
+browser recipes need no credential. Use `loadout mcp-recipe --credential-free` for the
+stricter zero-credential list. Browser control and service authorization remain
+explicit.
+
 ```bash
 export LOADOUT_GITHUB_TOKEN="$GITHUB_PERSONAL_ACCESS_TOKEN"
 
@@ -206,7 +236,9 @@ Executable tools and MCP servers receive separate treatment because they can run
 | Read the discovery queue                  | `loadout review-queue`                        |
 | Check installed changes                   | `loadout alerts --updates`                    |
 | Preview updates                           | `loadout update`                              |
+| Apply all safe reviewed updates           | `loadout update --yes`                        |
 | Undo the latest applied change            | `loadout rollback`                            |
+| Completely remove Loadout                 | `loadout uninstall`                           |
 | Test safely without touching your profile | `loadout demo`                                |
 | See every command                         | `loadout --help`                              |
 

package/dist/src/cli.js

@@ -12,13 +12,15 @@ import { fetchRepositorySnapshot } from "./core/source.js";
 import { discoverMcpManifests, summarizeMcpManifest, planMcpConfig, summarizeMcpConfigPlan, applyMcpConfigPlan, } from "./core/mcp.js";
 import { REVIEWED_MCP_RECIPES, findMcpRecipe, formatMcpRecipePlan, planMcpRecipe, verifyMcpRecipe, verifyMcpRecipeConnection, } from "./core/mcp-recipes.js";
 import { runDoctor, formatDoctorReport } from "./core/doctor.js";
-import { applyPackageUpdate, buildUpdatePlan, formatUpdatePlan, } from "./core/update.js";
+import { applyPackageUpdate, buildUpdatePlan, formatUpdatePlan, selectSafeAutomaticUpdates, } from "./core/update.js";
 import { startApiServer } from "./core/api.js";
 import { inspectPackage, formatPackageInspection } from "./core/package.js";
 import { addManifestPackage, applyProfileToManifest, initManifest, readManifest, removeManifestPackage, writeLockfile, } from "./core/manifest.js";
 import { buildHealthReport, formatHealthReport } from "./core/health.js";
-import { readInstallState } from "./core/state.js";
+import { readInstallState, recordInstallTransaction } from "./core/state.js";
 import { applyRemove, planRemove } from "./core/remove.js";
+import { applyUninstall, buildUninstallPlan, formatUninstallPlan, uninstallGlobalCli, } from "./core/uninstall.js";
+import { evaluateInstalledProfile, formatInstalledProfileStatus, recordInstalledProfile, } from "./core/profile-state.js";
 import { formatRecommendations, personalizeRecommendations, profileManifestPackages, recommendPackages, scanProject, TESTED_PROFILES, } from "./core/recommend.js";
 import { buildImprovementCycle, formatImprovementCycle, recordImprovementOutcome, writeImprovementCycle, } from "./core/improve.js";
 import { applySyncPlan, buildSyncPlan } from "./core/sync.js";
@@ -47,7 +49,7 @@ import { applyPreparedCatalogInstall, formatPreparedCatalogInstall, prepareCatal
 import { formatInstalledSkillInventory, scanInstalledSkills, } from "./core/skill-inventory.js";
 import { enrichInventoryWithProvenance, formatProvenanceSummary, resolveCatalogSkillIndex, } from "./core/provenance.js";
 import { compareSkill, formatSkillComparison } from "./core/skill-compare.js";
-import { applyActivationChange, buildLibraryStateReport, formatActivationPlan, formatLibraryStateReport, planActivationChange, } from "./core/active-set.js";
+import { applyActivationChange, buildLibraryStateReport, formatActivationPlan, formatLibrarySummary, formatLibraryStateReport, planActivationChange, } from "./core/active-set.js";
 import { applyProjectActivation, formatProjectActivation, planProjectActivation, } from "./core/active-policy.js";
 import { applySkillAdoption, formatAdoptionPlan, planSkillAdoption, } from "./core/adopt.js";
 import { formatReviewQueue, mergeReviewQueue, readReviewQueue, setReviewDecision, } from "./core/review-queue.js";
@@ -79,6 +81,7 @@ import { applyIntelligenceFeed, previewIntelligenceFeed, readCachedIntelligenceF
 import { scanSkillSecurity } from "./core/skill-security.js";
 import { planApmImportFiles, planOpenPackageImportFiles, } from "./core/ecosystem-import.js";
 import { buildCompatibilityIntelligence, parseCompatibilityNoticeSet, } from "./core/compatibility-intelligence.js";
+import { ADVANCED_GUIDE, BEGINNER_GUIDE, HIDDEN_FROM_FIRST_SCREEN, } from "./core/cli-guide.js";
 const collectOption = (value, previous = []) => [
     ...previous,
     value,
@@ -255,6 +258,7 @@ async function runSetup(options) {
         const snapshotId = await applyPreparedCatalogInstall(prepared, {
             approveRisk: riskApproved,
         });
+        await recordInstalledProfile(prepared);
         console.log(`\nLoadout installed ${prepared.entries.length} repositories for ${prepared.agents.length} agent(s). Snapshot: ${snapshotId}`);
         console.log("Next: `loadout status`, `loadout optimize --project .`, or `loadout autopilot --yes` for opt-in daily read-only discovery and update checks.");
     }
@@ -262,7 +266,7 @@ async function runSetup(options) {
         reader?.close();
     }
 }
-const LOADOUT_VERSION = "0.2.2";
+const LOADOUT_VERSION = "0.3.1";
 function durableSchedulerLauncher() {
     return [
         join(dirname(process.execPath), process.platform === "win32" ? "npx.cmd" : "npx"),
@@ -271,6 +275,9 @@ function durableSchedulerLauncher() {
     ];
 }
 const program = new Command();
+function printBeginnerGuide() {
+    console.log(BEGINNER_GUIDE);
+}
 program
     .name("loadout")
     .description("The trusted upgrade layer for AI coding agents")
@@ -285,6 +292,14 @@ program
     // writes its own parse error first, producing two stderr documents and
     // breaking --json-errors consumers.
     .configureOutput({ writeErr: () => undefined });
+program
+    .command("guide")
+    .description("Show the simple, read-only path for using Loadout")
+    .action(printBeginnerGuide);
+program
+    .command("advanced")
+    .description("Explain where to find advanced and maintainer-only commands")
+    .action(() => console.log(ADVANCED_GUIDE));
 program
     .command("setup")
     .description("Preview and install a screened skill loadout for detected agents")
@@ -620,11 +635,14 @@ program
     .command("library")
     .description("Show separate cache, review, installation, and per-agent activation state")
     .option("--json", "emit machine-readable JSON")
+    .option("--all", "show every managed skill and its source package")
     .action(async (options) => {
     const report = await buildLibraryStateReport();
     console.log(options.json
         ? JSON.stringify(report, null, 2)
-        : formatLibraryStateReport(report));
+        : options.all
+            ? formatLibraryStateReport(report)
+            : formatLibrarySummary(report));
 });
 program
     .command("report")
@@ -891,7 +909,17 @@ program
     .option("--explain", "add deterministic score dimensions, evidence, uncertainty, and remediation")
     .option("--agents <ids>", "limit explained scores to selected agent ids")
     .action(async (options) => {
-    const report = await buildHealthReport({ checkUpdates: options.updates });
+    if (options.updates && !options.json)
+        console.error("Checking managed repositories (4 at a time, 30s per network operation)…");
+    const report = await buildHealthReport({
+        updates: options.updates
+            ? () => buildUpdatePlan(undefined, {
+                onProgress: options.json
+                    ? undefined
+                    : ({ completed, total, packageId }) => console.error(`✓ [${completed}/${total}] ${packageId}`),
+            })
+            : undefined,
+    });
     if (options.agents && !options.explain)
         throw new Error("--agents requires --explain");
     const selectedAgents = parseAgentSelection(options.agents);
@@ -985,6 +1013,29 @@ program
     const snapshot = await applyRemove(plan, { force: options.force });
     console.log(`Removed ${packageId}. Snapshot: ${snapshot}`);
 });
+program
+    .command("uninstall")
+    .description("Preview or completely remove Loadout-managed data")
+    .option("--yes", "remove managed data; otherwise show a preview")
+    .option("--force", "also remove managed files changed outside Loadout")
+    .option("--remove-cli", "also uninstall the global loadout-ai npm command")
+    .action(async (options) => {
+    const plan = await buildUninstallPlan();
+    console.log(formatUninstallPlan(plan));
+    if (!options.yes)
+        return;
+    const result = await applyUninstall(plan, undefined, {
+        force: options.force,
+    });
+    console.log(`Removed ${result.removedPackages} managed package(s), ${result.removedRuntimeTools} runtime tool(s), daily jobs, cache, library, and Loadout state.`);
+    if (options.removeCli) {
+        await uninstallGlobalCli();
+        console.log("Removed the global loadout-ai CLI. Open a new shell before checking the command again.");
+    }
+    else {
+        console.log("The CLI is still installed. Remove it too with: npm uninstall -g loadout-ai");
+    }
+});
 program
     .command("recommend")
     .description("Recommend catalog packages from local project signals")
@@ -1520,6 +1571,10 @@ program
             : formatCatalogCoverage(coverage));
         return;
     }
+    if (options.json) {
+        console.log(JSON.stringify(rankCatalog(result.catalog), null, 2));
+        return;
+    }
     for (const pkg of rankCatalog(result.catalog)) {
         const topics = pkg.topics?.length ? ` — ${pkg.topics.join(", ")}` : "";
         const updated = pkg.lastUpdatedAt
@@ -2103,21 +2158,27 @@ program
     .option("--timeout <milliseconds>", "real connection timeout", "8000")
     .option("--approve-risk", "approve launching the reviewed pinned MCP artifact for --connect")
     .option("--json", "emit machine-readable JSON")
+    .option("--no-key", "list recipes needing no separately billed AI/model API key")
+    .option("--no-model-key", "clear alias for --no-key; service tokens may still be required")
+    .option("--credential-free", "list recipes needing no credential of any kind")
     .action(async (id, options) => {
     if (!id) {
         if (options.connect || options.verify || options.yes)
             throw new Error("Select an MCP recipe id for this operation");
-        const listed = REVIEWED_MCP_RECIPES.map((recipe) => ({
+        const selected = REVIEWED_MCP_RECIPES.filter((recipe) => !((options.key === false || options.modelKey === false) &&
+            recipe.modelApiProviders.length > 0) && !(options.credentialFree && recipe.environment.length > 0));
+        const listed = selected.map((recipe) => ({
             id: recipe.id,
             displayName: recipe.displayName,
             source: recipe.source,
             permissions: recipe.permissions,
             environment: recipe.environment,
+            modelApiProviders: recipe.modelApiProviders,
         }));
         console.log(options.json
             ? JSON.stringify(listed, null, 2)
             : listed
-                .map((recipe) => `${recipe.id} — ${recipe.displayName} — env: ${recipe.environment.length ? recipe.environment.join(", ") : "none"}`)
+                .map((recipe) => `${recipe.id} — ${recipe.displayName} — ${recipe.modelApiProviders.length ? `AI API required: ${recipe.modelApiProviders.join(", ")}` : "No AI API key required"} · ${recipe.environment.length ? `${recipe.environment.includes("GITHUB_PERSONAL_ACCESS_TOKEN") ? "GitHub token required" : `service credential required: ${recipe.environment.join(", ")}`}` : "no other credential"}`)
                 .join("\n"));
         return;
     }
@@ -2174,6 +2235,7 @@ program
         return;
     }
     const snapshot = await applyMcpConfigPlan(plan.config);
+    await recordInstallTransaction([], [{ packageId: `mcp-recipe:${id}`, plan: plan.config }], snapshot.id);
     console.log(options.json
         ? JSON.stringify({ plan, snapshot }, null, 2)
         : `${formatMcpRecipePlan(plan)}\nConfigured. Snapshot: ${snapshot.id}\nAuthorize the service separately, then run: loadout mcp-recipe ${id} --config ${plan.config.path} --verify`);
@@ -2534,6 +2596,7 @@ program
         const snapshotId = await applyPreparedCatalogInstall(prepared, {
             approveRisk: options.approveRisk,
         });
+        await recordInstalledProfile(prepared);
         console.log(`Installed ${prepared.entries.length} repositories as one transaction. Snapshot: ${snapshotId}`);
         return;
     }
@@ -2615,23 +2678,104 @@ program
 });
 program
     .command("update")
-    .description("Plan updates, or apply one explicitly selected package update")
+    .description("Check the saved profile and every managed package for updates")
     .option("--json", "emit machine-readable JSON")
-    .option("--apply", "apply the selected update")
+    .option("--yes", "apply reviewed profile drift and safe screened package updates")
+    .option("--apply", "legacy alias for --yes with --package")
     .option("--package <id>", "managed package id to update")
     .option("--approve-risk", "explicitly approve an update containing blocked safety findings")
     .action(async (options) => {
-    if (options.apply) {
-        if (!options.package)
-            throw new Error("--apply requires --package <id>");
+    const applying = Boolean(options.apply || options.yes);
+    if (options.apply && !options.package)
+        throw new Error("--apply requires --package <id>");
+    if (applying && options.package) {
         const result = await applyPackageUpdate(options.package, {
             approveRisk: options.approveRisk,
         });
-        console.log(`Updated ${options.package} to ${result.commit}. Snapshot: ${result.snapshotId}`);
+        console.log(options.json
+            ? JSON.stringify({ packageId: options.package, ...result }, null, 2)
+            : `Updated ${options.package} to ${result.commit}. Snapshot: ${result.snapshotId}`);
         return;
     }
-    const plans = await buildUpdatePlan();
-    console.log(options.json ? JSON.stringify(plans, null, 2) : formatUpdatePlan(plans));
+    const catalog = await loadEffectiveCatalog();
+    let profile = await evaluateInstalledProfile(catalog);
+    let profileSnapshotId;
+    const appliedPackages = [];
+    const failedPackages = [];
+    if (applying && profile.installed && profile.needsRefresh) {
+        const saved = (await readInstallState()).profile;
+        const prepared = await prepareCatalogInstall({
+            mode: saved.mode,
+            ...(saved.packageIds ? { packageIds: saved.packageIds } : {}),
+        }, {
+            requestedAgents: saved.agents,
+            catalog,
+            access: { modelApis: [] },
+            onProgress: printSetupProgress,
+        });
+        profileSnapshotId = await applyPreparedCatalogInstall(prepared, {
+            approveRisk: options.approveRisk,
+        });
+        await recordInstalledProfile(prepared);
+        if (!options.json)
+            console.log(`Applied reviewed ${saved.mode} profile changes. Snapshot: ${profileSnapshotId}`);
+        profile = await evaluateInstalledProfile(catalog);
+    }
+    if (!options.json)
+        console.error("Checking managed repositories (4 at a time, 30s per network operation)…");
+    let plans = await buildUpdatePlan(undefined, {
+        packageId: options.package,
+        onProgress: options.json
+            ? undefined
+            : ({ completed, total, packageId }) => console.error(`✓ [${completed}/${total}] ${packageId}`),
+    });
+    if (options.package && plans.length === 0)
+        throw new Error(`No Loadout-managed installation named '${options.package}' was found. Run \`loadout list\` to see tracked packages.`);
+    if (applying) {
+        const safe = selectSafeAutomaticUpdates(plans);
+        for (const plan of safe)
+            try {
+                await applyPackageUpdate(plan.packageId);
+                appliedPackages.push(plan.packageId);
+            }
+            catch (error) {
+                failedPackages.push({
+                    packageId: plan.packageId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        plans = await buildUpdatePlan(undefined, {
+            onProgress: options.json
+                ? undefined
+                : ({ completed, total, packageId }) => console.error(`✓ [${completed}/${total}] ${packageId}`),
+        });
+        if (!options.json) {
+            console.log(appliedPackages.length
+                ? `Updated safely: ${appliedPackages.join(", ")}`
+                : "No safe active package update needed applying.");
+            for (const item of failedPackages)
+                console.log(`Could not update ${item.packageId}: ${item.error}`);
+            const held = plans.filter((plan) => plan.status === "update-available" &&
+                (plan.approvalRequired || plan.disabledAgents?.length));
+            if (held.length)
+                console.log(`Held for explicit review: ${held.map((item) => item.packageId).join(", ")}`);
+        }
+    }
+    console.log(options.json
+        ? JSON.stringify({
+            profile,
+            packages: plans,
+            ...(applying
+                ? {
+                    applied: {
+                        profileSnapshotId,
+                        packages: appliedPackages,
+                        failures: failedPackages,
+                    },
+                }
+                : {}),
+        }, null, 2)
+        : `${formatInstalledProfileStatus(profile)}\n\n${formatUpdatePlan(plans)}`);
 });
 program
     .command("convert")
@@ -2732,7 +2876,14 @@ program
     });
     await handle.close();
 });
-program.action(() => runSetup({ package: [] }));
+for (const command of program.commands)
+    // Commander supports `hidden` when a command is created. These commands are
+    // registered by separate feature blocks, so use the same runtime flag here
+    // rather than `Option#hideHelp`, which does not exist on Command objects.
+    if (HIDDEN_FROM_FIRST_SCREEN.has(command.name()))
+        command._hidden = true;
+program.addHelpText("after", "\nStart here: `loadout guide` shows the safe everyday path. `loadout advanced` lists the retained maintainer and integration commands.\n");
+program.action(printBeginnerGuide);
 try {
     await recoverPendingTransactions();
     await program.parseAsync();

package/dist/src/core/active-set.js

@@ -156,9 +156,13 @@ async function activeTreeFiles(targets) {
 export async function buildLibraryStateReport() {
     const state = await readInstallState();
     const records = allActivationRecords(state.installs, state.activations ?? []);
+    const repositories = Object.fromEntries(state.installs
+        .filter((install) => Boolean(install.repository))
+        .map((install) => [install.packageId, install.repository]));
     return {
         generatedAt: new Date().toISOString(),
         records,
+        repositories,
         counts: {
             packages: new Set(records.map((record) => record.packageId)).size,
             downloaded: records.filter((record) => record.cacheState === "downloaded")
@@ -357,17 +361,48 @@ export async function applyActivationChange(plan) {
     });
     return applied.snapshotId;
 }
+function formatLibraryHeadline(report) {
+    return `Managed library: ${report.counts.packages} package(s), ${report.counts.active} active, ${report.counts.disabled} disabled, ${report.counts.downloaded} cached`;
+}
+function countByAgent(report, activationState) {
+    const counts = new Map();
+    for (const record of report.records)
+        if (record.activationState === activationState)
+            counts.set(record.agent, (counts.get(record.agent) ?? 0) + 1);
+    return [...counts]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([agent, count]) => `${agent} ${count}`)
+        .join(", ");
+}
+/** Concise default for people with a broad Maximum library. */
+export function formatLibrarySummary(report) {
+    if (!report.records.length)
+        return "No Loadout-managed skill activations exist.";
+    return [
+        formatLibraryHeadline(report),
+        `Active now: ${countByAgent(report, "active") || "none"}`,
+        `Disabled library: ${countByAgent(report, "disabled") || "none"}`,
+        "Disabled library skills are reviewed copies, not extra agent context.",
+        ...(report.migrationPending
+            ? [
+                `Migration pending: ${report.migrationPending} active installation(s) will be cached on first disable.`,
+            ]
+            : []),
+        "Use `loadout library --all` for every skill, source package, and activation state.",
+    ].join("\n");
+}
+/** Full per-skill provenance report for audits and explicit investigation. */
 export function formatLibraryStateReport(report) {
     if (!report.records.length)
         return "No Loadout-managed skill activations exist.";
     return [
-        `Managed library: ${report.counts.packages} package(s), ${report.counts.active} active, ${report.counts.disabled} disabled, ${report.counts.downloaded} cached`,
+        formatLibraryHeadline(report),
         ...(report.migrationPending
             ? [
                 `Migration pending: ${report.migrationPending} active installation(s) will be cached on first disable.`,
             ]
             : []),
-        ...report.records.map((record) => `${record.packageId}${record.unitId ? `/${record.unitId}` : ""} — ${record.agent} — cache:${record.cacheState} review:${record.reviewState} install:${record.installationState} activation:${record.activationState} — ${record.targets.length} target(s)`),
+        ...report.records.map((record) => `${record.packageId}${record.unitId ? `/${record.unitId}` : ""}${report.repositories[record.packageId] ? ` (${report.repositories[record.packageId]})` : ""} — ${record.agent} — cache:${record.cacheState} review:${record.reviewState} install:${record.installationState} activation:${record.activationState} — ${record.targets.length} target(s)`),
     ].join("\n");
 }
 export function formatActivationPlan(plan) {