loadout-ai 0.6.0 → 0.8.0

package/dist/src/core/{route.js → routing/route.js}

@@ -4,29 +4,64 @@
 // Prices as of August 2026.
 export const MODEL_CATALOG = [
     // --- Anthropic (Claude Code) ---
-    { id: "claude-fable-5", provider: "anthropic", name: "Claude Fable 5", tier: "frontier", inputCostPer1M: 10, outputCostPer1M: 50, nativeAgents: ["claude-code"], current: true, generation: "5" },
-    { id: "claude-opus-5", provider: "anthropic", name: "Claude Opus 5", tier: "frontier", inputCostPer1M: 5, outputCostPer1M: 25, nativeAgents: ["claude-code"], current: true, generation: "5" },
-    { id: "claude-sonnet-5", provider: "anthropic", name: "Claude Sonnet 5", tier: "standard", inputCostPer1M: 3, outputCostPer1M: 15, nativeAgents: ["claude-code"], current: true, generation: "5" },
-    { id: "claude-opus-4-8", provider: "anthropic", name: "Claude Opus 4.8", tier: "frontier", inputCostPer1M: 5, outputCostPer1M: 25, nativeAgents: ["claude-code"], current: false, generation: "4" },
-    { id: "claude-opus-4-6", provider: "anthropic", name: "Claude Opus 4.6", tier: "frontier", inputCostPer1M: 5, outputCostPer1M: 25, nativeAgents: ["claude-code"], current: false, generation: "4" },
-    { id: "claude-sonnet-4-6", provider: "anthropic", name: "Claude Sonnet 4.6", tier: "standard", inputCostPer1M: 3, outputCostPer1M: 15, nativeAgents: ["claude-code"], current: false, generation: "4" },
-    { id: "claude-haiku-4-5", provider: "anthropic", name: "Claude Haiku 4.5", tier: "fast", inputCostPer1M: 1, outputCostPer1M: 5, nativeAgents: ["claude-code"], current: true, generation: "4" },
-    // --- OpenAI (Codex) — GPT-5.6 family ---
-    { id: "gpt-5.6-sol", provider: "openai", name: "GPT-5.6 Sol", tier: "frontier", inputCostPer1M: 5, outputCostPer1M: 30, nativeAgents: ["codex"], current: true, generation: "5.6" },
-    { id: "gpt-5.6-terra", provider: "openai", name: "GPT-5.6 Terra", tier: "standard", inputCostPer1M: 2, outputCostPer1M: 12, nativeAgents: ["codex"], current: true, generation: "5.6" },
-    { id: "gpt-5.6-luna", provider: "openai", name: "GPT-5.6 Luna", tier: "fast", inputCostPer1M: 0.20, outputCostPer1M: 1.20, nativeAgents: ["codex"], current: true, generation: "5.6" },
-    // --- OpenAI — GPT-5.5 ---
-    { id: "gpt-5.5", provider: "openai", name: "GPT-5.5", tier: "frontier", inputCostPer1M: 5, outputCostPer1M: 30, nativeAgents: ["codex"], current: true, generation: "5.5" },
-    // --- OpenAI — GPT-5.4 family ---
-    { id: "gpt-5.4", provider: "openai", name: "GPT-5.4", tier: "standard", inputCostPer1M: 2.50, outputCostPer1M: 15, nativeAgents: ["codex"], current: true, generation: "5.4" },
-    { id: "gpt-5.4-mini", provider: "openai", name: "GPT-5.4 Mini", tier: "fast", inputCostPer1M: 0.75, outputCostPer1M: 4.50, nativeAgents: ["codex"], current: true, generation: "5.4" },
-    // --- OpenAI — Codex-specific ---
-    { id: "gpt-5.1-codex", provider: "openai", name: "GPT-5.1 Codex", tier: "standard", inputCostPer1M: 1.25, outputCostPer1M: 10, nativeAgents: ["codex"], current: true, generation: "5.1" },
-    // --- OpenAI — o-series reasoning ---
-    { id: "o3-pro", provider: "openai", name: "o3-pro", tier: "frontier", inputCostPer1M: 20, outputCostPer1M: 80, nativeAgents: ["codex"], current: true, generation: "o3" },
-    { id: "o3", provider: "openai", name: "o3", tier: "frontier", inputCostPer1M: 2, outputCostPer1M: 8, nativeAgents: ["codex"], current: true, generation: "o3" },
-    { id: "o4-mini", provider: "openai", name: "o4-mini", tier: "standard", inputCostPer1M: 1.10, outputCostPer1M: 4.40, nativeAgents: ["codex"], current: true, generation: "o4" },
-    { id: "o3-mini", provider: "openai", name: "o3-mini", tier: "standard", inputCostPer1M: 1.10, outputCostPer1M: 4.40, nativeAgents: ["codex"], current: true, generation: "o3" },
+    // Haiku and the 4.x line are deliberately absent: for real coding work the
+    // choice is Opus or Sonnet, and offering a weaker tier invites picking it.
+    {
+        id: "claude-opus-5",
+        provider: "anthropic",
+        name: "Claude Opus 5",
+        tier: "frontier",
+        inputCostPer1M: 5,
+        outputCostPer1M: 25,
+        nativeAgents: ["claude-code"],
+        current: true,
+        generation: "5",
+    },
+    {
+        id: "claude-sonnet-5",
+        provider: "anthropic",
+        name: "Claude Sonnet 5",
+        tier: "standard",
+        inputCostPer1M: 3,
+        outputCostPer1M: 15,
+        nativeAgents: ["claude-code"],
+        current: true,
+        generation: "5",
+    },
+    // --- OpenAI (Codex) — the current GPT-5.6 tiers only ---
+    {
+        id: "gpt-5.6-sol",
+        provider: "openai",
+        name: "GPT-5.6 Sol",
+        tier: "frontier",
+        inputCostPer1M: 5,
+        outputCostPer1M: 30,
+        nativeAgents: ["codex"],
+        current: true,
+        generation: "5.6",
+    },
+    {
+        id: "gpt-5.6-terra",
+        provider: "openai",
+        name: "GPT-5.6 Terra",
+        tier: "standard",
+        inputCostPer1M: 2,
+        outputCostPer1M: 12,
+        nativeAgents: ["codex"],
+        current: true,
+        generation: "5.6",
+    },
+    {
+        id: "gpt-5.6-luna",
+        provider: "openai",
+        name: "GPT-5.6 Luna",
+        tier: "fast",
+        inputCostPer1M: 0.2,
+        outputCostPer1M: 1.2,
+        nativeAgents: ["codex"],
+        current: true,
+        generation: "5.6",
+    },
 ];
 const TIER_LABELS = {
     frontier: "Frontier (deep reasoning)",
@@ -74,12 +109,70 @@ const PHASE_CONFIG = {
     },
 };
 const PHASE_KEYWORDS = {
-    plan: ["plan", "design", "architect", "architecture", "rfc", "spec", "decompose", "strategy", "system design"],
-    implement: ["implement", "build", "code", "create", "add", "feature", "write", "develop", "make"],
-    review: ["review", "audit", "check", "inspect", "critique", "pr", "pull request", "diff"],
-    test: ["test", "spec", "coverage", "unit", "integration", "e2e", "assert", "vitest", "jest"],
-    debug: ["debug", "fix", "bug", "error", "crash", "broken", "investigate", "troubleshoot", "failing"],
-    document: ["document", "docs", "readme", "comment", "jsdoc", "changelog", "explain", "docstring"],
+    plan: [
+        "plan",
+        "design",
+        "architect",
+        "architecture",
+        "rfc",
+        "spec",
+        "decompose",
+        "strategy",
+        "system design",
+    ],
+    implement: [
+        "implement",
+        "build",
+        "code",
+        "create",
+        "add",
+        "feature",
+        "write",
+        "develop",
+        "make",
+    ],
+    review: [
+        "review",
+        "audit",
+        "check",
+        "inspect",
+        "critique",
+        "pr",
+        "pull request",
+        "diff",
+    ],
+    test: [
+        "test",
+        "spec",
+        "coverage",
+        "unit",
+        "integration",
+        "e2e",
+        "assert",
+        "vitest",
+        "jest",
+    ],
+    debug: [
+        "debug",
+        "fix",
+        "bug",
+        "error",
+        "crash",
+        "broken",
+        "investigate",
+        "troubleshoot",
+        "failing",
+    ],
+    document: [
+        "document",
+        "docs",
+        "readme",
+        "comment",
+        "jsdoc",
+        "changelog",
+        "explain",
+        "docstring",
+    ],
 };
 // ---------------------------------------------------------------------------
 // Classification
