agent-trellis 0.4.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,17 +26,6 @@ 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;
 /**
@@ -45,3 +39,32 @@ export declare function printMemorySyncResult(result: MemorySyncResult, dryRun:
 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)
@@ -87,3 +101,74 @@ export function runMemorySync(opts = {}) {
     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 {
+        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/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`

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

@@ -354,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
@@ -378,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

@@ -948,6 +948,9 @@ tests passing.
 | 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.4.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