loadout-ai 0.6.0 → 0.7.0

package/dist/src/core/{package.js → install/package.js}

@@ -1,8 +1,8 @@
 import { readFile, readdir } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
-import { discoverSkillDirectories } from "./skills.js";
-import { discoverMcpManifests } from "./mcp.js";
-import { discoverResources } from "./components.js";
+import { discoverSkillDirectories } from "../catalog/skills.js";
+import { discoverMcpManifests } from "../runtime/mcp.js";
+import { discoverResources } from "../catalog/components.js";
 const portableRelative = (root, path) => relative(root, path).split(/[\\/]/).join("/") || ".";
 function frontmatter(path) {
     return readFile(join(path, "SKILL.md"), "utf8").then((content) => {

package/dist/src/core/{reconcile.js → install/reconcile.js}

@@ -1,13 +1,13 @@
 import { createHash } from "node:crypto";
 import { cp, lstat, readFile, readdir, rm } from "node:fs/promises";
 import { join, relative, sep } from "node:path";
-import { analyzeUpdateSafety } from "./safety.js";
-import { enrichInventoryWithProvenance, } from "./provenance.js";
-import { scanInstalledSkills } from "./skill-inventory.js";
-import { installStatePath, recordInstallBatch } from "./state.js";
+import { analyzeUpdateSafety } from "../catalog/safety.js";
+import { enrichInventoryWithProvenance, } from "../catalog/provenance.js";
+import { scanInstalledSkills } from "../catalog/skill-inventory.js";
+import { installStatePath, recordInstallBatch } from "../workspace/state.js";
 import { runMutationTransaction } from "./transaction.js";
 import { repositoryCachePath } from "./source.js";
-import { validateSkillDirectory } from "./skills.js";
+import { validateSkillDirectory } from "../catalog/skills.js";
 const issuedPlans = new WeakMap();
 const IGNORED_TREE_NAMES = new Set([".git", ".cache", "node_modules"]);
 function slug(value) {

package/dist/src/core/{remove.js → install/remove.js}

@@ -1,10 +1,10 @@
 import { createHash } from "node:crypto";
 import { readFile, rm } from "node:fs/promises";
-import { forgetInstall, installStatePath, readInstallState } from "./state.js";
-import { writeMcpConfigPlan } from "./mcp.js";
+import { forgetInstall, installStatePath, readInstallState, } from "../workspace/state.js";
+import { writeMcpConfigPlan } from "../runtime/mcp.js";
 import { runMutationTransaction } from "./transaction.js";
-import { managedFileReadPath } from "./active-set.js";
-import { codexMcpServerFingerprint, removeCodexMcpServerBlock, writeCodexMcpConfigContent, } from "./codex-mcp.js";
+import { managedFileReadPath } from "../workspace/active-set.js";
+import { codexMcpServerFingerprint, removeCodexMcpServerBlock, writeCodexMcpConfigContent, } from "../agents/codex-mcp.js";
 export async function planRemove(packageId) {
     const state = await readInstallState();
     const record = state.installs.find((entry) => entry.packageId === packageId);

package/dist/src/core/{snapshot.js → install/snapshot.js}

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { readFile, writeFile, mkdir, readdir, rename, rm, lstat, } from "node:fs/promises";
 import { dirname, join, resolve, sep } from "node:path";
-import { loadoutHome, ensureDirectory, userHome } from "./paths.js";
+import { loadoutHome, ensureDirectory, userHome } from "../agents/paths.js";
 export async function createSnapshot(paths, options = {}) {
     const normalizedRoots = [...new Set(paths.map((path) => resolve(path)))];
     const snapshot = {

package/dist/src/core/{source.js → install/source.js}

@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { loadoutHome, ensureDirectory } from "./paths.js";
+import { loadoutHome, ensureDirectory } from "../agents/paths.js";
 const execFileAsync = promisify(execFile);
 async function enforceRepositoryBounds(root, options) {
     if (options.maxBytes === undefined && options.maxFiles === undefined)

package/dist/src/core/{sync.js → install/sync.js}

@@ -1,17 +1,17 @@
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { dirname, resolve, sep } from "node:path";
-import { loadEffectiveCatalog } from "./catalog.js";
+import { loadEffectiveCatalog } from "../catalog/catalog.js";
 import { installedAgents } from "./install.js";
-import { orderManifestPackages, readManifest, writeLockfile, } from "./manifest.js";
-import { detectAgents, userHome } from "./paths.js";
+import { orderManifestPackages, readManifest, writeLockfile, } from "../workspace/manifest.js";
+import { detectAgents, userHome } from "../agents/paths.js";
 import { fetchGitSnapshot, fetchRepositorySnapshot } from "./source.js";
-import { addRootFileExports, buildUniversalPackagePlan } from "./components.js";
-import { analyzeInstallPlanSafety, } from "./safety.js";
-import { fetchRemoteRegistryPackage, packPackage, resolveRegistryPackage, } from "./registry.js";
-import { discoverMcpManifests, planMcpConfigBatch, writeMcpConfigPlan, } from "./mcp.js";
-import { applySkillPlan, detectInstallConflicts } from "./skills.js";
-import { installStatePath, readInstallState, recordInstallTransaction, } from "./state.js";
+import { addRootFileExports, buildUniversalPackagePlan, } from "../catalog/components.js";
+import { analyzeInstallPlanSafety, } from "../catalog/safety.js";
+import { fetchRemoteRegistryPackage, packPackage, resolveRegistryPackage, } from "../catalog/registry.js";
+import { discoverMcpManifests, planMcpConfigBatch, writeMcpConfigPlan, } from "../runtime/mcp.js";
+import { applySkillPlan, detectInstallConflicts } from "../catalog/skills.js";
+import { installStatePath, readInstallState, recordInstallTransaction, } from "../workspace/state.js";
 import { runMutationTransaction } from "./transaction.js";
 function registrySourceKey(source) {
     if (source.type === "registry")

package/dist/src/core/{transaction.js → install/transaction.js}

@@ -1,7 +1,7 @@
 import { lstat, mkdir, readdir, readFile, rename, rm, writeFile, } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
-import { ensureDirectory, loadoutHome } from "./paths.js";
+import { ensureDirectory, loadoutHome } from "../agents/paths.js";
 import { createSnapshot, readSnapshot, recordSnapshotPostMutationState, restoreSnapshot, } from "./snapshot.js";
 import { acquireFileLock, withFileLock, } from "./file-lock.js";
 export const transactionRoot = () => join(loadoutHome(), "staging");

package/dist/src/core/{uninstall.js → install/uninstall.js}

@@ -2,11 +2,11 @@ import { execFile } from "node:child_process";
 import { readdir, rm, rmdir } from "node:fs/promises";
 import { dirname, parse, resolve } from "node:path";
 import { promisify } from "node:util";
-import { loadoutHome } from "./paths.js";
+import { loadoutHome } from "../agents/paths.js";
 import { applyRemove, planRemove } from "./remove.js";
-import { applyRuntimeToolPlan, listInstalledRuntimeTools, planRuntimeTool, } from "./runtime-tools.js";
-import { applyNativeSchedulerBundle, planNativeScheduler, } from "./scheduler.js";
-import { readInstallState } from "./state.js";
+import { applyRuntimeToolPlan, listInstalledRuntimeTools, planRuntimeTool, } from "../agents/runtime-tools.js";
+import { applyNativeSchedulerBundle, planNativeScheduler, } from "../runtime/scheduler.js";
+import { readInstallState } from "../workspace/state.js";
 export async function buildUninstallPlan(dependencies = {}) {
     const stateHome = loadoutHome();
     const state = await readInstallState();

package/dist/src/core/{update.js → install/update.js}

@@ -3,11 +3,11 @@ import { basename, join } from "node:path";
 import { fetchRepositorySnapshot, resolveRepositoryHead } from "./source.js";
 import { repositoryCachePath } from "./source.js";
 import { diffRepositorySnapshots } from "./diff.js";
-import { hashDirectory, readInstallState } from "./state.js";
-import { analyzeUpdateSafety } from "./safety.js";
-import { detectAgents, loadoutHome } from "./paths.js";
+import { hashDirectory, readInstallState } from "../workspace/state.js";
+import { analyzeUpdateSafety } from "../catalog/safety.js";
+import { detectAgents, loadoutHome } from "../agents/paths.js";
 import { applySkillInstall, buildSkillPlan, installedAgents, } from "./install.js";
-import { discoverSkillDirectories, validateSkillDirectory, } from "./skills.js";
+import { discoverSkillDirectories, validateSkillDirectory, } from "../catalog/skills.js";
 function managedUnitIds(state, packageId) {
     return [
         ...new Set((state.activations ?? [])

package/dist/src/core/{cli-guide.js → reporting/cli-guide.js}

@@ -1,42 +1,41 @@
 /** Plain-language entry points for people using the CLI, not maintaining it. */
 export const BEGINNER_GUIDE = `
-START HERE
+Loadout — manage the skills, tools, and MCP servers your AI agents use.
 
-1. See what Loadout currently manages
-   loadout library
-   loadout scan
-   loadout reconcile
+FIRST TIME
 
-2. Preview the recommended everyday setup
-   loadout setup --mode stable
-   loadout profiles
+  loadout doctor                    which agents you have, and whether they are healthy
+  loadout setup --mode stable       preview 30 reviewed skills (nothing changes)
+  loadout setup --mode stable --yes install them
 
-3. Find additions that fit the project in this folder
-   loadout recommend --project .
-   loadout optimize --project .
+IN A PROJECT
 
-4. Check for safer updates and new discoveries
-   loadout health
-   loadout alerts
-   loadout candidate list --limit 10
+  loadout recommend --project .     what this codebase actually needs
+  loadout optimize --project .      propose an active set for it
+  loadout status                    health grade and what is managed
 
-5. See reviewed MCP integrations and their credential needs
-   loadout mcp-recipe
-   loadout mcp-recipe --credential-free
-   loadout mcp-recipe playwright --agent claude-code
+WHILE YOU WORK
 
-If you decide to install something, Loadout shows a preview first and creates a
-snapshot before changing managed files. Recover with: loadout rollback
+  loadout route <describe a task>   which model tier fits, and what it costs
+  loadout route --conserve <task>   cheaper tiers when you are low on quota
+  loadout handoff send codex "..."  give a task to your other agent
 
-Reconcile is also read-only unless you add --yes. Exact matches can be managed
-without rewriting them; outdated replacements remain a separate explicit choice.
+USE IT INSIDE YOUR AGENT
 
-Setup reconciles the complete selected profile. To add one catalog package without
-retiring the current managed profile, use:
-   loadout install --mode custom --package <id>
+  loadout skills install loadout-router --yes
 
-Nothing above changes your agents. For the full maintainer/tooling surface, run:
-loadout advanced
+  Then just ask your agent "which model should I use for this?" instead of
+  coming back here.
+
+KEEPING CURRENT
+
+  loadout health                    safer updates and local drift
+  loadout alerts                    archived, stale, or changed sources
+
+Every command that writes previews first and snapshots before it changes
+anything. Undo with: loadout rollback
+
+More commands: loadout advanced
 `.trim();
 export const ADVANCED_GUIDE = [
     "ADVANCED COMMANDS",
@@ -44,8 +43,8 @@ export const ADVANCED_GUIDE = [
     "Hidden from the first screen so daily use stays focused.",
     "",
     "Discovery:    candidate, discover, review-queue, evaluate, skill-audit",
-    "Sharing:      init, lock, export, import, share, card, badge",
-    "Integrations: mcp-recipe, mcp-config, credentials, models, handoff, convert",
+    "Sharing:      init, lock, export, import, share, card",
+    "Integrations: mcp-recipe, mcp-config, credentials, models, handoff, skills, convert",
     "Lifecycle:    plan, adopt, uninstall, profiles, autopilot, tool, watch",
     "",
     "`loadout <command> --help` for options. Mutations preview first or require --yes.",
@@ -64,29 +63,18 @@ export const HIDDEN_FROM_FIRST_SCREEN = new Set([
     "import",
     "audit",
     "create",
-    "pack",
-    "publish",
     "add",
     "unadd",
     "share",
     "card",
-    "badge",
-    "compare-loadouts",
     "search",
     // analytics / evidence / discovery
     "report",
-    "outcomes",
-    "outcome",
-    "improve",
-    "improve-feedback",
-    "compare",
     "versions",
     "skill-audit",
-    "capabilities",
     "candidate",
     "discover",
     "review-queue",
-    "review",
     "inspect",
     "propose",
     "evaluate",
@@ -97,11 +85,7 @@ export const HIDDEN_FROM_FIRST_SCREEN = new Set([
     "completion",
     "mcp-recipe",
     "mcp-config",
-    "codex-mcp-config",
-    "sandbox-run",
     "convert",
-    "canary",
-    "serve",
     // lifecycle extras
     "plan",
     "adopt",

package/dist/src/core/{doctor.js → reporting/doctor.js}

@@ -1,7 +1,7 @@
 import { access, constants } from "node:fs/promises";
 import { dirname } from "node:path";
-import { detectAgents, directoryExists, loadoutHome, userHome, } from "./paths.js";
-import { inspectAgents } from "./agent-inspection.js";
+import { detectAgents, directoryExists, loadoutHome, userHome, } from "../agents/paths.js";
+import { inspectAgents } from "../agents/agent-inspection.js";
 async function writable(path) {
     // A not-yet-created directory is healthy when any existing ancestor is
     // writable; this handles first-run paths such as ~/.agents/skills.
@@ -65,10 +65,7 @@ export async function runDoctor() {
 export function formatDoctorReport(report, options = {}) {
     const installed = report.agents.filter((a) => a.agent.installed);
     const notInstalled = report.agents.filter((a) => !a.agent.installed);
-    const allIssues = [
-        ...report.issues,
-        ...installed.flatMap((a) => a.issues),
-    ];
+    const allIssues = [...report.issues, ...installed.flatMap((a) => a.issues)];
     const grade = allIssues.length === 0 && installed.length > 0
         ? "HEALTHY"
         : allIssues.length <= 2

package/dist/src/core/{freshness-alerts.js → reporting/freshness-alerts.js}

@@ -1,11 +1,11 @@
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { writeFileAtomically } from "./atomic-file.js";
-import { loadEffectiveCatalog } from "./catalog.js";
-import { ensureDirectory, loadoutHome } from "./paths.js";
-import { readInstallState } from "./state.js";
-import { buildUpdatePlan } from "./update.js";
+import { writeFileAtomically } from "../install/atomic-file.js";
+import { loadEffectiveCatalog } from "../catalog/catalog.js";
+import { ensureDirectory, loadoutHome } from "../agents/paths.js";
+import { readInstallState } from "../workspace/state.js";
+import { buildUpdatePlan } from "../install/update.js";
 const decisionsPath = () => join(loadoutHome(), "alert-decisions.json");
 function alertId(packageId, kind, evidence) {
     return `${packageId}-${kind}-${createHash("sha256")

package/dist/src/core/{health.js → reporting/health.js}

@@ -1,12 +1,12 @@
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { managedFileReadPath } from "./active-set.js";
-import { detectAgents } from "./paths.js";
-import { readInstallState } from "./state.js";
-import { buildUpdatePlan } from "./update.js";
-import { codexMcpServerFingerprint } from "./codex-mcp.js";
-import { listInstalledRuntimeToolSkillTargets, listInstalledRuntimeTools, } from "./runtime-tools.js";
+import { managedFileReadPath } from "../workspace/active-set.js";
+import { detectAgents } from "../agents/paths.js";
+import { readInstallState } from "../workspace/state.js";
+import { buildUpdatePlan } from "../install/update.js";
+import { codexMcpServerFingerprint } from "../agents/codex-mcp.js";
+import { listInstalledRuntimeToolSkillTargets, listInstalledRuntimeTools, } from "../agents/runtime-tools.js";
 async function drift(record, activations) {
     const changed = [];
     for (const file of record.files) {

package/dist/src/core/{loadout-card.js → reporting/loadout-card.js}

@@ -1,4 +1,4 @@
-import { buildLocalAgentHealthScores } from "./health-score-evidence.js";
+import { buildLocalAgentHealthScores } from "../agents/health-score-evidence.js";
 import { buildHealthReport, gradeHealth } from "./health.js";
 import { buildPrivacySafeReport, } from "./share-report.js";
 export async function buildLoadoutCard(options = {}) {

package/dist/src/core/{readme-claims.js → reporting/readme-claims.js}

@@ -1,4 +1,4 @@
-import { formatSchemaError, readmeClaimManifestSchema, } from "../shared/schemas.js";
+import { formatSchemaError, readmeClaimManifestSchema, } from "../../shared/schemas.js";
 export { readmeClaimManifestSchema };
 /** Parse the versioned index of evidence for material README statements. */
 export function parseReadmeClaimManifest(value) {

package/dist/src/core/{readme-facts.js → reporting/readme-facts.js}

@@ -1,5 +1,5 @@
-import { supportedAdapterNames } from "./adapters.js";
-import { buildCatalogCoverage } from "./catalog-coverage.js";
+import { supportedAdapterNames, } from "../agents/adapters.js";
+import { buildCatalogCoverage } from "../catalog/catalog-coverage.js";
 function profileFacts(allowlist) {
     return {
         sources: Object.keys(allowlist).length,

package/dist/src/core/{share-report.js → reporting/share-report.js}

@@ -1,7 +1,7 @@
 import { dirname } from "node:path";
-import { writeFileAtomically } from "./atomic-file.js";
-import { ensureDirectory } from "./paths.js";
-import { readInstallState } from "./state.js";
+import { writeFileAtomically } from "../install/atomic-file.js";
+import { ensureDirectory } from "../agents/paths.js";
+import { readInstallState } from "../workspace/state.js";
 export function parsePrivacySafeLoadoutReport(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         throw new Error("Privacy-safe Loadout report must be an object");

package/dist/src/core/{upgrade.js → reporting/upgrade.js}

@@ -1,11 +1,11 @@
-import { buildAdapterCapabilityGaps, } from "./adapters.js";
-import { applyPreparedCatalogInstall, formatPreparedCatalogInstall, prepareCatalogInstall, } from "./catalog-install.js";
-import { DEFAULT_ACTIVE_SKILL_LIMIT } from "./active-limit.js";
-import { loadEffectiveCatalog } from "./catalog.js";
+import { buildAdapterCapabilityGaps, } from "../agents/adapters.js";
+import { applyPreparedCatalogInstall, formatPreparedCatalogInstall, prepareCatalogInstall, } from "../install/catalog-install.js";
+import { DEFAULT_ACTIVE_SKILL_LIMIT } from "../workspace/active-limit.js";
+import { loadEffectiveCatalog, } from "../catalog/catalog.js";
 import { buildHealthReport, formatHealthReport } from "./health.js";
-import { buildLocalAgentHealthScores } from "./health-score-evidence.js";
-import { formatRecommendations, personalizeRecommendations, recommendPackages, scanProject, } from "./recommend.js";
-import { readLocalOutcomes } from "./outcomes.js";
+import { buildLocalAgentHealthScores } from "../agents/health-score-evidence.js";
+import { formatRecommendations, personalizeRecommendations, recommendPackages, scanProject, } from "../workspace/recommend.js";
+import { readLocalOutcomes, } from "../workspace/outcomes.js";
 /**
  * Builds the complete first-run preview without changing agent or Loadout state.
  * Network access is limited to the same immutable catalog preparation performed by

package/dist/src/core/routing/first-party-skills.js

@@ -0,0 +1,118 @@
+import { cp, rm, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { detectAgents } from "../agents/paths.js";
+export const FIRST_PARTY_SKILLS = [
+    {
+        id: "loadout-router",
+        displayName: "Loadout Router",
+        summary: "Lets an agent pick the right model tier for a task and hand work to another agent",
+    },
+    {
+        id: "loadout-curator",
+        displayName: "Loadout Curator",
+        summary: "Lets an agent decide which skills and MCP servers should be active for the current repository",
+    },
+];
+/**
+ * Locate the bundled `skills/` directory. Resolution walks upward so it works
+ * both from `src/` under tsx and from `dist/src/` in the published package.
+ */
+export async function bundledSkillsRoot() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 5; depth += 1) {
+        const candidate = join(dir, "skills");
+        try {
+            if ((await stat(candidate)).isDirectory())
+                return candidate;
+        }
+        catch {
+            // Keep walking toward the package root.
+        }
+        dir = dirname(dir);
+    }
+    throw new Error("Bundled skills directory not found; this build may be incomplete.");
+}
+export function findFirstPartySkill(id) {
+    const skill = FIRST_PARTY_SKILLS.find((item) => item.id === id);
+    if (!skill)
+        throw new Error(`Unknown Loadout skill '${id}'. Available: ${FIRST_PARTY_SKILLS.map((s) => s.id).join(", ")}`);
+    return skill;
+}
+async function directoryExists(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Build a preview of where one first-party skill would be installed. Nothing is
+ * written; the caller decides whether to apply.
+ */
+export async function planFirstPartySkill(id, options = {}) {
+    const skill = findFirstPartySkill(id);
+    const source = join(await bundledSkillsRoot(), skill.id);
+    if (!(await directoryExists(source)))
+        throw new Error(`Bundled skill '${skill.id}' is missing from this build.`);
+    const detected = options.detected ?? (await detectAgents());
+    const installed = detected.filter((agent) => agent.installed);
+    const requested = options.agents?.length
+        ? installed.filter((agent) => options.agents.includes(agent.id))
+        : installed;
+    const targets = [];
+    for (const agent of requested) {
+        const destination = join(agent.skillsDirectory, skill.id);
+        targets.push({
+            agent: agent.id,
+            displayName: agent.displayName,
+            destination,
+            replacing: await directoryExists(destination),
+        });
+    }
+    return { skill, source, targets };
+}
+export async function applyFirstPartySkill(plan) {
+    for (const target of plan.targets) {
+        // Replace wholesale so a reinstall cannot leave files from an older
+        // version of the skill behind.
+        if (target.replacing)
+            await rm(target.destination, { recursive: true });
+        await cp(plan.source, target.destination, { recursive: true });
+    }
+}
+export async function removeFirstPartySkill(plan) {
+    for (const target of plan.targets)
+        if (target.replacing)
+            await rm(target.destination, { recursive: true });
+}
+export function formatFirstPartySkillList(installedIds = new Set()) {
+    const lines = ["Skills that ship with Loadout:", ""];
+    for (const skill of FIRST_PARTY_SKILLS) {
+        const marker = installedIds.has(skill.id) ? "✓" : "○";
+        lines.push(`  ${marker} ${skill.id} — ${skill.summary}`);
+    }
+    lines.push("", "Install with: loadout skills install <id> --yes", "These teach your agents to use Loadout from inside a conversation.");
+    return lines.join("\n");
+}
+export function formatFirstPartySkillPlan(plan) {
+    if (!plan.targets.length)
+        return `No installed agents detected, so '${plan.skill.id}' has nowhere to go. Install an agent first.`;
+    const lines = [`${plan.skill.displayName} (${plan.skill.id})`, ""];
+    for (const target of plan.targets)
+        lines.push(`  ${target.replacing ? "replace" : "install"} → ${target.destination}  [${target.displayName}]`);
+    return lines.join("\n");
+}
+/** Which first-party skills are already present for at least one agent. */
+export async function installedFirstPartySkills(detected) {
+    const agents = (detected ?? (await detectAgents())).filter((agent) => agent.installed);
+    const found = new Set();
+    for (const skill of FIRST_PARTY_SKILLS)
+        for (const agent of agents)
+            if (await directoryExists(join(agent.skillsDirectory, skill.id))) {
+                found.add(skill.id);
+                break;
+            }
+    return found;
+}

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

@@ -1,7 +1,7 @@
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
-import { writeFileAtomically } from "./atomic-file.js";
+import { writeFileAtomically } from "../install/atomic-file.js";
 const HANDOFF_DIR = ".handoff";
 const MESSAGES_FILE = "messages.jsonl";
 const PROTOCOL_FILE = "PROTOCOL.md";
@@ -53,8 +53,17 @@ export async function initHandoff(projectRoot) {
         "loadout handoff done <message-id>",
         "```",
         "",
-        "Agents read this directory on wake. Loadout manages the message log;",
-        "each agent's own CLAUDE.md / AGENTS.md can reference .handoff/ for pickup.",
+        "## Making agents read this",
+        "",
+        "A message log only helps if the other agent checks it. Run:",
+        "",
+        "```",
+        "loadout handoff pickup --yes",
+        "```",
+        "",
+        "That adds a managed block to CLAUDE.md and AGENTS.md telling each agent to",
+        "run `loadout handoff inbox <agent>` at session start and act on what it finds.",
+        "Only the block between the loadout:handoff markers is managed.",
         "",
     ].join("\n");
     await writeFileAtomically(join(dir, PROTOCOL_FILE), protocol);
@@ -131,6 +140,114 @@ export async function getHandoffState(projectRoot) {
         done,
     };
 }
+// ---------------------------------------------------------------------------
+// Consumption — the half that makes a handoff more than an outbox
+// ---------------------------------------------------------------------------
+/** Pending tasks addressed to one agent, oldest first. */
+export async function readInbox(projectRoot, agent) {
+    const state = await getHandoffState(projectRoot);
+    return state.pending.filter((m) => m.to === agent);
+}
+/**
+ * Render an agent's inbox as instructions the agent itself can act on. This is
+ * what `loadout handoff inbox` prints, and what the generated pickup block
+ * tells each agent to run, so the message log is consumed rather than merely
+ * written.
+ */
+export function formatInbox(agent, messages) {
+    if (!messages.length)
+        return `No pending handoff tasks for ${agent}.`;
+    const lines = [
+        `${messages.length} pending handoff task(s) for ${agent}:`,
+        "",
+    ];
+    for (const m of messages) {
+        lines.push(`[${m.id}] from ${m.from} (${m.timestamp.slice(0, 16).replace("T", " ")})`);
+        lines.push(`  ${m.description}`);
+        if (m.context)
+            lines.push(`  context: ${m.context}`);
+        lines.push(`  when finished: loadout handoff done ${m.id}`);
+        lines.push("");
+    }
+    lines.push("Work these in order. Mark each done as you complete it so the sender sees progress.");
+    return lines.join("\n");
+}
+const PICKUP_START = "<!-- loadout:handoff:start -->";
+const PICKUP_END = "<!-- loadout:handoff:end -->";
+/** The managed instruction block written into an agent's context file. */
+export function pickupBlock(agent) {
+    return [
+        PICKUP_START,
+        "",
+        "## Handoff inbox",
+        "",
+        `At the start of a session, and whenever you finish a task, run:`,
+        "",
+        "```bash",
+        `loadout handoff inbox ${agent}`,
+        "```",
+        "",
+        "If it lists pending tasks, work them in order and run the `loadout handoff done`",
+        "command it prints for each one. If it reports none, continue as normal.",
+        "",
+        PICKUP_END,
+    ].join("\n");
+}
+/** Agent context files, relative to the project root. */
+const AGENT_CONTEXT_FILES = {
+    "claude-code": "CLAUDE.md",
+    codex: "AGENTS.md",
+};
+export function agentContextFile(agent) {
+    const file = AGENT_CONTEXT_FILES[agent];
+    if (!file)
+        throw new Error(`No known context file for agent '${agent}'. Supported: ${Object.keys(AGENT_CONTEXT_FILES).join(", ")}`);
+    return file;
+}
+/**
+ * Compute the new content for an agent's context file with the pickup block
+ * added or refreshed. Existing content is preserved; only the managed block
+ * between the markers is replaced.
+ */
+export async function planPickup(projectRoot, agent) {
+    const file = agentContextFile(agent);
+    const path = join(projectRoot, file);
+    const block = pickupBlock(agent);
+    let existing = "";
+    let exists = false;
+    try {
+        existing = await readFile(path, "utf8");
+        exists = true;
+    }
+    catch {
+        // A missing context file is created with just the managed block.
+    }
+    const start = existing.indexOf(PICKUP_START);
+    const end = existing.indexOf(PICKUP_END);
+    const replacing = start !== -1 && end !== -1 && end > start;
+    const content = replacing
+        ? existing.slice(0, start) + block + existing.slice(end + PICKUP_END.length)
+        : exists
+            ? `${existing.replace(/\s*$/, "")}\n\n${block}\n`
+            : `${block}\n`;
+    return { path, agent, exists, replacing, content };
+}
+export async function applyPickup(plan) {
+    await writeFileAtomically(plan.path, plan.content);
+}
+export function formatPickupPlan(plans) {
+    const lines = ["Handoff pickup instructions:", ""];
+    for (const plan of plans) {
+        const action = plan.replacing
+            ? "refresh managed block in"
+            : plan.exists
+                ? "append managed block to"
+                : "create";
+        lines.push(`  ${action} ${plan.path}`);
+    }
+    lines.push("", "This teaches each agent to check its handoff inbox at session start.", "Only the block between the loadout:handoff markers is managed; the rest of", "each file is preserved.");
+    return lines.join("\n");
+}
 export function formatHandoffStatus(state) {
     if (!state.initialized)
         return "Handoff not initialized. Run `loadout handoff init`.";