agent-trellis 0.3.0 → 0.4.0

package/dist/commands/memory.d.ts

@@ -34,6 +34,14 @@ export type MemorySyncResult = {
  */
 export declare function collectMemorySyncResult(homeDir?: string): MemorySyncResult;
 export declare function applyMemorySync(result: MemorySyncResult): void;
+/**
+ * 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 declare function printMemorySyncResult(result: MemorySyncResult, dryRun: boolean): void;
 export declare function runMemorySync(opts?: RunMemorySyncOptions): {
     exitCode: number;
 };

package/dist/commands/memory.js

@@ -45,6 +45,26 @@ export function applyMemorySync(result) {
     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;
@@ -61,17 +81,8 @@ export function runMemorySync(opts = {}) {
     if (opts.json) {
         console.log(JSON.stringify(result, null, 2));
     }
-    else if (!result.configured) {
-        console.log(result.reason);
-    }
     else {
-        console.log(`${opts.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}`);
-        }
+        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/onboard.d.ts

@@ -17,6 +17,7 @@ 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;
@@ -27,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 {
@@ -82,6 +90,7 @@ export interface OnboardResult {
     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

@@ -28,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 = {
@@ -40,19 +41,20 @@ 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;
 }
 function agentSummaryLabel(s) {
     const skills = s.skillCount > 0 ? ` (${s.skillNames.join(", ")})` : "";
-    return `${s.agent} — ${s.skillCount} skill(s)${skills}, instructions: ${s.hasRealInstructions ? "yes" : "no"}`;
+    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
@@ -144,48 +146,47 @@ async function promptForManagedAgentsReal(candidates, alreadyManaged) {
 }
 /**
  * Resolves which categories (skills, instructions) to migrate from a
- * resolved source (trellis-migrate-category-selection). 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 — both 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.
+ * 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) {
-    const wantsSkills = source.skillCount > 0;
-    const wantsInstructions = source.hasRealInstructions;
-    // The choice is only meaningful when both 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 (wantsSkills && wantsInstructions && !opts.json) {
+    // 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(["skills", "instructions"], [true, true]);
+            const indices = await runMultiSelectPicker(candidates.map((c) => c.label), candidates.map(() => true));
             if (indices === null) {
                 console.log("cancelled, no changes made");
                 process.exit(1);
             }
-            const kinds = [];
-            if (indices.includes(0))
-                kinds.push("skill");
-            if (indices.includes(1))
-                kinds.push("instructions");
-            return kinds;
+            return indices.map((i) => candidates[i].kind);
         }
     }
-    const kinds = [];
-    if (wantsSkills)
-        kinds.push("skill");
-    if (wantsInstructions)
-        kinds.push("instructions");
-    return kinds;
+    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
@@ -343,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).
@@ -357,6 +367,7 @@ export async function collectOnboardPlan(opts = {}) {
         migrateSkipped,
         syncReport,
         mcpSyncReport,
+        memorySyncResult,
         secretsAuditReport,
     };
 }
@@ -370,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 };
 }
@@ -431,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);

package/docs/getting-started.md

@@ -17,17 +17,23 @@ $ trellis onboard
 
 Runs `init`, detects which of Claude Code/Codex/Kiro/pi are on this machine,
 then resolves two independent choices before running `migrate`, `sync`,
-`mcp sync`, and `secrets audit` — the whole onboarding path, no follow-up
-commands to type by hand:
+`mcp sync`, `memory sync`, and `secrets audit` — the whole onboarding path,
+no follow-up commands to type by hand:
 
 1. **Migration source** — read from, at most one, never written back to.
+   "Real content" means skills, custom instructions, *or* real MCP servers
+   — an agent whose only real content is its MCP servers is still a valid
+   source.
    - **No agent has real content**: skipped — canonical starts from `init`'s
      placeholder.
    - **Exactly one agent has real content**: auto-selected, no prompt.
    - **Two or more**: prompts you to choose (Up/Down or j/k, Enter to confirm,
      on a real terminal that supports it — falls back to a numbered
      type-a-digit prompt otherwise), or pass `--agent <id>` to skip the
-     prompt entirely.
+     prompt entirely. Which *categories* to bring in from that source
+     (skills, instructions, mcp) is its own checkbox, shown only when the
+     source has real content in two or more of them — with just one, that
+     one is migrated unprompted.
 2. **Managed set** — zero or more agents to actually write to. Always an
    explicit choice: pass `--manage <ids>` (comma-separated, e.g. `--manage
    pi,codex`) or `--manage none`, or answer the interactive checkbox prompt
@@ -54,6 +60,9 @@ sync
 mcp sync
   ✅ pi — already in sync
 
+memory sync
+  no "memory" MCP server with static_env.MEMORY_FILE_PATH configured in servers.yaml — see schema/servers.example.yaml
+
 secrets audit
   ✅ no findings — every present agent's real config and every declared env var passed all checks
 ```
@@ -63,9 +72,9 @@ it's present and was the migration source, but it isn't managed, so it's
 never even probed as a sync target, not just left with zero items.
 
 Add `--dry-run` to preview the entire chain — init/migrate/sync/mcp
-sync, including what would be written to `~/.trellis/managed.yaml` — with
-zero writes anywhere (secrets audit is always read-only, with or without
-the flag).
+sync/memory sync, including what would be written to
+`~/.trellis/managed.yaml` — with zero writes anywhere (secrets audit is
+always read-only, with or without the flag).
 
 **A managed agent's own real content still isn't overwritten.** If you
 explicitly include the source in `--manage`, sync still never overwrites

package/docs/roadmap.md

@@ -899,6 +899,35 @@ byte-identical for both transports, now covered by its own test), so
 that distinction was never stored in the first place. 350/350 tests
 passing.
 
+**P17 (✅ done, archived
+[2026-09-13-trellis-onboard-mcp-memory](../openspec/changes/archive/2026-09-13-trellis-onboard-mcp-memory/)):
+`onboard` catches up to P15/P16 — mcp and memory were never wired into
+its own orchestration.** Found by live dogfooding on a real machine:
+`onboard`'s migrate-category picker hardcoded `["skills",
+"instructions"]` — `mcp` was invisible to it regardless of how many real
+MCP servers the source agent had — and `trellis memory sync` was never
+called anywhere in `onboard`'s chain at all, despite its own docstring
+naming a complete chain. `OnboardAgentSummary` gains an
+`mcpServerCount`, computed via the already-exported
+`collectMigratePlan(agent, homeDir, ["mcp"])` rather than a second reader
+dispatch — so it always agrees with what `migrate` itself would do, and
+an agent whose only real content is MCP servers is now a valid migration
+source (previously invisible to `hasContent` entirely).
+`resolveMigrateCategories` was rewritten from a fixed two-slot structure
+to a dynamically-built list of whichever of skill/instructions/mcp have
+real content, offering the checkbox only when two or more do — not a
+bolted-on special case for a third option. `memory sync` runs as a new
+final chained stage, after `mcp sync` and before `secrets audit`,
+independent of the resolved managed-agent set (the memory server is
+shared, not per-agent); `runMemorySync`'s inline printing was extracted
+into an exported `printMemorySyncResult` so `onboard` reuses the exact
+same output format rather than a second, drifting copy of it —
+`memory.ts`'s own standalone command behavior is unchanged, confirmed by
+its existing tests passing unmodified. No change to `migrate.ts`,
+`mcp.ts`, or `memory.ts`'s own command behavior — purely `onboard`'s
+orchestration layer catching up to commands that already existed. 357/357
+tests passing.
+
 | Phase | Deliverable | Depends on |
 |---|---|---|
 | P0 | ✅ `trellis doctor` — read-only, opt-in-for-handshakes scan of all four agents' current skills/MCP/instructions state, reports drift and duplicates | nothing |
@@ -918,6 +947,7 @@ passing.
 | P14 | ✅ MCP server lifecycle parity with skills: ownership-tracked safe removal on sync (migrate-in closed separately by P16) | P2, P13 |
 | P15 | ✅ Shared memory: ingest canonical `memories/*.md` into the `server-memory` store's own graph file (per-agent extraction into canonical remains a separate, open gap) | P6 |
 | P16 | ✅ MCP migrate-in: `trellis migrate --only mcp` for claude-code/kiro/codex (codex remote transport + probe HOME-scoping closed same-day, see prose above), closing the gap P14 named | P12, P14 |
+| P17 | ✅ `onboard` orchestration catches up to P15/P16: three-way migrate-category selection (mcp added), `memory sync` wired in as a chained stage | P15, P16 |
 
 No dates. This is scoped by verification milestones, not calendar time.
 Execution order for P11–P16: P11 → P12 → P13 → P14 → P15 → P16 — CRUD

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-trellis",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A single source of capability for every coding agent — skills, MCP, subagents, memory, and secret policy, adapted natively into Claude Code, Codex, Kiro, and pi.",
   "license": "MIT",
   "author": "Paul Leo",