agent-trellis 0.2.0 → 0.4.0

package/dist/commands/memory.js

@@ -0,0 +1,89 @@
+/**
+ * `trellis memory sync` — ingests canonical `memories/*.md` into the
+ * on-disk knowledge-graph file `@modelcontextprotocol/server-memory`
+ * itself reads at startup, closing P6's explicitly-left-open "auto-
+ * ingesting memories/*.md content into the running memory server's
+ * store" gap (trellis-memory-sync). Never spawns or talks to a running
+ * server process — this is a plain file write, same posture as every
+ * other Trellis write.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname } from "node:path";
+import { loadCanonicalSource } from "../core/canonical.js";
+import { planMemorySync, renderMemoryGraph } from "../lib/memoryGraph.js";
+const MEMORY_SERVER_NAME = "memory";
+/**
+ * Looks up `mcp.servers["memory"]` specifically (matching `schema/
+ * servers.example.yaml`'s own naming convention for the default shared-
+ * memory backend) — not a heuristic scan for any server whose command
+ * happens to mention `@modelcontextprotocol/server-memory`, since a
+ * user could reasonably name or configure it differently and this
+ * would then silently miss it. `static_env.MEMORY_FILE_PATH` must be
+ * set explicitly: the server's own unset-env default resolves relative
+ * to wherever `npx` cached the package, a location Trellis has no
+ * reliable way to predict.
+ */
+export function collectMemorySyncResult(homeDir = homedir()) {
+    const canonical = loadCanonicalSource(homeDir);
+    const server = canonical.mcp.servers[MEMORY_SERVER_NAME];
+    const rawPath = server?.staticEnv?.MEMORY_FILE_PATH;
+    if (!server || !rawPath) {
+        return {
+            configured: false,
+            reason: `no "${MEMORY_SERVER_NAME}" MCP server with static_env.MEMORY_FILE_PATH configured in servers.yaml — see schema/servers.example.yaml`,
+        };
+    }
+    const graphPath = rawPath.replace(/^~(?=$|\/)/, homeDir);
+    const currentContent = existsSync(graphPath) ? readFileSync(graphPath, "utf-8") : undefined;
+    const plan = planMemorySync(canonical, currentContent);
+    return { configured: true, graphPath, plan };
+}
+export function applyMemorySync(result) {
+    if (!result.configured || !result.plan.nextGraph)
+        return;
+    mkdirSync(dirname(result.graphPath), { recursive: true });
+    writeFileSync(result.graphPath, renderMemoryGraph(result.plan.nextGraph));
+}
+/**
+ * Extracted from `runMemorySync` (trellis-onboard-mcp-memory) so
+ * `onboard`'s own chained output can print this stage in the exact same
+ * format without a second, drifting copy — mirrors the
+ * `collect...Report`/`print...Report` export pair every other chained
+ * stage (`sync`, `mcp sync`, `secrets audit`) already has.
+ */
+export function printMemorySyncResult(result, dryRun) {
+    if (!result.configured) {
+        console.log(result.reason);
+        return;
+    }
+    console.log(`${dryRun ? "[dry run] " : ""}memory sync — ${result.graphPath}`);
+    if (result.plan.items.length === 0) {
+        console.log("  nothing in canonical memories/ yet");
+    }
+    for (const item of result.plan.items) {
+        console.log(`  [${item.action}] "${item.name}" — ${item.detail}`);
+    }
+}
+export function runMemorySync(opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    let result;
+    try {
+        result = collectMemorySyncResult(homeDir);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
+    }
+    if (!opts.dryRun) {
+        applyMemorySync(result);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        printMemorySyncResult(result, opts.dryRun ?? false);
+    }
+    const hasConflict = result.configured && result.plan.items.some((i) => i.action === "conflict");
+    return { exitCode: hasConflict ? 1 : 0 };
+}

package/dist/commands/migrate.d.ts

@@ -4,26 +4,52 @@
  * Pure `collectMigratePlan` / effectful `applyMigratePlan`, same
  * plan-then-apply split every adapter already uses.
  */
