agent-trellis 0.3.0 → 0.5.2

package/dist/core/canonical.js

@@ -10,17 +10,24 @@ import { basename, join } from "node:path";
 import { isMap, parse as parseYaml, parseDocument } from "yaml";
 import { ALL_AGENTS } from "./types.js";
 function fromServerDefYaml(def) {
-    const { static_env, ...rest } = def;
-    return static_env ? { ...rest, staticEnv: static_env } : rest;
+    const { static_env, env_aliases, ...rest } = def;
+    const out = { ...rest };
+    if (static_env)
+        out.staticEnv = static_env;
+    if (env_aliases)
+        out.envAliases = env_aliases;
+    return out;
 }
 /** Inverse of `fromServerDefYaml` (trellis-canonical-cli-crud) — strips
  * `undefined` fields so the written YAML never gets a literal `null`
  * for an omitted optional. */
 export function toServerDefYaml(def) {
-    const { staticEnv, ...rest } = def;
+    const { staticEnv, envAliases, ...rest } = def;
     const out = { ...rest };
     if (staticEnv)
         out.static_env = staticEnv;
+    if (envAliases)
+        out.env_aliases = envAliases;
     for (const key of Object.keys(out)) {
         if (out[key] === undefined)
             delete out[key];

package/dist/core/types.d.ts

@@ -53,6 +53,18 @@ export interface McpServerDef {
      * environment tag), not an escape hatch for real credentials.
      */
     staticEnv?: Record<string, string>;
+    /**
+     * Target env var name -> source variable name, for a reference whose
+     * key differs from the name it resolves (`OPENAPI_MCP_HEADERS:
+     * "${NOTION_OPENAPI_MCP_HEADERS}"` becomes `{ OPENAPI_MCP_HEADERS:
+     * "NOTION_OPENAPI_MCP_HEADERS" }`) — `env`'s self-referencing shape
+     * can't express a differently-named source, and treating this case as
+     * `staticEnv` silently ships the literal, unexpanded placeholder text
+     * to any consumer with no native `${VAR}` runtime of its own
+     * (trellis-migrate-env-var-alias). Resolved through the exact same
+     * mechanism as `env`, never a raw literal.
+     */
+    envAliases?: Record<string, string>;
     /**
      * Defaults to `true`. `false` keeps the definition in canonical
      * without writing it to any agent — matches a real host config's own

package/dist/lib/mcpMigrateRead.d.ts

@@ -23,6 +23,18 @@ export interface McpMigrateReadResult {
     entries: McpMigrateEntry[];
     unsupported: McpMigrateUnsupported[];
 }
+/**
+ * Inverse of `splitJsonEnvMap`: the resolved literal/reference text every
+ * env-classification key would produce on disk, regardless of which of
+ * `env`/`envAliases`/`staticEnv` it's currently filed under — a self-
+ * referencing `env` name and a differently-named `envAliases` entry
+ * both resolve to a `${...}` placeholder, a `staticEnv` entry resolves
+ * to its own literal text as-is. Shared by `renderJsonServerEntry` (the
+ * JSON write path) and migrate's own safe-reclassification check
+ * (`trellis-migrate-reclassify-repair`) — the same mechanism, not two
+ * independent derivations of it.
+ */
+export declare function resolvedEnvTextMap(def: Pick<McpServerDef, "env" | "envAliases" | "staticEnv">): Record<string, string>;
 export declare function readClaudeCodeMcpDefs(homeDir: string): McpMigrateReadResult;
 export declare function readKiroMcpDefs(homeDir: string): McpMigrateReadResult;
 export interface CodexMcpEntryRich {

package/dist/lib/mcpMigrateRead.js

@@ -17,25 +17,47 @@ import { readJsonFile } from "./probeCommon.js";
 import { readServerEnvTable } from "./tomlSection.js";
 const EMPTY_RESULT = { entries: [], unsupported: [] };
 /**
- * Trellis's own `env` (name-only reference) vs. `staticEnv` (literal
- * value) split lives in one JSON object on disk (`jsonMcp.ts`'s
- * `renderJsonServerEntry`) — a value is a "name" entry only when it's
- * exactly `${KEY}` referencing its OWN key, matching exactly what that
- * renderer ever produces; anything else (a literal value, or a `${...}`
- * referencing a *different* name) is treated as a literal `staticEnv`
- * value instead of guessed at.
+ * Trellis's own `env` (self-referencing name) vs. `envAliases`
+ * (differently-named reference) vs. `staticEnv` (literal value) split
+ * lives in one JSON object on disk (`jsonMcp.ts`'s
+ * `renderJsonServerEntry`) — any value matching exactly `${NAME}` is a
+ * reference needing resolution, regardless of whether `NAME` equals its
+ * own key (trellis-migrate-env-var-alias; previously only the
+ * same-name case was recognized, silently shipping a differently-named
+ * reference as an unresolved literal). Anything not shaped like
+ * `${NAME}` at all remains a literal `staticEnv` value.
  */
-const SELF_VAR_REF_RE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
+const VAR_REF_RE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
+/**
+ * Inverse of `splitJsonEnvMap`: the resolved literal/reference text every
+ * env-classification key would produce on disk, regardless of which of
+ * `env`/`envAliases`/`staticEnv` it's currently filed under — a self-
+ * referencing `env` name and a differently-named `envAliases` entry
+ * both resolve to a `${...}` placeholder, a `staticEnv` entry resolves
+ * to its own literal text as-is. Shared by `renderJsonServerEntry` (the
+ * JSON write path) and migrate's own safe-reclassification check
+ * (`trellis-migrate-reclassify-repair`) — the same mechanism, not two
+ * independent derivations of it.
+ */
+export function resolvedEnvTextMap(def) {
+    const nameRefs = Object.fromEntries((def.env ?? []).map((name) => [name, `\${${name}}`]));
+    const aliasRefs = Object.fromEntries(Object.entries(def.envAliases ?? {}).map(([targetKey, sourceName]) => [targetKey, `\${${sourceName}}`]));
+    return { ...nameRefs, ...aliasRefs, ...(def.staticEnv ?? {}) };
+}
 function splitJsonEnvMap(env) {
     if (!env)
         return {};
     const names = [];
+    const aliases = {};
     const literal = {};
     for (const [key, value] of Object.entries(env)) {
-        const match = SELF_VAR_REF_RE.exec(value);
+        const match = VAR_REF_RE.exec(value);
         if (match && match[1] === key) {
             names.push(key);
         }
+        else if (match) {
+            aliases[key] = match[1];
+        }
         else {
             literal[key] = value;
         }
@@ -43,6 +65,8 @@ function splitJsonEnvMap(env) {
     const result = {};
     if (names.length > 0)
         result.env = names;
+    if (Object.keys(aliases).length > 0)
+        result.envAliases = aliases;
     if (Object.keys(literal).length > 0)
         result.staticEnv = literal;
     return result;
@@ -115,9 +139,20 @@ export function buildCodexMcpReadResult(mcpEntries, tomlContent) {
         if (entry.transport.env_vars && entry.transport.env_vars.length > 0)
             def.env = entry.transport.env_vars;
         if (tomlContent) {
-            const staticEnv = readServerEnvTable(tomlContent, entry.name);
-            if (staticEnv && Object.keys(staticEnv).length > 0)
-                def.staticEnv = staticEnv;
+            const envTable = readServerEnvTable(tomlContent, entry.name);
+            if (envTable && Object.keys(envTable).length > 0) {
+                // Same `${NAME}`-reference-vs-literal classification as the
+                // JSON-source path (trellis-migrate-env-var-alias D2) — Codex's
+                // `[mcp_servers.<name>.env]` table can hold either, same as
+                // Claude Code/Kiro's `env` object can.
+                const classified = splitJsonEnvMap(envTable);
+                if (classified.env)
+                    def.env = [...(def.env ?? []), ...classified.env];
+                if (classified.envAliases)
+                    def.envAliases = classified.envAliases;
+                if (classified.staticEnv)
+                    def.staticEnv = classified.staticEnv;
+            }
         }
         entries.push({ name: entry.name, def });
     }

package/dist/lib/memoryGraph.d.ts

@@ -58,3 +58,38 @@ export interface MemorySyncPlan {
  * regardless of what canonical wants.
  */
 export declare function planMemorySync(canonical: Pick<CanonicalSource, "memories">, currentGraphContent: string | undefined): MemorySyncPlan;
+/**
+ * Renders one extraction candidate as readable markdown — the entity's
+ * real (unslugged) name as a heading, its type, its observations as a
+ * list, and (only when it participates in any) its relations as a short
+ * list. Not a serialization format meant to round-trip byte-for-byte
+ * back through `planMemorySync` (trellis-memory-extraction design.md
+ * D2/Non-Goals) — canonical's own memory model is a single flat blob per
+ * file, strictly less expressive than the graph's typed-entity-plus-
+ * relations shape.
+ */
+export declare function renderExtractedMemoryFile(entity: MemoryEntity, relations: readonly MemoryRelation[]): string;
+export type MemoryExtractionAction = "create" | "already-extracted" | "conflict";
+export interface MemoryExtractionItem {
+    /** The entity's real, unslugged name. */
+    name: string;
+    /** The derived target filename, without the `.md` extension. */
+    slug: string;
+    action: MemoryExtractionAction;
+    detail: string;
+    /** Only set when `action === "create"` — the file content to write. */
+    content?: string;
+}
+export interface MemoryExtractionPlan {
+    items: MemoryExtractionItem[];
+}
+/**
+ * Pure: given the graph's parsed lines and a way to read an existing
+ * canonical memory file by its (already-slugged) name, computes which
+ * non-`trellis-memory` entities (D1) should become new canonical files.
+ * `readCanonicalFile` returning `undefined` means "no such file yet" —
+ * the same "create vs. already-there vs. differs" three-way split
+ * `planMcpServer`/skill-migrate already use elsewhere in this codebase,
+ * applied to a new content type (trellis-memory-extraction design.md D4).
+ */
+export declare function planMemoryExtraction(graphLines: readonly MemoryGraphLine[], readCanonicalFile: (slug: string) => string | undefined): MemoryExtractionPlan;

package/dist/lib/memoryGraph.js

@@ -22,6 +22,7 @@
  * completely untouched — reported as a conflict, never overwritten.
  */
 import { readFileSync } from "node:fs";
+import { slugify } from "./slug.js";
 export const TRELLIS_MEMORY_ENTITY_TYPE = "trellis-memory";
 export function parseMemoryGraph(content) {
     const lines = [];
@@ -99,3 +100,64 @@ export function planMemorySync(canonical, currentGraphContent) {
     }
     return { items, nextGraph: [...untouchedLines, ...nextTrellisEntities] };
 }
+/**
+ * Renders one extraction candidate as readable markdown — the entity's
+ * real (unslugged) name as a heading, its type, its observations as a
+ * list, and (only when it participates in any) its relations as a short
+ * list. Not a serialization format meant to round-trip byte-for-byte
+ * back through `planMemorySync` (trellis-memory-extraction design.md
+ * D2/Non-Goals) — canonical's own memory model is a single flat blob per
+ * file, strictly less expressive than the graph's typed-entity-plus-
+ * relations shape.
+ */
+export function renderExtractedMemoryFile(entity, relations) {
+    const lines = [`# ${entity.name}`, "", `**Type:** ${entity.entityType}`, "", "## Observations"];
+    for (const observation of entity.observations) {
+        lines.push(`- ${observation}`);
+    }
+    const related = relations.filter((r) => r.from === entity.name || r.to === entity.name);
+    if (related.length > 0) {
+        lines.push("", "## Relations");
+        for (const r of related) {
+            lines.push(r.from === entity.name ? `- ${r.relationType} -> ${r.to}` : `- ${r.from} -> ${r.relationType} -> this entity`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * Pure: given the graph's parsed lines and a way to read an existing
+ * canonical memory file by its (already-slugged) name, computes which
+ * non-`trellis-memory` entities (D1) should become new canonical files.
+ * `readCanonicalFile` returning `undefined` means "no such file yet" —
+ * the same "create vs. already-there vs. differs" three-way split
+ * `planMcpServer`/skill-migrate already use elsewhere in this codebase,
+ * applied to a new content type (trellis-memory-extraction design.md D4).
+ */
+export function planMemoryExtraction(graphLines, readCanonicalFile) {
+    const entities = graphLines.filter((line) => line.type === "entity");
+    const relations = graphLines.filter((line) => line.type === "relation");
+    const candidates = entities.filter((e) => e.entityType !== TRELLIS_MEMORY_ENTITY_TYPE && e.observations.length > 0);
+    const items = [];
+    const claimedSlugs = new Map();
+    for (const entity of candidates) {
+        const slug = slugify(entity.name);
+        const claimedBy = claimedSlugs.get(slug);
+        if (claimedBy !== undefined) {
+            items.push({ name: entity.name, slug, action: "conflict", detail: `slug "${slug}" collides with entity "${claimedBy}" — resolve by hand` });
+            continue;
+        }
+        claimedSlugs.set(slug, entity.name);
+        const content = renderExtractedMemoryFile(entity, relations);
+        const existing = readCanonicalFile(slug);
+        if (existing === undefined) {
+            items.push({ name: entity.name, slug, action: "create", detail: "will create a new canonical memory file", content });
+        }
+        else if (existing === content) {
+            items.push({ name: entity.name, slug, action: "already-extracted", detail: "canonical file content is already identical" });
+        }
+        else {
+            items.push({ name: entity.name, slug, action: "conflict", detail: `~/.trellis/memories/${slug}.md already exists with different content — resolve by hand` });
+        }
+    }
+    return { items };
+}

package/dist/lib/slug.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Kebab-case, filesystem-safe slug for deriving a file/dir name from an
+ * arbitrary display name (e.g. a memory graph entity's own name, which
+ * can contain spaces, mixed case, or punctuation). Collision handling
+ * (two different inputs producing the same slug) is the caller's
+ * concern (trellis-memory-extraction design.md D3) — this function only
+ * ever normalizes one input at a time.
+ */
+export declare function slugify(name: string): string;

package/dist/lib/slug.js

@@ -0,0 +1,15 @@
+/**
+ * Kebab-case, filesystem-safe slug for deriving a file/dir name from an
+ * arbitrary display name (e.g. a memory graph entity's own name, which
+ * can contain spaces, mixed case, or punctuation). Collision handling
+ * (two different inputs producing the same slug) is the caller's
+ * concern (trellis-memory-extraction design.md D3) — this function only
+ * ever normalizes one input at a time.
+ */
+export function slugify(name) {
+    return name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}

package/dist/lib/tomlSection.js

@@ -155,7 +155,13 @@ export function renderServerSection(name, def) {
         if (bearerEnvVar)
             lines.push(`bearer_token_env_var = ${tomlString(bearerEnvVar)}`);
     }
-    const staticEnvEntries = Object.entries(def.staticEnv ?? {});
+    // `envAliases`' target key gets a literal `${sourceName}` placeholder
+    // in the same env table `staticEnv` writes to — Codex's own runtime
+    // expands it from its own ambient environment, the same mechanism
+    // `env_vars` already relies on for a same-named reference
+    // (trellis-migrate-env-var-alias D3).
+    const aliasEntries = Object.entries(def.envAliases ?? {}).map(([targetKey, sourceName]) => [targetKey, `\${${sourceName}}`]);
+    const staticEnvEntries = [...aliasEntries, ...Object.entries(def.staticEnv ?? {})];
     if (staticEnvEntries.length > 0) {
         lines.push(`[${envHeader(name)}]`);
         for (const [key, value] of staticEnvEntries) {

package/dist/pi-bridge/bundle.js

@@ -27261,8 +27261,11 @@ function resolveScope(scope, managedAgents) {
 
 // src/core/canonical.ts
 function fromServerDefYaml(def) {
-  const { static_env, ...rest } = def;
-  return static_env ? { ...rest, staticEnv: static_env } : rest;
+  const { static_env, env_aliases, ...rest } = def;
+  const out = { ...rest };
+  if (static_env) out.staticEnv = static_env;
+  if (env_aliases) out.envAliases = env_aliases;
+  return out;
 }
 function trellisRoot(homeDir) {
   return join(homeDir, ".trellis");
@@ -27474,7 +27477,7 @@ function findLiteralSecret(def) {
   return void 0;
 }
 function findUnresolvedEnvName(def, policy) {
-  const names = def.env ?? [];
+  const names = [...def.env ?? [], ...Object.values(def.envAliases ?? {})];
   if (names.length === 0) return void 0;
   const resolved = resolveSecretEnv(names, policy);
   return names.find((name) => !resolved[name]);
@@ -31994,8 +31997,10 @@ async function connectWithCleanup(client, transport, timeoutMs, message) {
 }
 async function connectStdio(def, secretsPolicy, timeoutMs) {
   const client = new Client(CLIENT_INFO, { capabilities: {} });
-  const resolved = resolveSecretEnv(def.env ?? [], secretsPolicy);
+  const envAliases = def.envAliases ?? {};
+  const resolved = resolveSecretEnv([...def.env ?? [], ...Object.values(envAliases)], secretsPolicy);
   const namedEnv = Object.fromEntries((def.env ?? []).map((name) => [name, resolved[name] ?? ""]));
+  const aliasEnv = Object.fromEntries(Object.entries(envAliases).map(([targetKey, sourceName]) => [targetKey, resolved[sourceName] ?? ""]));
   const transport = new StdioClientTransport({
     command: def.command,
     args: def.args,
@@ -32004,7 +32009,7 @@ async function connectStdio(def, secretsPolicy, timeoutMs) {
     // entry's empty-string fallback for the same key — though in practice
     // resolveMcpPlan's D6 refusal never lets an unresolved name reach
     // this point at all (trellis-mcp-static-env-and-disabled-servers).
-    env: { ...getDefaultEnvironment(), ...namedEnv, ...def.staticEnv ?? {} }
+    env: { ...getDefaultEnvironment(), ...namedEnv, ...aliasEnv, ...def.staticEnv ?? {} }
   });
   return connectWithCleanup(client, transport, timeoutMs, `connect timed out after ${timeoutMs}ms`);
 }

package/dist/pi-bridge/index.js

@@ -70,8 +70,15 @@ async function connectWithCleanup(client, transport, timeoutMs, message) {
 }
 async function connectStdio(def, secretsPolicy, timeoutMs) {
     const client = new Client(CLIENT_INFO, { capabilities: {} });
-    const resolved = resolveSecretEnv(def.env ?? [], secretsPolicy);
+    const envAliases = def.envAliases ?? {};
+    // `envAliases`' values are source variable names — resolved through the
+    // exact same call as `env`'s own names, never delivered as the raw
+    // `${sourceName}` placeholder text a consumer with no `${VAR}` runtime
+    // of its own (like this bridge) would otherwise crash on parsing
+    // (trellis-migrate-env-var-alias, the real notion-on-pi bug).
+    const resolved = resolveSecretEnv([...(def.env ?? []), ...Object.values(envAliases)], secretsPolicy);
     const namedEnv = Object.fromEntries((def.env ?? []).map((name) => [name, resolved[name] ?? ""]));
+    const aliasEnv = Object.fromEntries(Object.entries(envAliases).map(([targetKey, sourceName]) => [targetKey, resolved[sourceName] ?? ""]));
     const transport = new StdioClientTransport({
         command: def.command,
         args: def.args,
@@ -80,7 +87,7 @@ async function connectStdio(def, secretsPolicy, timeoutMs) {
         // entry's empty-string fallback for the same key — though in practice
         // resolveMcpPlan's D6 refusal never lets an unresolved name reach
         // this point at all (trellis-mcp-static-env-and-disabled-servers).
-        env: { ...getDefaultEnvironment(), ...namedEnv, ...(def.staticEnv ?? {}) },
+        env: { ...getDefaultEnvironment(), ...namedEnv, ...aliasEnv, ...(def.staticEnv ?? {}) },
     });
     return connectWithCleanup(client, transport, timeoutMs, `connect timed out after ${timeoutMs}ms`);
 }

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
@@ -345,6 +354,19 @@ not currently active anywhere; remove the line (or set it `true`) to
 turn it back on everywhere at once. See
 [`schema/servers.example.yaml`](../schema/servers.example.yaml) for both.
 
+If a server's own env var name differs from the one it should resolve
+(a real example: Notion's MCP server wants `OPENAPI_MCP_HEADERS`, but
+your shell/secret manager holds it under `NOTION_OPENAPI_MCP_HEADERS`),
+use `env_aliases` instead of either `env` or `static_env` —
+`target_key: source_variable_name`. It resolves through the exact same
+mechanism as `env` (the same pre-write refusal check, the same agent
+`${VAR}` reference on every target), just delivered under a different
+key. Writing that kind of reference as `static_env` looks like it works
+(the placeholder text is still just a string) but ships the literal,
+unexpanded `${SOURCE_NAME}` text to any agent with no `${VAR}` runtime
+of its own — which is exactly what broke pi's Notion connection before
+this field existed.
+
 ## `trellis memory sync`
 
 Ingests `~/.trellis/memories/*.md` into the actual on-disk file
@@ -369,12 +391,47 @@ the graph that Trellis didn't create, the command refuses that one entry
 (reported as a conflict) rather than overwriting it, same posture as
 every other conflict in this project.
 
-**Known limitation, named rather than silently worked around:** this only
-ingests canonical's *own* `memories/*.md` files into the shared store —
-it does not (yet) extract an agent's own already-accumulated memory
-content (e.g. Claude Code's own per-project memory feature) back into
-canonical. That extraction is a real, separate, still-open gap — see
-`docs/roadmap.md`'s P15 entry.
+This only ingests canonical's *own* `memories/*.md` files into the shared
+store — the reverse direction (an agent's own already-accumulated content
+in that same shared graph, not yet represented in canonical) is
+`trellis memory extract`, below.
+
+## `trellis memory extract`
+
+The other direction: reads the same graph file's real entities — not
+Trellis's own (anything an agent created directly, via its own MCP tool
+calls against the shared memory server, before or outside of canonical) —
+and writes each as a new canonical `memories/*.md` file. Requires the
+same `memory` server configuration `memory sync` does; refuses with the
+identical message when it's missing.
+
+```
+$ trellis memory extract
+memory extract — /Users/you/.trellis/memories/graph.jsonl
+  [create] "Sprint Tasks Q2" (sprint-tasks-q2.md) — will create a new canonical memory file
+```
+
+A rendered file is a readable markdown transcription — heading,
+observations as a list, relations as a short list when the entity has
+any — not a format meant to round-trip byte-for-byte back through
+`memory sync`: re-syncing an extracted file later turns it into a single,
+flat observation, the same as any other canonical memory file. This is a
+one-way trip from "richer, live graph" to "durable, reviewable,
+version-controllable prose," not a lossless mirror.
+
+Same conflict discipline as everywhere else: a target file that already
+exists with different content is reported as a conflict and left
+untouched, never silently overwritten — including when two different
+entities' names would slug to the same filename. Not wired into
+`trellis onboard`'s automatic chain (unlike `memory sync`) — this is a
+deliberate, occasional action you run, the same posture `migrate` already
+has.
+
+**Note:** this is unrelated to any project-level "auto memory" feature an
+agent may have of its own (e.g. Claude Code's own per-project memory
+files) — those are a different, agent-specific mechanism entirely, not
+the shared `@modelcontextprotocol/server-memory` server Trellis manages
+here.
 
 ## `trellis secrets audit`
 

package/docs/research.md

@@ -120,6 +120,17 @@ clients." Mature, but needs Docker + an LLM key. Documented as the
 upgrade path for cross-machine or richer semantic memory, alongside
 `totalrecallai` as a second real option in that same category.
 
+Two commands, one direction each: `trellis memory sync` (canonical
+`memories/*.md` → the shared graph file) and `trellis memory extract`
+(the graph's own real, non-Trellis entities → new canonical files) —
+closing P15's own explicitly-named "per-agent extraction into canonical
+remains a separate, open gap." The two are not symmetric round-trips:
+canonical's memory model is one flat blob per file, the graph's native
+model is typed entities plus a relation graph, so extraction is a
+one-way, lossy-in-structure (not in substance) transcription, not a
+serialization format — see `docs/getting-started.md`'s `memory extract`
+section for the exact trade-off.
+
 ## Secrets (formalize existing practice, don't build new infra)
 
 The 2026 consensus across 1Password, Vault, Infisical writeups is uniform:
@@ -133,6 +144,19 @@ which was silently invalid). Trellis's contribution here is `trellis secrets
 audit` — a linter that fails a build if any adapter output contains a raw
 credential — not a new secret store.
 
+A third real incident during migrate-in: a source config's `${VAR}`
+reference doesn't always name itself (`OPENAPI_MCP_HEADERS:
+"${NOTION_OPENAPI_MCP_HEADERS}"`, a real Notion MCP server entry). Migrate's
+read path originally only recognized a same-named reference as one; a
+differently-named reference silently fell through as a literal, unexpanded
+value — harmless on Claude Code/Codex (both expand `${VAR}` themselves from
+their own native config format), but a hard crash on pi, whose bridge has no
+`${VAR}` runtime of its own and merges an unrecognized value verbatim.
+`McpServerDef.envAliases` (target key → source variable name) closes this:
+every agent's adapter renders it through the exact same reference mechanism
+`env` already uses, and the pi bridge resolves it through the exact same
+`resolveSecretEnv` call.
+
 ## pi coding agent — the one place we write real code, not config generation
 
 Reverse-engineered directly from the installed binary

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,10 @@ 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 |
+| P18 | ✅ `envAliases`: a migrated `${NAME}` env reference whose name differs from its own key (found via live dogfooding — a real Notion MCP server crashing pi after migrate, not a hypothetical) is now recognized as a reference, not silently shipped as literal unexpanded placeholder text. New `McpServerDef.envAliases` field, threaded through migrate-read (both JSON and Codex TOML sources), every adapter's write path, the pre-write unresolvable-env refusal guard, the pi bridge's runtime resolution, and canonical's own `env_aliases`/`envAliases` on-disk round-trip | P16 |
+| P19 | ✅ Migrate reclassify-repair: found immediately after P18 shipped — re-running migrate on data migrated *before* a classification fix didn't pick the fix up at all, since `planMcpServer`'s conflict check was plain `deepEqual` (any structural difference, real customization or not, was refused as "resolve by hand"). New narrow `isSafeReclassification` check + `"reclassify"` migrate action: applied automatically when a value only moved between `staticEnv`/`env`/`envAliases` while resolving to the exact same literal/reference text, everything else identical; any real difference still conflicts, unchanged. Verified for real on this machine: `migrate --from claude-code --only mcp` correctly reclassified notion's stale entry and left all 8 other already-migrated servers untouched | P18 |
+| P20 | ✅ Memory extraction: closes P15's own explicitly-named "per-agent extraction into canonical remains a separate, open gap." New `trellis memory extract` — the reverse of `memory sync` — reads the shared graph's real, non-`trellis-memory` entities (the same ownership marker `memory sync` already uses to leave agent-created content untouched, read the other direction) and writes each as a new canonical `memories/*.md` file: readable markdown, not a serialization format, not meant to round-trip byte-for-byte back through `memory sync`. Same create/no-op/conflict discipline as every other Trellis write; not wired into `onboard`'s automatic chain (a deliberate, occasional action, like `migrate`) | P15 |
 
 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.5.2",
   "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",

package/schema/servers.example.yaml

@@ -11,6 +11,12 @@
 #     scanned against `reject_patterns` like everything else, so a real
 #     credential accidentally placed there is still refused, not silently
 #     written (trellis-mcp-static-env-and-disabled-servers).
+#   - `env_aliases` is for a var whose own name differs from the name it
+#     should resolve (`target_key: source_variable_name`) — resolved
+#     through the exact same mechanism as `env`, just delivered under a
+#     different key. Do NOT reach for `static_env` here: a "${SOURCE_NAME}"
+#     string looks like it works but ships unexpanded to any agent with no
+#     `${VAR}` runtime of its own (trellis-migrate-env-var-alias).
 #   - `enabled: false` keeps a server's definition in canonical without
 #     writing it to any agent — for a server you want to keep configured
 #     but not currently active everywhere, matching how a real agent's
@@ -78,6 +84,18 @@ servers:
     args: ["-y", "@zereight/mcp-gitlab"]
     env: [GITLAB_PERSONAL_ACCESS_TOKEN, GITLAB_API_URL]
 
+  # `env_aliases`: the server wants `OPENAPI_MCP_HEADERS`, but your secret
+  # manager holds it under a differently-named variable — a real example
+  # found via migrating an actual Notion MCP server entry. Same resolution
+  # discipline as `env`, just target-key -> source-name instead of
+  # self-named.
+  notion:
+    transport: stdio
+    command: npx
+    args: ["-y", "@notionhq/notion-mcp-server"]
+    env_aliases:
+      OPENAPI_MCP_HEADERS: NOTION_OPENAPI_MCP_HEADERS
+
   # `enabled: false` keeps this definition in canonical without writing it
   # to any agent — for something you want configured but not currently
   # active anywhere. Remove the line (or set it to `true`) to turn it back