agent-trellis 0.3.0 → 0.5.2

package/dist/adapters/jsonMcp.js

@@ -7,6 +7,7 @@
  * through untouched.
  */
 import { deepEqual } from "../lib/deepEqual.js";
+import { resolvedEnvTextMap } from "../lib/mcpMigrateRead.js";
 import { resolveMcpPlan } from "./mcpPlan.js";
 /** Renders the native JSON shape Claude Code/Kiro's `mcpServers` map
  * expects — `env` names render as `${VAR}` references, `staticEnv`
@@ -23,8 +24,7 @@ export function renderJsonServerEntry(def) {
         return entry;
     }
     const entry = { type: "stdio", command: def.command, args: def.args ?? [] };
-    const nameRefs = Object.fromEntries((def.env ?? []).map((name) => [name, `\${${name}}`]));
-    const env = { ...nameRefs, ...(def.staticEnv ?? {}) };
+    const env = resolvedEnvTextMap(def);
     if (Object.keys(env).length > 0) {
         entry.env = env;
     }

package/dist/adapters/mcpPlan.js

@@ -53,9 +53,16 @@ function findLiteralSecret(def) {
  * proposal.md "Why"). Uses the identical `resolveSecretEnv` `secrets
  * audit`/the pi bridge already call, so this and a later `secrets audit`
  * run can never disagree about what resolves.
+ *
+ * `envAliases`' values are themselves source variable names needing the
+ * exact same resolution — checked in the same pass so a differently-named
+ * reference gets the same pre-write refusal `env` already has, naming the
+ * unresolved *source* name (what the caller must find a value for), not
+ * the target key it would have been written under
+ * (trellis-migrate-env-var-alias).
  */
 function findUnresolvedEnvName(def, policy) {
-    const names = def.env ?? [];
+    const names = [...(def.env ?? []), ...Object.values(def.envAliases ?? {})];
     if (names.length === 0)
         return undefined;
     const resolved = resolveSecretEnv(names, policy);

package/dist/cli.js

@@ -13,7 +13,7 @@ import { runMcpSync, runMcpList, runMcpAdd, runMcpRemove, parseMcpAddArgs } from
 import { runSecretsAudit } from "./commands/secretsAudit.js";
 import { runRollback } from "./commands/rollback.js";
 import { runSkillList, runSkillAdd, runSkillRemove } from "./commands/skill.js";
-import { runMemorySync } from "./commands/memory.js";
+import { runMemoryExtraction, runMemorySync } from "./commands/memory.js";
 import { parseSyncArgs } from "./lib/syncArgs.js";
 const KNOWN_COMMANDS = ["onboard", "init", "migrate", "doctor", "sync", "mcp", "skill", "memory", "secrets", "rollback"];
 function printUsage() {
@@ -104,6 +104,14 @@ Commands:
               or relation this didn't create.
               --dry-run    preview the plan, write nothing
               --json       machine-readable output, no report text
+  memory extract
+            The reverse direction: read the same graph file's real,
+              non-Trellis entities (agent-accumulated content, never
+              Trellis's own) and write each as a new canonical
+              memories/*.md file — readable markdown, not meant to
+              round-trip byte-for-byte back through memory sync.
+              --dry-run    preview the plan, write nothing
+              --json       machine-readable output, no report text
   secrets audit
             Scan each present agent's real MCP config for leaked
             credentials and unexpected env var names
@@ -240,13 +248,18 @@ async function main(argv) {
     }
     if (command === "memory") {
         const [subcommand, ...memoryRest] = rest;
-        if (subcommand !== "sync") {
-            console.error(`Unknown memory subcommand: ${subcommand ?? "(none)"}\nUsage: trellis memory sync\n`);
-            process.exitCode = 1;
+        const json = memoryRest.includes("--json");
+        const dryRun = memoryRest.includes("--dry-run");
+        if (subcommand === "sync") {
+            process.exitCode = runMemorySync({ json, dryRun }).exitCode;
             return;
         }
-        const { exitCode } = runMemorySync({ json: memoryRest.includes("--json"), dryRun: memoryRest.includes("--dry-run") });
-        process.exitCode = exitCode;
+        if (subcommand === "extract") {
+            process.exitCode = runMemoryExtraction({ json, dryRun }).exitCode;
+            return;
+        }
+        console.error(`Unknown memory subcommand: ${subcommand ?? "(none)"}\nUsage: trellis memory sync|extract\n`);
+        process.exitCode = 1;
         return;
     }
     if (command === "secrets") {

package/dist/commands/memory.d.ts

@@ -1,13 +1,18 @@
 /**
- * `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.
+ * `trellis memory sync`/`trellis memory extract` — the two one-directional
+ * halves of Trellis's shared-memory story: 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); extract
+ * reads the graph's own real, non-Trellis entities back into new
+ * canonical files, closing P15's own explicitly-named "per-agent
+ * extraction into canonical remains a separate, open gap"
+ * (trellis-memory-extraction). Neither spawns or talks to a running
+ * server process — both are plain file operations, same posture as
+ * every other Trellis write.
  */
-import { type MemorySyncPlan } from "../lib/memoryGraph.js";
+import { type MemoryExtractionPlan, type MemorySyncPlan } from "../lib/memoryGraph.js";
 export interface RunMemorySyncOptions {
     homeDir?: string;
     json?: boolean;
@@ -21,19 +26,45 @@ export type MemorySyncResult = {
     configured: false;
     reason: string;
 };
-/**
- * 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 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;
 };
+export interface RunMemoryExtractionOptions {
+    homeDir?: string;
+    json?: boolean;
+    dryRun?: boolean;
+}
+export type MemoryExtractionResult = {
+    configured: true;
+    graphPath: string;
+    plan: MemoryExtractionPlan;
+} | {
+    configured: false;
+    reason: string;
+};
+/**
+ * The reverse direction of `collectMemorySyncResult`: reads the same
+ * graph file, but plans which of its real, non-`trellis-memory` entities
+ * (`planMemoryExtraction`) should become new canonical files — never the
+ * other way around, and never touching an entity `memory sync` itself
+ * owns (trellis-memory-extraction).
+ */
+export declare function collectMemoryExtractionResult(homeDir?: string): MemoryExtractionResult;
+export declare function applyMemoryExtraction(result: MemoryExtractionResult, homeDir?: string): void;
+/** Mirrors `printMemorySyncResult`'s own export-pair convention — reused
+ * verbatim if `onboard` ever chains this stage too, not a second,
+ * drifting copy. */
+export declare function printMemoryExtractionResult(result: MemoryExtractionResult, dryRun: boolean): void;
+export declare function runMemoryExtraction(opts?: RunMemoryExtractionOptions): {
+    exitCode: number;
+};

package/dist/commands/memory.js

@@ -1,17 +1,22 @@
 /**
- * `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.
+ * `trellis memory sync`/`trellis memory extract` — the two one-directional
+ * halves of Trellis's shared-memory story: 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); extract
+ * reads the graph's own real, non-Trellis entities back into new
+ * canonical files, closing P15's own explicitly-named "per-agent
+ * extraction into canonical remains a separate, open gap"
+ * (trellis-memory-extraction). Neither spawns or talks to a running
+ * server process — both are plain file operations, 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 { dirname, join } from "node:path";
 import { loadCanonicalSource } from "../core/canonical.js";
-import { planMemorySync, renderMemoryGraph } from "../lib/memoryGraph.js";
+import { parseMemoryGraph, planMemoryExtraction, planMemorySync, renderMemoryGraph } from "../lib/memoryGraph.js";
 const MEMORY_SERVER_NAME = "memory";
 /**
  * Looks up `mcp.servers["memory"]` specifically (matching `schema/
@@ -22,9 +27,12 @@ const MEMORY_SERVER_NAME = "memory";
  * 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.
+ * reliable way to predict. Shared by `collectMemorySyncResult` and
+ * `collectMemoryExtractionResult` — both directions must never disagree
+ * about which graph file they're reading/writing
+ * (trellis-memory-extraction).
  */
-export function collectMemorySyncResult(homeDir = homedir()) {
+function resolveMemoryServerGraphPath(homeDir) {
     const canonical = loadCanonicalSource(homeDir);
     const server = canonical.mcp.servers[MEMORY_SERVER_NAME];
     const rawPath = server?.staticEnv?.MEMORY_FILE_PATH;
@@ -34,10 +42,16 @@ export function collectMemorySyncResult(homeDir = homedir()) {
             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;
+    return { configured: true, graphPath: rawPath.replace(/^~(?=$|\/)/, homeDir) };
+}
+export function collectMemorySyncResult(homeDir = homedir()) {
+    const lookup = resolveMemoryServerGraphPath(homeDir);
+    if (!lookup.configured)
+        return lookup;
+    const canonical = loadCanonicalSource(homeDir);
+    const currentContent = existsSync(lookup.graphPath) ? readFileSync(lookup.graphPath, "utf-8") : undefined;
     const plan = planMemorySync(canonical, currentContent);
-    return { configured: true, graphPath, plan };
+    return { configured: true, graphPath: lookup.graphPath, plan };
 }
 export function applyMemorySync(result) {
     if (!result.configured || !result.plan.nextGraph)
@@ -45,6 +59,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 +95,79 @@ export function runMemorySync(opts = {}) {
     if (opts.json) {
         console.log(JSON.stringify(result, null, 2));
     }
-    else if (!result.configured) {
+    else {
+        printMemorySyncResult(result, opts.dryRun ?? false);
+    }
+    const hasConflict = result.configured && result.plan.items.some((i) => i.action === "conflict");
+    return { exitCode: hasConflict ? 1 : 0 };
+}
+function canonicalMemoryFilePath(homeDir, slug) {
+    return join(homeDir, ".trellis", "memories", `${slug}.md`);
+}
+/**
+ * The reverse direction of `collectMemorySyncResult`: reads the same
+ * graph file, but plans which of its real, non-`trellis-memory` entities
+ * (`planMemoryExtraction`) should become new canonical files — never the
+ * other way around, and never touching an entity `memory sync` itself
+ * owns (trellis-memory-extraction).
+ */
+export function collectMemoryExtractionResult(homeDir = homedir()) {
+    const lookup = resolveMemoryServerGraphPath(homeDir);
+    if (!lookup.configured)
+        return lookup;
+    const graphContent = existsSync(lookup.graphPath) ? readFileSync(lookup.graphPath, "utf-8") : undefined;
+    const graphLines = graphContent !== undefined ? parseMemoryGraph(graphContent) : [];
+    const plan = planMemoryExtraction(graphLines, (slug) => {
+        const file = canonicalMemoryFilePath(homeDir, slug);
+        return existsSync(file) ? readFileSync(file, "utf-8") : undefined;
+    });
+    return { configured: true, graphPath: lookup.graphPath, plan };
+}
+export function applyMemoryExtraction(result, homeDir = homedir()) {
+    if (!result.configured)
+        return;
+    for (const item of result.plan.items) {
+        if (item.action !== "create" || item.content === undefined)
+            continue;
+        const file = canonicalMemoryFilePath(homeDir, item.slug);
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, item.content);
+    }
+}
+/** Mirrors `printMemorySyncResult`'s own export-pair convention — reused
+ * verbatim if `onboard` ever chains this stage too, not a second,
+ * drifting copy. */
+export function printMemoryExtractionResult(result, dryRun) {
+    if (!result.configured) {
         console.log(result.reason);
+        return;
+    }
+    console.log(`${dryRun ? "[dry run] " : ""}memory extract — ${result.graphPath}`);
+    if (result.plan.items.length === 0) {
+        console.log("  nothing to extract — no non-trellis-memory entities with observations in the graph");
+    }
+    for (const item of result.plan.items) {
+        console.log(`  [${item.action}] "${item.name}" (${item.slug}.md) — ${item.detail}`);
+    }
+}
+export function runMemoryExtraction(opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    let result;
+    try {
+        result = collectMemoryExtractionResult(homeDir);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
+    }
+    if (!opts.dryRun) {
+        applyMemoryExtraction(result, homeDir);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
     }
     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}`);
-        }
+        printMemoryExtractionResult(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

@@ -5,7 +5,7 @@
  * plan-then-apply split every adapter already uses.
  */
 import type { AgentId, McpServerDef } from "../core/types.js";
-export type MigrateAction = "create" | "skip-symlink" | "skip-case-broken" | "skip-unsupported" | "already-migrated" | "conflict";
+export type MigrateAction = "create" | "skip-symlink" | "skip-case-broken" | "skip-unsupported" | "already-migrated" | "reclassify" | "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"`
@@ -28,6 +28,19 @@ export interface MigratePlan {
     present: boolean;
     items: MigratePlanItem[];
 }
+/**
+ * True when `existing` and `def` differ ONLY in which of `env`/
+ * `envAliases`/`staticEnv` an env value is filed under, while every
+ * other field and every value's resolved literal/reference text stays
+ * identical — the exact shape a migrate-read classification fix (like
+ * `trellis-migrate-env-var-alias`) leaves behind on already-migrated
+ * canonical data. Not a real conflict: the underlying value never
+ * changed, only Trellis's own bucketing of it got more precise
+ * (trellis-migrate-reclassify-repair). Anything this doesn't cover — a
+ * real value change, a different command, an added/removed field —
+ * still conflicts, unchanged.
+ */
+export declare function isSafeReclassification(existing: McpServerDef, def: McpServerDef): boolean;
 /**
  * `only` restricts which kind(s) are even considered — not a post-hoc
  * filter on a fully-computed plan (trellis-migrate-category-selection

package/dist/commands/migrate.js

@@ -14,7 +14,7 @@ import * as piProbe from "../probes/pi.js";
 import { AGENTS_MD_TEMPLATE } from "./init.js";
 import { decideDirImport } from "../lib/dirEquals.js";
 import { deepEqual } from "../lib/deepEqual.js";
-import { readClaudeCodeMcpDefs, readCodexMcpDefs, readKiroMcpDefs } from "../lib/mcpMigrateRead.js";
+import { readClaudeCodeMcpDefs, readCodexMcpDefs, readKiroMcpDefs, resolvedEnvTextMap } from "../lib/mcpMigrateRead.js";
 import { loadCanonicalSource, upsertServerYaml } from "../core/canonical.js";
 import { ALL_AGENTS } from "../core/types.js";
 const PROBES = {
@@ -72,6 +72,25 @@ function planInstructions(snapshot, canonicalAgentsMd) {
     }
     return { kind: "instructions", name: "agents.md", action: "conflict", detail: "canonical agents.md already has different real content — resolve by hand" };
 }
+/**
+ * True when `existing` and `def` differ ONLY in which of `env`/
+ * `envAliases`/`staticEnv` an env value is filed under, while every
+ * other field and every value's resolved literal/reference text stays
+ * identical — the exact shape a migrate-read classification fix (like
+ * `trellis-migrate-env-var-alias`) leaves behind on already-migrated
+ * canonical data. Not a real conflict: the underlying value never
+ * changed, only Trellis's own bucketing of it got more precise
+ * (trellis-migrate-reclassify-repair). Anything this doesn't cover — a
+ * real value change, a different command, an added/removed field —
+ * still conflicts, unchanged.
+ */
+export function isSafeReclassification(existing, def) {
+    const { env: _e1, envAliases: _ea1, staticEnv: _se1, ...restExisting } = existing;
+    const { env: _e2, envAliases: _ea2, staticEnv: _se2, ...restDef } = def;
+    if (!deepEqual(restExisting, restDef))
+        return false;
+    return deepEqual(resolvedEnvTextMap(existing), resolvedEnvTextMap(def));
+}
 function planMcpServer(name, def, existing) {
     if (existing === undefined) {
         return { kind: "mcp", name, action: "create", detail: "will add to servers.yaml", mcpDef: def };
@@ -79,6 +98,9 @@ function planMcpServer(name, def, existing) {
     if (deepEqual(existing, def)) {
         return { kind: "mcp", name, action: "already-migrated", detail: "canonical definition is already identical" };
     }
+    if (isSafeReclassification(existing, def)) {
+        return { kind: "mcp", name, action: "reclassify", detail: "same value, only its internal classification changed — safe to update", mcpDef: def };
+    }
     return { kind: "mcp", name, action: "conflict", detail: `canonical mcp/servers.yaml already has a different definition for "${name}" — resolve by hand` };
 }
 /**
@@ -127,7 +149,7 @@ export async function collectMigratePlan(agent, homeDir = homedir(), only) {
 export function applyMigratePlan(plan, homeDir = homedir()) {
     const canonicalRoot = join(homeDir, ".trellis");
     for (const item of plan.items) {
-        if (item.action !== "create")
+        if (item.action !== "create" && item.action !== "reclassify")
             continue;
         if (item.kind === "skill" && item.sourceDir) {
             const dest = join(canonicalRoot, "skills", item.name);

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/dist/core/canonical.d.ts

@@ -6,14 +6,16 @@
  */
 import type { CanonicalSource, McpServerDef } from "./types.js";
 /**
- * The on-disk shape for one server entry — `static_env` (snake_case, like
- * every other multi-word key across `.trellis/*.yaml`) is translated to
- * `McpServerDef.staticEnv` (camelCase) below; every other field happens
- * to already be a single word, so no server-def field needed this
- * treatment before (trellis-mcp-static-env-and-disabled-servers).
+ * The on-disk shape for one server entry — `static_env`/`env_aliases`
+ * (snake_case, like every other multi-word key across `.trellis/*.yaml`)
+ * are translated to `McpServerDef.staticEnv`/`envAliases` (camelCase)
+ * below; every other field happens to already be a single word, so no
+ * server-def field needed this treatment before
+ * (trellis-mcp-static-env-and-disabled-servers, trellis-migrate-env-var-alias).
  */
-type McpServerDefYaml = Omit<McpServerDef, "staticEnv"> & {
+type McpServerDefYaml = Omit<McpServerDef, "staticEnv" | "envAliases"> & {
     static_env?: Record<string, string>;
+    env_aliases?: Record<string, string>;
 };
 /** Inverse of `fromServerDefYaml` (trellis-canonical-cli-crud) — strips
  * `undefined` fields so the written YAML never gets a literal `null`