-import type { AgentId } from "../core/types.js";
-export type MigrateAction = "create" | "skip-symlink" | "skip-case-broken" | "already-migrated" | "conflict";
+import type { AgentId, McpServerDef } from "../core/types.js";
+export type MigrateAction = "create" | "skip-symlink" | "skip-case-broken" | "skip-unsupported" | "already-migrated" | "conflict";
+/** Internal kind naming, unchanged since before `--only` existed
+ * (trellis-migrate-category-selection design.md D2) — the CLI-facing
+ * flag value is the plural `"skills"`, mapped to this singular `"skill"`
+ * in `runMigrate`, not renamed here to avoid touching every existing
+ * `MigratePlanItem.kind` comparison for no functional reason. */
+export type MigrateKind = "skill" | "instructions" | "mcp";
 export interface MigratePlanItem {
-    kind: "skill" | "instructions";
+    kind: MigrateKind;
     name: string;
     action: MigrateAction;
     detail: string;
     /** Only set when action === "create"; consumed by applyMigratePlan. */
     sourceDir?: string;
     sourceContent?: string;
+    /** Only set when kind === "mcp" && action === "create". */
+    mcpDef?: McpServerDef;
 }
 export interface MigratePlan {
     agent: AgentId;
     present: boolean;
     items: MigratePlanItem[];
 }
-export declare function collectMigratePlan(agent: AgentId, homeDir?: string): Promise<MigratePlan>;
+/**
+ * `only` restricts which kind(s) are even considered — not a post-hoc
+ * filter on a fully-computed plan (trellis-migrate-category-selection
+ * design.md D3): the excluded kind's canonical path is never read for
+ * comparison and never appears in the plan, not even as a suppressed
+ * conflict. Omitting `only` (or passing both kinds) is exactly today's
+ * behavior.
+ */
+export declare function collectMigratePlan(agent: AgentId, homeDir?: string, only?: readonly MigrateKind[]): Promise<MigratePlan>;
 export declare function applyMigratePlan(plan: MigratePlan, homeDir?: string): void;