@@ -114,6 +207,25 @@ export function cheapestInTier(tier) {
     const models = modelsForTier(tier);
     return models.sort((a, b) => a.inputCostPer1M - b.inputCostPer1M)[0];
 }
+/**
+ * Narrow a recommendation to the agents actually present on this machine. A
+ * recommendation that names an agent the user has not installed is noise, so
+ * the resolved list drives both the printed advice and the handoff command.
+ */
+export function resolveAvailableAgents(suggested, installed) {
+    const present = new Set(installed);
+    return {
+        available: suggested.filter((id) => present.has(id)),
+        missing: suggested.filter((id) => !present.has(id)),
+    };
+}
+/** Models in the recommended tier that the given agents can actually run. */
+export function modelsRunnableBy(models, agents) {
+    if (!agents.length)
+        return models;
+    const wanted = new Set(agents);
+    return models.filter((m) => m.nativeAgents.some((id) => wanted.has(id)));
+}
 // ---------------------------------------------------------------------------
 // Routing
 // ---------------------------------------------------------------------------
@@ -166,23 +278,60 @@ export function estimateCostSavings() {
     const conserveTotal = conserveEstimates.reduce((s, c) => s + c, 0);
     return { estimates, normalTotal, conserveTotal };
 }
-// ---------------------------------------------------------------------------
-// Formatters
-// ---------------------------------------------------------------------------
-export function formatRouteRecommendation(rec) {
-    const modelNames = rec.models.slice(0, 4).map((m) => `${m.name} ($${m.inputCostPer1M}/$${m.outputCostPer1M})`);
+/** Shell-quote a task description for the suggested handoff command. */
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+export function formatRouteRecommendation(rec, context = {}) {
+    // `undefined` means detection never ran, so every suggested agent stands. An
+    // empty array means detection ran and found nothing, which must not be
+    // silently upgraded back to the full suggestion list.
+    const checked = context.installedAgents !== undefined;
+    const { available, missing } = checked
+        ? resolveAvailableAgents(rec.suggestedAgents, context.installedAgents)
+        : { available: rec.suggestedAgents, missing: [] };
+    // Only recommend models an available agent can actually run. Not every
+    // provider offers every tier — Claude Code has no fast tier — so when the
+    // recommended tier holds nothing the user can reach, step up to the nearest
+    // tier that does rather than naming a model they cannot run.
+    const runnable = checked
+        ? modelsRunnableBy(rec.models, available)
+        : rec.models;
+    const stepUp = {
+        fast: "standard",
+        standard: "frontier",
+    };
+    let effective = runnable;
+    let tier = rec.tier;
+    let substituted;
+    while (checked && available.length && !effective.length && stepUp[tier]) {
+        const next = stepUp[tier];
+        effective = modelsRunnableBy(modelsForTier(next), available);
+        if (effective.length)
+            substituted = { from: rec.tier, to: next };
+        tier = next;
+    }
+    const shown = (effective.length ? effective : rec.models).slice(0, 4);
+    const modelNames = shown.map((m) => `${m.name} ($${m.inputCostPer1M}/$${m.outputCostPer1M})`);
     const lines = [
         `Phase:    ${rec.phase}`,
         `Tier:     ${rec.tierLabel}`,
         `Models:   ${modelNames.join("\n          ")}`,
-        `Agents:   ${rec.suggestedAgents.join(", ")}`,
+        `Agents:   ${available.length ? available.join(", ") : "none detected"}${missing.length ? `  (not installed: ${missing.join(", ")})` : ""}`,
         `Why:      ${rec.reason}`,
     ];
+    if (substituted)
+        lines.push(`Note:     your agents have no ${substituted.from}-tier model, so this shows`, `          the ${substituted.to} tier instead.`);
     if (rec.conserveAlternative) {
         const alt = rec.conserveAlternative;
         const altCheapest = cheapestInTier(alt.tier);
         lines.push(``, `Conserve: drop to ${alt.tier} tier (${altCheapest?.name ?? "—"} at $${altCheapest?.inputCostPer1M ?? "?"}/$${altCheapest?.outputCostPer1M ?? "?"})`, `          ${alt.tradeoff}`);
     }
+    // Actionable next step: hand this task to a detected agent.
+    if (context.description && available.length) {
+        const target = available[0];
+        lines.push(``, `Hand off:`, `  loadout handoff ${target} ${shellQuote(context.description)}`);
+    }
     return lines.join("\n");
 }
 export function formatRoutingTable(conserve = false) {
@@ -200,8 +349,13 @@ export function formatRoutingTable(conserve = false) {
         return `${phase} ${tier} ${model} ${inCost} ${outCost} ${agents}`;
     });
     return [
-        conserve ? "ROUTING TABLE (conserve mode — usage-saving tier for each phase)" : "ROUTING TABLE",
-        "", header, divider, ...rows,
+        conserve
+            ? "ROUTING TABLE (conserve mode — usage-saving tier for each phase)"
+            : "ROUTING TABLE",
+        "",
+        header,
+        divider,
+        ...rows,
     ].join("\n");
 }
 export function formatCostTable() {
@@ -216,7 +370,10 @@ export function formatCostTable() {
     });
     const savings = Math.round((1 - conserveTotal / normalTotal) * 100);
     return [
-        header, divider, ...rows, divider,
+        header,
+        divider,
+        ...rows,
+        divider,
         `Normal total: $${normalTotal.toFixed(2)}/M input across 6 phases`,
         `Conserve total: $${conserveTotal.toFixed(2)}/M input (${savings}% cheaper)`,
         "",
@@ -244,5 +401,11 @@ export function formatModelCatalog(filter) {
         const agents = m.nativeAgents.slice(0, 3).join(", ");
         return `${name} ${provider} ${tier} ${inCost} ${outCost} ${gen} ${agents}`;
     });
