loadout-ai 0.5.8 → 0.6.0

package/dist/src/commands/sharing.js

@@ -0,0 +1,358 @@
+import { loadEffectiveCatalog } from "../core/catalog.js";
+import { detectAgents, parseAgentSelection } from "../core/paths.js";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { addManifestPackage, initManifest, readManifest, removeManifestPackage, writeLockfile, } from "../core/manifest.js";
+import { readInstallState } from "../core/state.js";
+import { createPackage, packPackage, publishLocalPackage, publishRemotePackage, searchLocalRegistry, } from "../core/registry.js";
+import { auditLoadout, formatAuditReport } from "../core/audit.js";
+import { applyPortableImport, exportPortableLoadout, planPortableImport, } from "../core/portable.js";
+import { writeFileAtomically } from "../core/atomic-file.js";
+import { buildLibraryStateReport, formatLibrarySummary, formatLibraryStateReport, } from "../core/active-set.js";
+import { buildPrivacySafeReport, formatPrivacySafeReport, parsePrivacySafeLoadoutReport, writePrivacySafeReport, } from "../core/share-report.js";
+import { readLocalOutcomes, recordLocalOutcome, } from "../core/outcomes.js";
+import { createCredentialResolver } from "../core/credentials.js";
+import { buildLoadoutCard, compareLoadoutReports, formatLoadoutCard, formatLoadoutComparison, } from "../core/loadout-card.js";
+export function registerSharing(program) {
+    program
+        .command("init")
+        .description("Create a shareable loadout.json manifest")
+        .option("--path <path>", "manifest path", "loadout.json")
+        .option("--name <name>", "Loadout name")
+        .option("--agents <ids>", "comma-separated agent ids", "codex,claude-code")
+        .option("--scope <scope>", "project or global", "project")
+        .action(async (options) => {
+        const manifest = await initManifest(options.path, {
+            name: options.name,
+            agents: parseAgentSelection(options.agents),
+            scope: options.scope,
+        });
+        console.log(`Created ${options.path} for ${manifest.agents.join(", ")}.`);
+    });
+    program
+        .command("lock")
+        .description("Write exact installed state to loadout.lock")
+        .option("--manifest <path>", "manifest path", "loadout.json")
+        .option("--output <path>", "lockfile path", "loadout.lock")
+        .action(async (options) => {
+        const lockfile = await writeLockfile(await readManifest(options.manifest), options.output);
+        console.log(`Wrote ${options.output} with ${lockfile.packages.length} resolved package(s).`);
+    });
+    program
+        .command("export")
+        .description("Export a portable Loadout manifest and optional lockfile")
+        .argument("<output>", "new portable JSON file")
+        .option("--manifest <path>", "manifest path", "loadout.json")
+        .option("--lock <path>", "include this exact lockfile")
+        .action(async (output, options) => {
+        const bundle = await exportPortableLoadout(options.manifest, output, options.lock);
+        console.log(`Exported ${bundle.manifest.packages.length} package(s) to ${output}.${bundle.lockfile ? " Exact lockfile included." : ""}`);
+    });
+    program
+        .command("import")
+        .description("Preview or apply a portable Loadout manifest and lockfile")
+        .argument("<source>", "portable JSON file")
+        .option("--manifest <path>", "manifest destination", "loadout.json")
+        .option("--lock <path>", "lockfile destination", "loadout.lock")
+        .option("--yes", "apply the import; otherwise remain read-only")
+        .option("--overwrite", "replace existing destination files after snapshotting them")
+        .action(async (source, options) => {
+        const preview = await planPortableImport(source, options.manifest, options.lock);
+        console.log(JSON.stringify(preview.plan, null, 2));
+        if (!options.yes)
+            return console.log("Dry run only. Re-run with --yes to import this Loadout.");
+        const result = await applyPortableImport(source, options.manifest, options.lock, { overwrite: options.overwrite });
+        console.log(`Imported successfully. Recovery snapshot: ${result.snapshotId}.`);
+    });
+    program
+        .command("audit")
+        .description("Verify manifest, lockfile, installed state, and managed file hashes for CI")
+        .option("--manifest <path>", "manifest path", "loadout.json")
+        .option("--lock <path>", "lockfile path", "loadout.lock")
+        .option("--json", "emit machine-readable JSON")
+        .action(async (options) => {
+        const report = await auditLoadout(options.manifest, options.lock);
+        console.log(options.json
+            ? JSON.stringify(report, null, 2)
+            : formatAuditReport(report));
+        if (!report.valid)
+            process.exitCode = 1;
+    });
+    program
+        .command("create")
+        .description("Create a new Loadout package directory")
+        .argument("<directory>", "new package directory")
+        .requiredOption("--name <name>", "lowercase package name")
+        .option("--description <text>", "package description")
+        .option("--version <version>", "semantic version", "0.1.0")
+        .action(async (directory, options) => {
+        const descriptor = await createPackage(directory, options);
+        console.log(`Created ${descriptor.name}@${descriptor.version} in ${directory}.`);
+    });
+    program
+        .command("pack")
+        .description("Validate a package and print its deterministic inventory digest")
+        .argument("[directory]", "package directory", ".")
+        .option("--json", "emit machine-readable JSON")
+        .action(async (directory, options) => {
+        const packed = await packPackage(directory);
+        console.log(options.json
+            ? JSON.stringify(packed, null, 2)
+            : `${packed.descriptor.name}@${packed.descriptor.version} — ${packed.files.length} file(s) — sha256:${packed.digest}`);
+    });
+    program
+        .command("publish")
+        .description("Publish an immutable package version to a local or remote Loadout registry")
+        .argument("[directory]", "package directory", ".")
+        .option("--local", "publish to the local registry")
+        .option("--registry-url <url>", "remote registry base URL")
+        .option("--credential-keychain <service>", "resolve the remote registry token from the OS credential store")
+        .option("--credential-account <account>", "OS credential account")
+        .option("--approve-risk", "explicitly approve publishing scripts, hooks, or binaries")
+        .action(async (directory, options) => {
+        if (Number(Boolean(options.local)) +
+            Number(Boolean(options.registryUrl)) !==
+            1)
+            throw new Error("Choose exactly one destination: --local or --registry-url");
+        if (options.local) {
+            if (options.credentialKeychain)
+                throw new Error("Local publishing does not require a credential");
+            const packed = await publishLocalPackage(directory, {
+                approveRisk: options.approveRisk,
+            });
+            console.log(`Published ${packed.descriptor.name}@${packed.descriptor.version} with digest ${packed.digest}.`);
+            return;
+        }
+        const token = await createCredentialResolver()(options.credentialKeychain
+            ? {
+                kind: "os-keychain",
+                service: options.credentialKeychain,
+                ...(options.credentialAccount
+                    ? { account: options.credentialAccount }
+                    : {}),
+            }
+            : { kind: "environment", name: "LOADOUT_REGISTRY_TOKEN" });
+        if (!token)
+            throw new Error("Remote publishing credential did not resolve; set LOADOUT_REGISTRY_TOKEN or use --credential-keychain");
+        const published = await publishRemotePackage(directory, options.registryUrl, token, { approveRisk: options.approveRisk });
+        console.log(`Published ${published.name}@${published.version} with digest ${published.digest}.`);
+    });
+    program
+        .command("search")
+        .description("Search the bundled catalog and local registry")
+        .argument("[query]", "search text", "")
+        .option("--json", "emit machine-readable JSON")
+        .action(async (query, options) => {
+        const catalog = (await loadEffectiveCatalog())
+            .filter((pkg) => !query ||
+            `${pkg.id} ${pkg.displayName} ${pkg.description}`
+                .toLowerCase()
+                .includes(query.toLowerCase()))
+            .map((pkg) => ({
+            source: "catalog",
+            name: pkg.id,
+            description: pkg.description,
+            repository: pkg.repository,
+        }));
+        const local = (await searchLocalRegistry(query)).map((pkg) => ({
+            source: "registry",
+            ...pkg,
+        }));
+        if (options.json)
+            return console.log(JSON.stringify([...catalog, ...local], null, 2));
+        for (const item of [...catalog, ...local])
+            console.log(`${item.name}${"version" in item ? `@${item.version}` : ""} [${item.source}] — ${item.description}`);
+        if (!catalog.length && !local.length)
+            console.log("No matching packages found.");
+    });
+    program
+        .command("add")
+        .description("Add a catalog, GitHub, or local package to loadout.json")
+        .argument("<id>", "package id")
+        .option("--manifest <path>", "manifest path", "loadout.json")
+        .option("--catalog <id>", "catalog package id")
+        .option("--repository <owner/repo>", "public GitHub repository")
+        .option("--git <url>", "generic HTTPS or SSH Git repository")
+        .option("--registry <name@version>", "exact local registry package version")
+        .option("--remote-registry <url>", "fetch --registry name@version from this remote registry")
+        .option("--ref <ref>", "Git branch, tag, or ref")
+        .option("--path <path>", "GitHub repository subpath or local path")
+        .option("--local", "treat --path as a local source")
+        .option("--agents <ids>", "comma-separated target agents")
+        .option("--depends-on <ids>", "comma-separated package dependencies")
+        .action(async (id, options) => {
+        const selected = Number(Boolean(options.catalog)) +
+            Number(Boolean(options.repository)) +
+            Number(Boolean(options.git)) +
+            Number(Boolean(options.registry)) +
+            Number(Boolean(options.local));
+        if (selected !== 1)
+            throw new Error("Choose exactly one source: --catalog, --repository, --git, --registry, or --local with --path");
+        if (options.local && !options.path)
+            throw new Error("--local requires --path <directory>");
+        const registry = options.registry?.match(/^([a-z0-9][a-z0-9._-]*)@(.+)$/);
+        if (options.registry && !registry)
+            throw new Error("--registry expects name@version");
+        if (options.remoteRegistry && !registry)
+            throw new Error("--remote-registry requires --registry name@version");
+        const source = options.catalog
+            ? { type: "catalog", id: options.catalog }
+            : options.repository
+                ? {
+                    type: "github",
+                    repository: options.repository,
+                    ...(options.ref ? { ref: options.ref } : {}),
+                    ...(options.path ? { path: options.path } : {}),
+                }
+                : options.git
+                    ? {
+                        type: "git",
+                        url: options.git,
+                        ...(options.ref ? { ref: options.ref } : {}),
+                        ...(options.path ? { path: options.path } : {}),
+                    }
+                    : registry && options.remoteRegistry
+                        ? {
+                            type: "remote-registry",
+                            registry: options.remoteRegistry,
+                            name: registry[1],
+                            version: registry[2],
+                        }
+                        : registry
+                            ? {
+                                type: "registry",
+                                name: registry[1],
+                                version: registry[2],
+                            }
+                            : { type: "local", path: options.path };
+        const manifest = await addManifestPackage(options.manifest, {
+            id,
+            source,
+            ...(options.agents
+                ? { agents: parseAgentSelection(options.agents) }
+                : {}),
+            ...(options.dependsOn
+                ? { dependsOn: options.dependsOn.split(",") }
+                : {}),
+        });
+        console.log(`Added ${id} to ${options.manifest}. ${manifest.packages.length} package(s) configured.`);
+    });
+    program
+        .command("unadd")
+        .description("Remove a desired package from loadout.json without touching installed files")
+        .argument("<id>", "package id")
+        .option("--manifest <path>", "manifest path", "loadout.json")
+        .action(async (id, options) => {
+        const manifest = await removeManifestPackage(options.manifest, id);
+        console.log(`Removed ${id} from ${options.manifest}. ${manifest.packages.length} package(s) configured.`);
+    });
+    program
+        .command("list")
+        .alias("ls")
+        .description("List packages managed by Loadout")
+        .option("--json", "emit machine-readable JSON")
+        .action(async (options) => {
+        const state = await readInstallState();
+        if (options.json)
+            return console.log(JSON.stringify(state.installs, null, 2));
+        if (!state.installs.length)
+            return console.log("No Loadout-managed packages are installed.");
+        for (const item of state.installs)
+            console.log(`${item.packageId} — ${item.targetAgents.join(", ")} — ${item.resolvedCommit?.slice(0, 12) ?? "local"} — ${item.files.length} file(s)`);
+    });
+    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)
+            : options.all
+                ? formatLibraryStateReport(report)
+                : formatLibrarySummary(report));
+    });
+    program
+        .command("report")
+        .description("Print a privacy-safe shareable summary without paths, code, prompts, or secrets")
+        .option("--json", "emit the machine-readable artifact")
+        .action(async (options) => {
+        const report = await buildPrivacySafeReport();
+        console.log(options.json
+            ? JSON.stringify(report, null, 2)
+            : formatPrivacySafeReport(report));
+    });
+    program
+        .command("outcomes")
+        .description("Show privacy-safe local outcome signals; never uploads project or prompt data")
+        .option("--json", "emit machine-readable JSON")
+        .action(async (options) => {
+        const store = await readLocalOutcomes();
+        console.log(options.json
+            ? JSON.stringify(store, null, 2)
+            : [
+                `Local outcomes: ${store.events.length}`,
+                ...store.events.map((event) => `${event.recordedAt} — ${event.selector} — ${event.agent}/${event.taskFamily} — ${event.result}`),
+                "Privacy: local only; no project names, paths, prompts, code, filenames, or secrets.",
+            ].join("\n"));
+    });
+    program
+        .command("outcome")
+        .description("Record an explicit local, agent/task-scoped skill outcome")
+        .argument("<selector>", "exact package/skill selector")
+        .requiredOption("--agent <id>", "agent id")
+        .requiredOption("--task <family>", "general, frontend, testing, javascript, python, backend, security, or documentation")
+        .requiredOption("--result <value>", "accept, reject, success, failure, activation, disable, or rollback")
+        .action(async (selector, options) => {
+        const knownAgents = new Set((await detectAgents()).map((agent) => agent.id));
+        if (!knownAgents.has(options.agent))
+            throw new Error(`Unknown agent id: ${options.agent}`);
+        const event = await recordLocalOutcome({
+            selector,
+            agent: options.agent,
+            taskFamily: options.task,
+            result: options.result,
+        });
+        console.log(`Recorded local outcome ${event.id}. No project, prompt, or source data was stored.`);
+    });
+    program
+        .command("share")
+        .description("Write the privacy-safe Loadout report to a JSON artifact")
+        .argument("<output>", "new or replacement report path")
+        .action(async (output) => {
+        const report = await buildPrivacySafeReport();
+        await writePrivacySafeReport(output, report);
+        console.log(`Wrote privacy-safe Loadout report to ${output}. Review it before sharing.`);
+    });
+    program
+        .command("card")
+        .description("Render a privacy-safe Markdown evidence card without project or repository details")
+        .option("--output <path>", "write the Markdown card to a file")
+        .option("--json", "emit the underlying privacy-safe card as JSON")
+        .action(async (options) => {
+        if (options.output && options.json)
+            throw new Error("--output and --json cannot be used together");
+        const card = await buildLoadoutCard();
+        const markdown = formatLoadoutCard(card);
+        if (options.output) {
+            await writeFileAtomically(resolve(options.output), `${markdown}\n`);
+            console.log(`Wrote privacy-safe Loadout card to ${resolve(options.output)}. Review it before sharing.`);
+            return;
+        }
+        console.log(options.json ? JSON.stringify(card, null, 2) : markdown);
+    });
+    program
+        .command("compare-loadouts")
+        .description("Compare aggregate counts from two explicit privacy-safe Loadout reports")
+        .argument("<left>", "earlier privacy-safe report JSON")
+        .argument("<right>", "later privacy-safe report JSON")
+        .option("--json", "emit machine-readable count deltas")
+        .action(async (left, right, options) => {
+        const [before, after] = await Promise.all([left, right].map(async (path) => parsePrivacySafeLoadoutReport(JSON.parse(await readFile(resolve(path), "utf8")))));
+        const comparison = compareLoadoutReports(before, after);
+        console.log(options.json
+            ? JSON.stringify(comparison, null, 2)
+            : formatLoadoutComparison(comparison));
+    });
+}