+/** CLI-facing spelling: `"skills"` (plural — a run usually touches more
+ * than one), `"instructions"` (already singular-shaped), or `"mcp"`
+ * (already the CLI's own convention, matching `trellis mcp`'s own
+ * command name). Mapped to `MigrateKind` in `runMigrate`, the one place
+ * this translation lives. */
+export type MigrateOnlyValue = "skills" | "instructions" | "mcp";
 export interface RunMigrateOptions {
     from?: string;
+    /** Restricts the run to one category (`"skills"`, `"instructions"`, or
+     * `"mcp"`, raw and unvalidated same as `from` — `runMigrate` checks
+     * it). `undefined` means all three, exactly as before `"mcp"` existed. */
+    only?: string;
     dryRun?: boolean;
     json?: boolean;
     /** Defaults to the real `~`; overridable for tests only. */

package/dist/commands/migrate.js

@@ -12,7 +12,10 @@ import * as codexProbe from "../probes/codex.js";
 import * as kiroProbe from "../probes/kiro.js";
 import * as piProbe from "../probes/pi.js";
 import { AGENTS_MD_TEMPLATE } from "./init.js";
-import { dirContentsEqual } from "../lib/dirEquals.js";
+import { decideDirImport } from "../lib/dirEquals.js";
+import { deepEqual } from "../lib/deepEqual.js";
+import { readClaudeCodeMcpDefs, readCodexMcpDefs, readKiroMcpDefs } from "../lib/mcpMigrateRead.js";
+import { loadCanonicalSource, upsertServerYaml } from "../core/canonical.js";
 import { ALL_AGENTS } from "../core/types.js";
 const PROBES = {
     "claude-code": (homeDir) => claudeCodeProbe.probe(homeDir),
@@ -20,6 +23,14 @@ const PROBES = {
     kiro: (homeDir) => kiroProbe.probe(homeDir),
     pi: (homeDir) => piProbe.probe(homeDir),
 };
+/** pi has no static MCP config to read at all (roadmap.md P14/
+ * trellis-migrate-mcp-servers) — deliberately absent, not an oversight;
+ * `collectMigratePlan` skips the `mcp` category entirely for pi. */
+const MCP_READERS = {
+    "claude-code": readClaudeCodeMcpDefs,
+    kiro: readKiroMcpDefs,
+    codex: readCodexMcpDefs,
+};
 function planSkill(name, sourceDir, isSymlink, caseCorrect, canonicalDir) {
     if (isSymlink) {
         return { kind: "skill", name, action: "skip-symlink", detail: "shared in from elsewhere, not this agent's own content" };
@@ -27,13 +38,14 @@ function planSkill(name, sourceDir, isSymlink, caseCorrect, canonicalDir) {
     if (!caseCorrect) {
         return { kind: "skill", name, action: "skip-case-broken", detail: "already undiscoverable on at least one other agent — fix on the source before migrating" };
     }
-    if (!existsSync(canonicalDir)) {
-        return { kind: "skill", name, action: "create", detail: `will copy from ${sourceDir}`, sourceDir };
-    }
-    if (dirContentsEqual(sourceDir, canonicalDir)) {
-        return { kind: "skill", name, action: "already-migrated", detail: "canonical content is byte-identical" };
+    switch (decideDirImport(sourceDir, canonicalDir)) {
+        case "create":
+            return { kind: "skill", name, action: "create", detail: `will copy from ${sourceDir}`, sourceDir };
+        case "already-present":
+            return { kind: "skill", name, action: "already-migrated", detail: "canonical content is byte-identical" };
+        case "conflict":
+            return { kind: "skill", name, action: "conflict", detail: `canonical skills/${name}/ already exists with different content — resolve by hand` };
     }
-    return { kind: "skill", name, action: "conflict", detail: `canonical skills/${name}/ already exists with different content — resolve by hand` };
 }
 function planInstructions(snapshot, canonicalAgentsMd) {
     if (!snapshot.instructionsFile)
@@ -60,21 +72,56 @@ function planInstructions(snapshot, canonicalAgentsMd) {
     }
     return { kind: "instructions", name: "agents.md", action: "conflict", detail: "canonical agents.md already has different real content — resolve by hand" };
 }
-export async function collectMigratePlan(agent, homeDir = homedir()) {
+function planMcpServer(name, def, existing) {
+    if (existing === undefined) {
+        return { kind: "mcp", name, action: "create", detail: "will add to servers.yaml", mcpDef: def };
+    }
+    if (deepEqual(existing, def)) {
+        return { kind: "mcp", name, action: "already-migrated", detail: "canonical definition is already identical" };
+    }
+    return { kind: "mcp", name, action: "conflict", detail: `canonical mcp/servers.yaml already has a different definition for "${name}" — resolve by hand` };
+}
+/**
+ * `only` restricts which kind(s) are even considered — not a post-hoc
+ * filter on a fully-computed plan (trellis-migrate-category-selection
+ * design.md D3): the excluded kind's canonical path is never read for
+ * comparison and never appears in the plan, not even as a suppressed
+ * conflict. Omitting `only` (or passing both kinds) is exactly today's
+ * behavior.
+ */
+export async function collectMigratePlan(agent, homeDir = homedir(), only) {
     const snapshot = await PROBES[agent](homeDir);
     if (!snapshot.present) {
         return { agent, present: false, items: [] };
     }
     const canonicalRoot = join(homeDir, ".trellis");
     const items = [];
-    for (const root of snapshot.skillRoots) {
-        for (const skill of root.skills) {
-            items.push(planSkill(skill.name, skill.dir, skill.isSymlink, skill.caseCorrect, join(canonicalRoot, "skills", skill.name)));
+    const wants = (kind) => !only || only.includes(kind);
+    if (wants("skill")) {
+        for (const root of snapshot.skillRoots) {
+            for (const skill of root.skills) {
+                items.push(planSkill(skill.name, skill.dir, skill.isSymlink, skill.caseCorrect, join(canonicalRoot, "skills", skill.name)));
+            }
+        }
+    }
+    if (wants("instructions")) {
+        const instructionsItem = planInstructions(snapshot, join(canonicalRoot, "agents.md"));
+        if (instructionsItem)
+            items.push(instructionsItem);
+    }
+    if (wants("mcp")) {
+        const reader = MCP_READERS[agent];
+        if (reader) {
+            const canonicalServers = loadCanonicalSource(homeDir).mcp.servers;
+            const { entries, unsupported } = reader(homeDir);
+            for (const { name, def } of entries) {
+                items.push(planMcpServer(name, def, canonicalServers[name]));
+            }
+            for (const { name, reason } of unsupported) {
+                items.push({ kind: "mcp", name, action: "skip-unsupported", detail: reason });
+            }
         }
     }
-    const instructionsItem = planInstructions(snapshot, join(canonicalRoot, "agents.md"));
-    if (instructionsItem)
-        items.push(instructionsItem);
     return { agent, present: true, items };
 }
 export function applyMigratePlan(plan, homeDir = homedir()) {
@@ -91,8 +138,22 @@ export function applyMigratePlan(plan, homeDir = homedir()) {
             mkdirSync(canonicalRoot, { recursive: true });
             writeFileSync(join(canonicalRoot, "agents.md"), item.sourceContent);
         }
+        else if (item.kind === "mcp" && item.mcpDef) {
+            upsertServerYaml(join(canonicalRoot, "mcp", "servers.yaml"), item.name, item.mcpDef);
+        }
     }
 }
+const ONLY_VALUES = ["skills", "instructions", "mcp"];
+function isMigrateOnlyValue(value) {
+    return ONLY_VALUES.includes(value);
+}
+function toMigrateKinds(only) {
+    if (only === "skills")
+        return ["skill"];
+    if (only === "instructions")
+        return ["instructions"];
+    return ["mcp"];
+}
 export async function runMigrate(opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
     if (!opts.from || !ALL_AGENTS.includes(opts.from)) {
@@ -100,7 +161,12 @@ export async function runMigrate(opts = {}) {
         return { exitCode: 1 };
     }
     const agent = opts.from;
-    const plan = await collectMigratePlan(agent, homeDir);
+    if (opts.only !== undefined && !isMigrateOnlyValue(opts.only)) {
+        console.error(`--only must be one of: ${ONLY_VALUES.join(", ")} (got ${opts.only})`);
+        return { exitCode: 1 };
+    }
+    const only = opts.only && isMigrateOnlyValue(opts.only) ? toMigrateKinds(opts.only) : undefined;
+    const plan = await collectMigratePlan(agent, homeDir, only);
     if (!plan.present) {
         console.error(`${agent} is not present on this machine — nothing to migrate.`);
         return { exitCode: 1 };
@@ -127,6 +193,7 @@ export function printPlan(plan, dryRun) {
         return;
     }
     for (const item of plan.items) {
-        console.log(`  [${item.action}] ${item.kind === "skill" ? `skill "${item.name}"` : "instructions"} — ${item.detail}`);
+        const label = item.kind === "skill" ? `skill "${item.name}"` : item.kind === "mcp" ? `mcp server "${item.name}"` : "instructions";
+        console.log(`  [${item.action}] ${label} — ${item.detail}`);
     }
 }

package/dist/commands/onboard.d.ts

@@ -1,21 +1,23 @@
 /**
  * `trellis onboard` — chains `init` → agent detection → migration-source
- * resolution → managed-agent-set selection (install-then-manage for a
+ * resolution → migrate-category selection (trellis-migrate-category-
+ * selection) → managed-agent-set selection (install-then-manage for a
  * selected, not-yet-present agent) → `migrate` → `sync` → `mcp sync` →
  * `secrets audit` into one guided flow (trellis-cli-onboard,
  * trellis-managed-agents) — a user should never have to type a second
- * command by hand to finish onboarding. Source and managed set are
- * independent choices (design.md D2): importing from a source never
- * writes back to it, and it is not implicitly added to the managed set.
- * Orchestrates existing commands' own plan/apply logic; no new
- * skill-copy, symlink, conflict-detection, or secrets-scanning judgment
- * is made here.
+ * command by hand to finish onboarding. Source, categories, and managed
+ * set are three independent choices (design.md D2): importing from a
+ * source never writes back to it, and it is not implicitly added to the
+ * managed set. Orchestrates existing commands' own plan/apply logic; no
+ * new skill-copy, symlink, conflict-detection, or secrets-scanning
+ * judgment is made here.
  */
 import type { AgentId } from "../core/types.js";
-import type { MigratePlan } from "./migrate.js";
+import type { MigrateKind, MigratePlan } from "./migrate.js";
 import type { SyncReport } from "./sync.js";
 import type { McpSyncReport } from "./mcp.js";
 import type { SecretsAuditReport } from "./secretsAudit.js";
+import type { MemorySyncResult } from "./memory.js";
 import type { ConfirmAndInstallOptions } from "../lib/installAgent.js";
 export interface OnboardAgentSummary {
     agent: AgentId;
@@ -26,6 +28,13 @@ export interface OnboardAgentSummary {
      * of that agent's own to potentially migrate, not a judgment about
      * its quality or length. */
     hasRealInstructions: boolean;
+    /** How many real MCP servers `migrate --only mcp` would find for this
+     * agent — computed via `collectMigratePlan(agent, homeDir, ["mcp"])`
+     * rather than a second reader dispatch, so this always agrees with
+     * what migrate itself will do (design.md D1, trellis-onboard-mcp-
+     * memory). 0 for pi, which has no MCP reader at all — not a gap here,
+     * the same fact `migrate.ts` already establishes. */
+    mcpServerCount: number;
 }
 export declare function collectOnboardSummary(homeDir?: string): Promise<OnboardAgentSummary[]>;
 export interface RunOnboardOptions {
@@ -50,6 +59,11 @@ export interface RunOnboardOptions {
      * pre-parsed list — so the same parsing/validation code path is
      * exercised whether the answer came from a flag or a prompt. */
     promptForManagedAgents?: (candidates: OnboardAgentSummary[], alreadyManaged: readonly AgentId[]) => Promise<string>;
+    /** Test-only: replaces the real migrate-category picker/default logic
+     * (trellis-migrate-category-selection). An empty array is a valid
+     * answer — "skip migrate for this run" (design.md D6) — distinct from
+     * `source` being unresolved at all. */
+    promptForMigrateCategories?: (source: OnboardAgentSummary) => Promise<MigrateKind[]>;
     /** Test-only: injected into every `confirmAndInstall` call for a
      * selected, not-yet-present agent. Never a real terminal prompt or a
      * real `npm install` in a unit test. */
@@ -70,8 +84,13 @@ export interface OnboardResult {
     managedAgents?: AgentId[];
     installResults?: OnboardInstallResult[];
     migratePlan?: MigratePlan;
+    /** Set when a source was resolved but zero migrate categories were
+     * selected (design.md D6) — distinct from `migratePlan` being absent
+     * because no source existed at all, which prints nothing here. */
+    migrateSkipped?: string;
     syncReport?: SyncReport;
     mcpSyncReport?: McpSyncReport;
+    memorySyncResult?: MemorySyncResult;
     secretsAuditReport?: SecretsAuditReport;
     refusal?: string;
     /** Only set when no agent is present — the same values `--json` and

package/dist/commands/onboard.js

@@ -1,20 +1,22 @@
 /**
  * `trellis onboard` — chains `init` → agent detection → migration-source
- * resolution → managed-agent-set selection (install-then-manage for a
+ * resolution → migrate-category selection (trellis-migrate-category-
+ * selection) → managed-agent-set selection (install-then-manage for a
  * selected, not-yet-present agent) → `migrate` → `sync` → `mcp sync` →
  * `secrets audit` into one guided flow (trellis-cli-onboard,
  * trellis-managed-agents) — a user should never have to type a second
- * command by hand to finish onboarding. Source and managed set are
- * independent choices (design.md D2): importing from a source never
- * writes back to it, and it is not implicitly added to the managed set.
- * Orchestrates existing commands' own plan/apply logic; no new
- * skill-copy, symlink, conflict-detection, or secrets-scanning judgment
- * is made here.
+ * command by hand to finish onboarding. Source, categories, and managed
+ * set are three independent choices (design.md D2): importing from a
+ * source never writes back to it, and it is not implicitly added to the
+ * managed set. Orchestrates existing commands' own plan/apply logic; no
+ * new skill-copy, symlink, conflict-detection, or secrets-scanning
+ * judgment is made here.
  */
 import { createInterface } from "node:readline/promises";
 import { homedir } from "node:os";
 import { writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { canUseInteractivePicker, runMultiSelectPicker, runSingleSelectPicker } from "../lib/terminalPicker.js";
 import * as claudeCodeProbe from "../probes/claude-code.js";
 import * as codexProbe from "../probes/codex.js";
 import * as kiroProbe from "../probes/kiro.js";
@@ -26,6 +28,7 @@ import { applyMigratePlan, collectMigratePlan, printPlan as printMigratePlan } f
 import { collectSyncReport, printReport as printSyncReport } from "./sync.js";
 import { collectMcpSyncReport, printReport as printMcpSyncReport } from "./mcp.js";
 import { collectSecretsAuditReport, printReport as printSecretsAuditReport } from "./secretsAudit.js";
+import { applyMemorySync, collectMemorySyncResult, printMemorySyncResult } from "./memory.js";
 import { openBackupSession } from "../lib/backup.js";
 import { confirmAndInstall } from "../lib/installAgent.js";
 const PROBES = {
@@ -38,23 +41,30 @@ export async function collectOnboardSummary(homeDir = homedir()) {
     return Promise.all(ALL_AGENTS.map(async (agent) => {
         const snapshot = await PROBES[agent](homeDir);
         if (!snapshot.present) {
-            return { agent, present: false, skillCount: 0, skillNames: [], hasRealInstructions: false };
+            return { agent, present: false, skillCount: 0, skillNames: [], hasRealInstructions: false, mcpServerCount: 0 };
         }
         const skillNames = snapshot.skillRoots.flatMap((root) => root.skills.map((s) => s.name));
         const hasRealInstructions = snapshot.instructionsFile !== undefined && !snapshot.instructionsFile.isSymlink;
-        return { agent, present: true, skillCount: skillNames.length, skillNames, hasRealInstructions };
+        const mcpPlan = await collectMigratePlan(agent, homeDir, ["mcp"]);
+        return { agent, present: true, skillCount: skillNames.length, skillNames, hasRealInstructions, mcpServerCount: mcpPlan.items.length };
     }));
 }
 function hasContent(s) {
-    return s.skillCount > 0 || s.hasRealInstructions;
+    return s.skillCount > 0 || s.hasRealInstructions || s.mcpServerCount > 0;
 }
-async function promptForAgentReal(present) {
+function agentSummaryLabel(s) {
+    const skills = s.skillCount > 0 ? ` (${s.skillNames.join(", ")})` : "";
+    return `${s.agent} — ${s.skillCount} skill(s)${skills}, instructions: ${s.hasRealInstructions ? "yes" : "no"}, mcp: ${s.mcpServerCount}`;
+}
+/** Numbered-typing fallback (trellis-onboard-interactive-picker design.md
+ * D2) — used only when the terminal can't support the raw-mode picker
+ * (`canUseInteractivePicker()` false). Unchanged from before that change. */
+async function promptForAgentNumbered(present) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     try {
         console.log("Multiple agents detected:");
         present.forEach((s, i) => {
-            const skills = s.skillCount > 0 ? ` (${s.skillNames.join(", ")})` : "";
-            console.log(`  ${i + 1}) ${s.agent} — ${s.skillCount} skill(s)${skills}, instructions: ${s.hasRealInstructions ? "yes" : "no"}`);
+            console.log(`  ${i + 1}) ${agentSummaryLabel(s)}`);
         });
         for (let attempt = 0; attempt < 2; attempt++) {
             const answer = (await rl.question(`Choose a migration source [1-${present.length}]: `)).trim();
@@ -74,7 +84,28 @@ async function promptForAgentReal(present) {
         rl.close();
     }
 }
-async function promptForManagedAgentsReal(candidates, alreadyManaged) {
+/** Arrow-key single-select on a real, raw-mode-capable terminal; falls
+ * back to `promptForAgentNumbered` otherwise. Resolves to the exact same
+ * string contract either way — a real agent id — so `resolveMigrationSource`
+ * and every test injecting `RunOnboardOptions.promptForAgent` need no
+ * changes (design.md D5). Cancel (Ctrl+C) prints a message and exits
+ * directly, rather than threading a new "cancelled" state through the
+ * rest of onboard's return-based refusal plumbing. */
+async function promptForAgentReal(present) {
+    if (!canUseInteractivePicker()) {
+        return promptForAgentNumbered(present);
+    }
+    console.log("Multiple agents detected — use Up/Down (or j/k) and Enter to choose a migration source:");
+    const index = await runSingleSelectPicker(present.map(agentSummaryLabel));
+    if (index === null) {
+        console.log("cancelled, no changes made");
+        process.exit(1);
+    }
+    return present[index].agent;
+}
+/** Numbered-typing fallback — unchanged from before this change (see
+ * `promptForAgentNumbered`'s doc comment). */
+async function promptForManagedAgentsNumbered(candidates, alreadyManaged) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     try {
         console.log("Which agents should Trellis manage? (comma-separated numbers; enter for none new)");
@@ -90,6 +121,73 @@ async function promptForManagedAgentsReal(candidates, alreadyManaged) {
         rl.close();
     }
 }
+/** Checkbox multi-select on a real, raw-mode-capable terminal; falls
+ * back to `promptForManagedAgentsNumbered` otherwise. Resolves to the
+ * same comma-separated-agent-id string contract `parseManagedSelection`
+ * already parses — an empty selection resolves to `""` (comma-separated
+ * join of zero items), which `parseManagedSelection` already treats as
+ * "none" (design.md D5). Cancel behaves like `promptForAgentReal`'s. */
+async function promptForManagedAgentsReal(candidates, alreadyManaged) {
+    if (!canUseInteractivePicker()) {
+        return promptForManagedAgentsNumbered(candidates, alreadyManaged);
+    }
+    console.log("Which agents should Trellis manage? Up/Down (or j/k) to move, Space to toggle, Enter to confirm:");
+    const labels = candidates.map((s) => {
+        const status = s.present ? `present, ${s.skillCount} skill(s)` : "not installed";
+        return `${s.agent} — ${status}`;
+    });
+    const initiallyChecked = candidates.map((s) => alreadyManaged.includes(s.agent));
+    const indices = await runMultiSelectPicker(labels, initiallyChecked);
+    if (indices === null) {
+        console.log("cancelled, no changes made");
+        process.exit(1);
+    }
+    return indices.map((i) => candidates[i].agent).join(",");
+}
+/**
+ * Resolves which categories (skills, instructions) to migrate from a
+ * resolved source (trellis-migrate-category-selection, extended to a
+ * third category by trellis-onboard-mcp-memory design.md D2). Unlike the
+ * two pickers above, there is no numbered-text fallback to preserve
+ * parity with — this concept never existed before this change, so
+ * "can't prompt" simply means "default to whichever kind(s) actually
+ * have real content, silently" (design.md D4). The picker itself is
+ * only offered when the choice is meaningful — two or more kinds
+ * present, a capable terminal, and not a `--json` run (design.md D5).
+ * An empty result is a valid answer: "skip migrate for this run"
+ * (design.md D6), left for the caller to act on.
+ */
+async function resolveMigrateCategories(source, opts) {
+    // Built dynamically, in skill/instructions/mcp display order — not a
+    // fixed two- or three-slot structure, so a fourth category some day
+    // would only need an entry here, not a rewritten branch (design.md D2).
+    const candidates = [];
+    if (source.skillCount > 0)
+        candidates.push({ kind: "skill", label: "skills" });
+    if (source.hasRealInstructions)
+        candidates.push({ kind: "instructions", label: "instructions" });
+    if (source.mcpServerCount > 0)
+        candidates.push({ kind: "mcp", label: "mcp" });
+    // The choice is only meaningful when two or more kinds are real — same
+    // gate for the injected test seam as for the real picker, mirroring
+    // how `promptForAgent`/`promptForManagedAgents` are only ever
+    // consulted when their own real prompt would actually apply.
+    if (candidates.length > 1 && !opts.json) {
+        if (opts.promptForMigrateCategories) {
+            return opts.promptForMigrateCategories(source);
+        }
+        if (canUseInteractivePicker()) {
+            console.log(`Which categories should be migrated from ${source.agent}? Space to toggle, Enter to confirm:`);
+            const indices = await runMultiSelectPicker(candidates.map((c) => c.label), candidates.map(() => true));
+            if (indices === null) {
+                console.log("cancelled, no changes made");
+                process.exit(1);
+            }
+            return indices.map((i) => candidates[i].kind);
+        }
+    }
+    return candidates.map((c) => c.kind);
+}
 /** Shared by `--manage` and the interactive prompt's answer — same
  * grammar either way (design.md D4): a real agent id list, comma- or
  * whitespace-separated numbers referring to `candidates`' own order, or
@@ -224,10 +322,18 @@ export async function collectOnboardPlan(opts = {}) {
         writeManagedYaml(homeDir, managedAgents);
     }
     let migratePlan;
+    let migrateSkipped;
     if (source) {
-        migratePlan = await collectMigratePlan(source, homeDir);
-        if (!opts.dryRun) {
-            applyMigratePlan(migratePlan, homeDir);
+        const sourceSummary = summary.find((s) => s.agent === source);
+        const categories = await resolveMigrateCategories(sourceSummary, opts);
+        if (categories.length > 0) {
+            migratePlan = await collectMigratePlan(source, homeDir, categories);
+            if (!opts.dryRun) {
+                applyMigratePlan(migratePlan, homeDir);
+            }
+        }
+        else {
+            migrateSkipped = "migrate skipped — no categories selected";
         }
     }
     // One session for the whole chained run (trellis-backup-rollback) —
@@ -238,6 +344,15 @@ export async function collectOnboardPlan(opts = {}) {
     const syncReport = await collectSyncReport({ homeDir, dryRun: opts.dryRun, managedAgents, backupSession });
     const mcpSyncReport = await collectMcpSyncReport({ homeDir, dryRun: opts.dryRun, managedAgents, backupSession });
     backupSession?.finalize();
+    // Independent of `managedAgents` — the shared memory server is not
+    // per-agent (design.md D4, trellis-onboard-mcp-memory), unlike
+    // sync/mcp-sync above. Runs unconditionally once reached; an
+    // unconfigured `memory` server is a legitimate "nothing to do yet"
+    // state (design.md D5), not gated on any prior step here.
+    const memorySyncResult = collectMemorySyncResult(homeDir);
+    if (!opts.dryRun) {
+        applyMemorySync(memorySyncResult);
+    }
     // Read-only, no dryRun concept — same report either way, run last since
     // it audits the config mcp sync just wrote (or, on --dry-run, whatever
     // was already there before this run).
@@ -249,8 +364,10 @@ export async function collectOnboardPlan(opts = {}) {
         managedAgents,
         installResults: installResults.length > 0 ? installResults : undefined,
         migratePlan,
+        migrateSkipped,
         syncReport,
         mcpSyncReport,
+        memorySyncResult,
         secretsAuditReport,
     };
 }
@@ -264,9 +381,11 @@ export async function runOnboard(opts = {}) {
     }
     if (result.refusal)
         return { exitCode: 1 };
+    const memorySyncConflict = result.memorySyncResult?.configured === true && result.memorySyncResult.plan.items.some((i) => i.action === "conflict");
     const hasConflict = (result.migratePlan?.items.some((i) => i.action === "conflict") ?? false) ||
         (result.syncReport?.reports.some((r) => r.items.some((i) => i.action === "conflict")) ?? false) ||
         (result.mcpSyncReport?.reports.some((r) => r.items.some((i) => i.action === "conflict")) ?? false) ||
+        memorySyncConflict ||
         (result.secretsAuditReport?.findings.length ?? 0) > 0;
     return { exitCode: hasConflict ? 1 : 0 };
 }
@@ -313,6 +432,10 @@ function printResult(result, dryRun) {
         console.log("");
         printMigratePlan(result.migratePlan, false);
     }
+    else if (result.migrateSkipped) {
+        console.log("");
+        console.log(result.migrateSkipped);
+    }
     if (result.syncReport) {
         console.log("\nsync");
         printSyncReport(result.syncReport, false);
@@ -321,6 +444,10 @@ function printResult(result, dryRun) {
         console.log("\nmcp sync");
         printMcpSyncReport(result.mcpSyncReport, false);
     }
+    if (result.memorySyncResult) {
+        console.log("\nmemory sync");
+        printMemorySyncResult(result.memorySyncResult, false);
+    }
     if (result.secretsAuditReport) {
         console.log("\nsecrets audit");
         printSecretsAuditReport(result.secretsAuditReport);