-    return [`${models.length} models${filter?.current === false ? " (including legacy)" : ""}`, "", header, divider, ...rows].join("\n");
+    return [
+        `${models.length} models${filter?.current === false ? " (including legacy)" : ""}`,
+        "",
+        header,
+        divider,
+        ...rows,
+    ].join("\n");
 }

package/dist/src/core/{api.js → runtime/api.js}

@@ -1,8 +1,8 @@
 import { createServer, } from "node:http";
-import { loadEffectiveCatalog, rankCatalog } from "./catalog.js";
-import { detectAgents } from "./paths.js";
-import { buildUpdatePlan } from "./update.js";
-import { buildHealthReport } from "./health.js";
+import { loadEffectiveCatalog, rankCatalog } from "../catalog/catalog.js";
+import { detectAgents } from "../agents/paths.js";
+import { buildUpdatePlan } from "../install/update.js";
+import { buildHealthReport } from "../reporting/health.js";
 function json(response, statusCode, body) {
     const payload = JSON.stringify(body);
     response.writeHead(statusCode, {

package/dist/src/core/{canary.js → runtime/canary.js}

@@ -1,4 +1,4 @@
-import { evaluatePackage } from "./evaluate.js";
+import { evaluatePackage, } from "../discovery/evaluate.js";
 /**
  * Run the policy gate for a candidate without mutating agent configuration.
  * Promotion is deliberately injected so callers can connect it to their

package/dist/src/core/{github.js → runtime/github.js}

@@ -1,7 +1,7 @@
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
-import { loadoutHome } from "./paths.js";
+import { loadoutHome } from "../agents/paths.js";
 function normalizeRepository(input) {
     const value = input
         .trim()

package/dist/src/core/{mcp-recipes.js → runtime/mcp-recipes.js}

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
-import { createCredentialResolver } from "./credentials.js";
+import { createCredentialResolver } from "../routing/credentials.js";
 import { planMcpConfig } from "./mcp.js";
 /**
  * Small, source-linked recipes. These configure a connection only; authorizing

package/dist/src/core/{mcp.js → runtime/mcp.js}

@@ -1,8 +1,8 @@
 import { readFile, readdir, mkdir, rename, writeFile, rm, } from "node:fs/promises";
 import { join, resolve, dirname, basename } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
-import { loadoutHome } from "./paths.js";
-import { runMutationTransaction, withMutationLock } from "./transaction.js";
+import { loadoutHome } from "../agents/paths.js";
+import { runMutationTransaction, withMutationLock, } from "../install/transaction.js";
 const missingConfigMarker = "loadout:mcp-config:missing";
 async function configFingerprint(path) {
     let content;

package/dist/src/core/{scheduler.js → runtime/scheduler.js}

@@ -2,10 +2,10 @@ import { execFile } from "node:child_process";
 import { rm } from "node:fs/promises";
 import { dirname, win32, join } from "node:path";
 import { promisify } from "node:util";
-import { writeFileAtomically } from "./atomic-file.js";
-import { ensureDirectory, loadoutHome, userHome } from "./paths.js";
-import { createSnapshot, recordSnapshotPostMutationState } from "./snapshot.js";
-import { beginTransaction, completeTransaction, markTransactionCommitting, recoverPendingTransactions, rollbackTransaction, } from "./transaction.js";
+import { writeFileAtomically } from "../install/atomic-file.js";
+import { ensureDirectory, loadoutHome, userHome } from "../agents/paths.js";
+import { createSnapshot, recordSnapshotPostMutationState, } from "../install/snapshot.js";
+import { beginTransaction, completeTransaction, markTransactionCommitting, recoverPendingTransactions, rollbackTransaction, } from "../install/transaction.js";
 const execFileAsync = promisify(execFile);
 function parseTime(value) {
     const match = /^(\d{2}):(\d{2})$/.exec(value);

package/dist/src/core/{active-policy.js → workspace/active-policy.js}

@@ -1,8 +1,8 @@
 import { applyActivationChange, formatActivationPlan, planActivationChange, } from "./active-set.js";
 import { DEFAULT_ACTIVE_SKILL_LIMIT } from "./active-limit.js";
-import { detectAgents } from "./paths.js";
+import { detectAgents } from "../agents/paths.js";
 import { formatDetectedSignals, scanProject } from "./recommend.js";
-import { scanInstalledSkills } from "./skill-inventory.js";
+import { scanInstalledSkills } from "../catalog/skill-inventory.js";
 import { readInstallState } from "./state.js";
 import { outcomeAdjustment, projectTaskFamilies, readLocalOutcomes, } from "./outcomes.js";
 const FOUNDATION = new Set([

package/dist/src/core/{active-set.js → workspace/active-set.js}

@@ -1,10 +1,10 @@
 import { createHash } from "node:crypto";
 import { cp, lstat, mkdir, readFile, readdir, rm } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
-import { agentSkillsDirectory, ensureDirectory } from "./paths.js";
+import { agentSkillsDirectory, ensureDirectory } from "../agents/paths.js";
 import { activationLibraryPath, installStatePath, readInstallState, writeInstallState, } from "./state.js";
 import { inspectTargetOccupancy } from "./target-occupancy.js";
-import { runMutationTransaction } from "./transaction.js";
+import { runMutationTransaction } from "../install/transaction.js";
 /** Resolve a managed file to its active location or disabled library copy. */
 export function managedFileReadPath(packageId, filePath, activations) {
     const disabled = activations.find((activation) => activation.packageId === packageId &&

package/dist/src/core/{improve.js → workspace/improve.js}

@@ -1,9 +1,9 @@
-import { buildHealthReport } from "./health.js";
+import { buildHealthReport } from "../reporting/health.js";
 import { createHash } from "node:crypto";
 import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
-import { loadoutHome } from "./paths.js";
-import { detectSecretKinds } from "./safety.js";
+import { loadoutHome } from "../agents/paths.js";
+import { detectSecretKinds } from "../catalog/safety.js";
 export function proposeImprovements(report) {
     const proposals = [];
     if (report.driftedFiles)

package/dist/src/core/{manifest.js → workspace/manifest.js}

@@ -1,8 +1,8 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
-import { formatSchemaError, loadoutManifestSchema } from "../shared/schemas.js";
+import { formatSchemaError, loadoutManifestSchema, } from "../../shared/schemas.js";
 import { readInstallState } from "./state.js";
-import { writeFileAtomically } from "./atomic-file.js";
+import { writeFileAtomically } from "../install/atomic-file.js";
 const AGENTS = new Set([
     "claude-code",
     "codex",

package/dist/src/core/{outcomes.js → workspace/outcomes.js}

@@ -1,9 +1,9 @@
 import { readFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { dirname, join } from "node:path";
-import { writeFileAtomically } from "./atomic-file.js";
-import { ensureDirectory, loadoutHome } from "./paths.js";
-import { withFileLock } from "./file-lock.js";
+import { writeFileAtomically } from "../install/atomic-file.js";
+import { ensureDirectory, loadoutHome } from "../agents/paths.js";
+import { withFileLock } from "../install/file-lock.js";
 const outcomePath = () => join(loadoutHome(), "outcomes.json");
 const outcomeLockPath = () => join(loadoutHome(), "outcomes.lock");
 const RESULTS = new Set([

package/dist/src/core/{portable.js → workspace/portable.js}

@@ -1,9 +1,9 @@
 import { lstat, mkdir, readFile, rename, rm, writeFile, } from "node:fs/promises";
 import { dirname, isAbsolute, resolve } from "node:path";
-import { parseLockfile, readLockfile } from "./audit.js";
+import { parseLockfile, readLockfile } from "../catalog/audit.js";
 import { parseManifest, readManifest } from "./manifest.js";
-import { runMutationTransaction } from "./transaction.js";
-import { detectSecretKinds } from "./safety.js";
+import { runMutationTransaction } from "../install/transaction.js";
+import { detectSecretKinds } from "../catalog/safety.js";
 export function parsePortableLoadout(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         throw new Error("Portable Loadout must be an object");

package/dist/src/core/{profile-state.js → workspace/profile-state.js}

@@ -1,4 +1,4 @@
-import { resolveCatalogProfile } from "./profiles.js";
+import { resolveCatalogProfile } from "../catalog/profiles.js";
 import { readInstallState, writeInstallState } from "./state.js";
 export async function recordInstalledProfile(prepared) {
     const profile = {

package/dist/src/core/{recommend.js → workspace/recommend.js}

@@ -1,6 +1,6 @@
 import { readFile, readdir } from "node:fs/promises";
 import { basename, resolve } from "node:path";
-import { POWER_SKILL_ALLOWLIST, STABLE_BOOST_PACKAGE_IDS } from "./profiles.js";
+import { POWER_SKILL_ALLOWLIST, STABLE_BOOST_PACKAGE_IDS, } from "../catalog/profiles.js";
 import { packageOutcomeAdjustment, projectTaskFamilies, } from "./outcomes.js";
 const SIGNAL_FILES = new Set([
     "package.json",

package/dist/src/core/{state.js → workspace/state.js}

@@ -1,9 +1,9 @@
 import { createHash } from "node:crypto";
 import { readFile, readdir, stat } from "node:fs/promises";
 import { basename, join, relative, sep } from "node:path";
-import { formatSchemaError, installStateSchema } from "../shared/schemas.js";
-import { ensureDirectory, loadoutHome } from "./paths.js";
-import { writeFileAtomically } from "./atomic-file.js";
+import { formatSchemaError, installStateSchema } from "../../shared/schemas.js";
+import { ensureDirectory, loadoutHome } from "../agents/paths.js";
+import { writeFileAtomically } from "../install/atomic-file.js";
 const stateFile = () => join(loadoutHome(), "state.json");
 export const installStatePath = () => stateFile();
 export async function writeInstallState(state) {

package/docs/CANDIDATE_INTELLIGENCE.md

@@ -93,10 +93,16 @@ powers, platform behavior, category, and catalog policy.
 
 ## Distribute a trusted catalog release
 
-Maintainers sign a technically screened full catalog array with an Ed25519 key kept outside the
+> **Not implemented.** The signing flow below is a design sketch. `loadout keygen`,
+> `loadout catalog-sign`, and `loadout catalog-update` do not exist in the CLI
+> today; the catalog ships in the package and is verified by the evidence gate
+> instead. Kept here as the intended shape, not as instructions.
+
+Maintainers would sign a technically screened full catalog array with an Ed25519 key kept outside the
 repository:
 
 ```bash
+# Design sketch — these commands do not exist yet.
 loadout keygen --private-key /secure/catalog-private.pem \
   --public-key ./catalog-public.pem
 loadout catalog-sign --catalog ./catalog/packages.json \
@@ -104,9 +110,10 @@ loadout catalog-sign --catalog ./catalog/packages.json \
   --output ./catalog.signed.json
 ```
 
-Users preview the verified release before trusting it:
+Users would preview the verified release before trusting it:
 
 ```bash
+# Design sketch — these commands do not exist yet.
 loadout catalog-update --source ./catalog.signed.json \
   --public-key ./catalog-public.pem
 loadout catalog-update --source ./catalog.signed.json \

package/docs/CATALOG.md

@@ -12,7 +12,7 @@ Thank you to every maintainer and contributor whose work appears here. Loadout d
 - **License** is the SPDX identifier recorded in `catalog/packages.json` from GitHub metadata. **Review required** corresponds to `NOASSERTION`: no SPDX identifier was reported, so users must inspect the upstream terms instead of assuming permission.
 - **Reviewed revision** links to the immutable commit inspected for catalog admission. It is not necessarily the newest upstream commit.
 
-The machine-readable catalog remains the source of truth. Run `loadout catalog --coverage --json` to inspect coverage and `loadout capabilities` to inspect what each local agent adapter can actually manage.
+The machine-readable catalog remains the source of truth. Run `loadout catalog --coverage --json` to inspect coverage and `loadout doctor --verbose` to inspect what each local agent adapter can actually manage.
 
 ## All 53 credited repositories
 

package/docs/CREDENTIAL_AND_UPDATE_POLICY.md

@@ -26,6 +26,6 @@ verification restores the snapshot and quarantines the candidate commit. A user
 revoke a policy at any time; revocation prevents future mutations but never deletes
 existing snapshots.
 
-The local `loadout canary` command implements the non-mutating static gate. A
+Update safety runs as a non-mutating static gate during `loadout upgrade` previews. A
 transaction layer must provide verification and promotion callbacks before a
 candidate can be promoted; the command itself never installs a candidate.