package/dist/src/commands/support.js

@@ -0,0 +1,246 @@
+import { createInterface } from "node:readline/promises";
+import { createRequire } from "node:module";
+import { detectAgents, parseAgentSelection } from "../core/paths.js";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { applyPreparedCatalogInstall, formatCatalogApplyGuidance, formatPreparedCatalogInstall, prepareCatalogInstall, } from "../core/catalog-install.js";
+import { formatInstalledSkillInventory, scanInstalledSkills, } from "../core/skill-inventory.js";
+import { interactiveModelApiAccess, parseModelApiAccess, } from "../core/access.js";
+import { BEGINNER_GUIDE } from "../core/cli-guide.js";
+export const collectOption = (value, previous = []) => [...previous, value];
+export function parseMcpCredentialMappings(recipe, mappings, account) {
+    const references = {};
+    for (const mapping of mappings) {
+        const separator = mapping.indexOf("=");
+        if (separator <= 0)
+            throw new Error("Invalid --credential mapping; expected NAME=env:VARIABLE or NAME=keychain:SERVICE. Never pass a credential value.");
+        const name = mapping.slice(0, separator);
+        const value = mapping.slice(separator + 1);
+        if (!recipe.environment.includes(name))
+            throw new Error(`Credential '${name}' is not required by recipe '${recipe.id}'`);
+        if (references[name])
+            throw new Error(`Credential '${name}' was mapped more than once`);
+        if (value.startsWith("env:") && value.length > 4)
+            references[name] = {
+                kind: "environment",
+                name: value.slice(4),
+            };
+        else if (value.startsWith("keychain:") && value.length > 9)
+            references[name] = {
+                kind: "os-keychain",
+                service: value.slice(9),
+                ...(account ? { account } : {}),
+            };
+        else
+            throw new Error(`Invalid --credential mapping for '${name}'; use env:VARIABLE or keychain:SERVICE, never a credential value.`);
+    }
+    return references;
+}
+export async function readCredentialFromStdin() {
+    if (process.stdin.isTTY)
+        throw new Error("Credential input must be piped on stdin; interactive echo is intentionally unsupported");
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of process.stdin) {
+        const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += value.length;
+        if (size > 64 * 1024)
+            throw new Error("Credential input exceeds the 64 KiB safety limit");
+        chunks.push(value);
+    }
+    const secret = Buffer.concat(chunks)
+        .toString("utf8")
+        .replace(/\r?\n$/, "");
+    if (!secret)
+        throw new Error("Credential input is empty");
+    return secret;
+}
+export function setupSelection(mode, packageIds) {
+    if (!["stable", "power", "maximum", "custom"].includes(mode))
+        throw new Error("--mode must be stable, power, maximum, or custom");
+    if (mode === "custom" && packageIds.length === 0)
+        throw new Error("Custom setup requires at least one --package <id>");
+    if (mode !== "custom" && packageIds.length)
+        throw new Error("--package can only be used with --mode custom");
+    return {
+        mode: mode,
+        ...(packageIds.length ? { packageIds } : {}),
+    };
+}
+export function printSetupProgress(progress) {
+    const marker = progress.status === "ready"
+        ? "✓"
+        : progress.status === "skipped"
+            ? "○"
+            : "↓";
+    console.error(`${marker} [${progress.completed}/${progress.total}] ${progress.message}`);
+}
+export function printProvenanceProgress(progress) {
+    const marker = progress.status === "ready"
+        ? "✓"
+        : progress.status === "failed"
+            ? "○"
+            : "↓";
+    console.error(`${marker} [${progress.completed}/${progress.total}] ${progress.message}`);
+}
+export function riskyPackageSummary(prepared) {
+    return prepared.entries
+        .filter((entry) => entry.safety.approvalRequired)
+        .map((entry) => {
+        const categories = [
+            ...new Set(entry.safety.findings.map((finding) => finding.category)),
+        ];
+        return `${entry.package.id} (${categories.join(", ")})`;
+    })
+        .join(", ");
+}
+export async function runSetup(options) {
+    const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    let mode = options.mode;
+    let packageIds = options.package ?? [];
+    let reader;
+    let access = options.apiAccess
+        ? parseModelApiAccess(options.apiAccess)
+        : undefined;
+    try {
+        if (!mode) {
+            if (!interactive) {
+                console.log("Pick a loadout to preview: `loadout setup --mode stable` (recommended), `--mode power` (broader), or `--mode maximum` (full library, activate per project). Nothing installs until you add --yes.");
+                return;
+            }
+            reader = createInterface({
+                input: process.stdin,
+                output: process.stdout,
+            });
+            const answer = (await reader.question([
+                "Choose a loadout:",
+                "  [1] Stable   — a small, reviewed set of everyday skills (recommended)",
+                "  [2] Power    — a broader daily-driver set",
+                "  [3] Maximum  — download the full reviewed library, activate per project later",
+                "  [4] Custom   — pick exact package ids",
+                "> ",
+            ].join("\n"))).trim();
+            mode =
+                answer === "2"
+                    ? "power"
+                    : answer === "3"
+                        ? "maximum"
+                        : answer === "4"
+                            ? "custom"
+                            : "stable";
+            if (mode === "custom") {
+                const custom = await reader.question("Enter comma-separated catalog package ids: ");
+                packageIds = custom
+                    .split(",")
+                    .map((value) => value.trim())
+                    .filter(Boolean);
+            }
+        }
+        if (!access && interactive && !options.yes) {
+            reader ??= createInterface({
+                input: process.stdin,
+                output: process.stdout,
+            });
+            access = interactiveModelApiAccess(await reader.question("Any billed model API key to declare? (ChatGPT/Claude subscriptions don't count) [0] No, [1] OpenAI, [2] Anthropic, [3] Both, [4] OpenRouter, [5] Other: "));
+        }
+        access ??= { modelApis: [] };
+        const selection = setupSelection(mode, packageIds);
+        console.log("\nPreparing a read-only install plan from screened immutable commits…");
+        const prepared = await prepareCatalogInstall(selection, {
+            requestedAgents: parseAgentSelection(options.agents),
+            onProgress: printSetupProgress,
+            access,
+        });
+        console.log(`\n${formatPreparedCatalogInstall(prepared, { details: options.details })}\n`);
+        const risky = riskyPackageSummary(prepared);
+        let approved = Boolean(options.yes);
+        let riskApproved = Boolean(options.approveRisk);
+        if (!approved) {
+            if (!interactive) {
+                console.log(formatCatalogApplyGuidance(Boolean(risky)));
+                return;
+            }
+            reader ??= createInterface({
+                input: process.stdin,
+                output: process.stdout,
+            });
+            approved = /^(?:y|yes)$/i.test((await reader.question("Install this loadout as one rollback-safe transaction? [y/N] ")).trim());
+            if (!approved) {
+                console.log("Cancelled; no agent files were changed.");
+                return;
+            }
+        }
+        if (risky && !riskApproved) {
+            if (!interactive)
+                throw new Error(`The screened skills contain additional safety findings: ${risky}. Inspect the preview and add --approve-risk to proceed.`);
+            reader ??= createInterface({
+                input: process.stdin,
+                output: process.stdout,
+            });
+            console.log(`Additional safety findings: ${risky}`);
+            riskApproved = /^(?:y|yes)$/i.test((await reader.question("Approve these reviewed script/domain/instruction findings? [y/N] ")).trim());
+            if (!riskApproved) {
+                console.log("Cancelled; no agent files were changed.");
+                return;
+            }
+        }
+        const snapshotId = await applyPreparedCatalogInstall(prepared, {
+            approveRisk: riskApproved,
+        });
+        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.");
+    }
+    finally {
+        reader?.close();
+    }
+}
+/**
+ * Zero-argument front door. On a TTY, bare `loadout` detects agents, shows the
+ * current inventory, then hands off to the interactive setup flow. Non-TTY
+ * callers never reach here (cli.ts prints the read-only guide instead), so this
+ * stays safe to run without arguments in a real terminal only.
+ */
+export async function runWizard() {
+    console.log("Loadout — make your AI coding agents more capable\n");
+    const detected = await detectAgents();
+    const present = detected.filter((agent) => agent.installed);
+    if (!present.length) {
+        console.log("No supported agents detected yet. Loadout works with Claude Code, Codex, Cursor,");
+        console.log("Gemini CLI, OpenCode, and more. Install one, then run `loadout` again.\n");
+        printBeginnerGuide();
+        return;
+    }
+    console.log(`Detected ${present.length} agent(s): ${present.map((agent) => agent.displayName).join(", ")}`);
+    console.log(formatInstalledSkillInventory(await scanInstalledSkills(present)));
+    console.log("\nPreview first — nothing changes until you approve, and every change is snapshotted for rollback.\n");
+    await runSetup({ package: [] });
+}
+const _require = createRequire(import.meta.url);
+function findPackageJson() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 5; i++) {
+        const candidate = join(dir, "package.json");
+        try {
+            const pkg = _require(candidate);
+            if (pkg.name === "loadout-ai")
+                return candidate;
+        }
+        catch {
+            // not found, keep walking
+        }
+        dir = dirname(dir);
+    }
+    // ponytail: fallback for dist layout — 3 levels up from dist/src/commands/
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "package.json");
+}
+export const LOADOUT_VERSION = _require(findPackageJson()).version;
+export function durableSchedulerLauncher() {
+    return [
+        join(dirname(process.execPath), process.platform === "win32" ? "npx.cmd" : "npx"),
+        "--yes",
+        `loadout-ai@${LOADOUT_VERSION}`,
+    ];
+}
+export function printBeginnerGuide() {
+    console.log(BEGINNER_GUIDE);
+}

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

@@ -0,0 +1,2 @@
+/** Recommended maximum number of skills exposed to one agent at a time. */
+export const DEFAULT_ACTIVE_SKILL_LIMIT = 30;

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

@@ -1,4 +1,5 @@
 import { applyActivationChange, formatActivationPlan, planActivationChange, } from "./active-set.js";
+import { DEFAULT_ACTIVE_SKILL_LIMIT } from "./active-limit.js";
 import { detectAgents } from "./paths.js";
 import { formatDetectedSignals, scanProject } from "./recommend.js";
 import { scanInstalledSkills } from "./skill-inventory.js";
@@ -297,7 +298,7 @@ function alternativesFor(selected, scored) {
 }
 /** Deterministic, local-only active-set selection over the reviewed library. */
 export async function planProjectActivation(projectPath, options = {}) {
-    const limit = options.limit ?? 40;
+    const limit = options.limit ?? DEFAULT_ACTIVE_SKILL_LIMIT;
     if (!Number.isInteger(limit) || limit < 1 || limit > 200)
         throw new Error("--limit must be an integer from 1 to 200");
     const project = await scanProject(projectPath);