agent-trellis 0.2.0 → 0.3.0

package/dist/pi-bridge/bundle.js

@@ -7818,7 +7818,7 @@ var require_identity = __commonJS({
     var NODE_TYPE = /* @__PURE__ */ Symbol.for("yaml.node.type");
     var isAlias = (node2) => !!node2 && typeof node2 === "object" && node2[NODE_TYPE] === ALIAS;
     var isDocument = (node2) => !!node2 && typeof node2 === "object" && node2[NODE_TYPE] === DOC;
-    var isMap = (node2) => !!node2 && typeof node2 === "object" && node2[NODE_TYPE] === MAP;
+    var isMap2 = (node2) => !!node2 && typeof node2 === "object" && node2[NODE_TYPE] === MAP;
     var isPair = (node2) => !!node2 && typeof node2 === "object" && node2[NODE_TYPE] === PAIR;
     var isScalar = (node2) => !!node2 && typeof node2 === "object" && node2[NODE_TYPE] === SCALAR;
     var isSeq = (node2) => !!node2 && typeof node2 === "object" && node2[NODE_TYPE] === SEQ;
@@ -7854,7 +7854,7 @@ var require_identity = __commonJS({
     exports.isAlias = isAlias;
     exports.isCollection = isCollection;
     exports.isDocument = isDocument;
-    exports.isMap = isMap;
+    exports.isMap = isMap2;
     exports.isNode = isNode;
     exports.isPair = isPair;
     exports.isScalar = isScalar;
@@ -11966,9 +11966,9 @@ var require_resolve_flow_collection = __commonJS({
     var blockMsg = "Block collections are not allowed within flow collections";
     var isBlock = (token) => token && (token.type === "block-map" || token.type === "block-seq");
     function resolveFlowCollection({ composeNode, composeEmptyNode }, ctx, fc, onError, tag) {
-      const isMap = fc.start.source === "{";
-      const fcName = isMap ? "flow map" : "flow sequence";
-      const NodeClass = tag?.nodeClass ?? (isMap ? YAMLMap.YAMLMap : YAMLSeq.YAMLSeq);
+      const isMap2 = fc.start.source === "{";
+      const fcName = isMap2 ? "flow map" : "flow sequence";
+      const NodeClass = tag?.nodeClass ?? (isMap2 ? YAMLMap.YAMLMap : YAMLSeq.YAMLSeq);
       const coll = new NodeClass(ctx.schema);
       coll.flow = true;
       const atRoot = ctx.atRoot;
@@ -12004,7 +12004,7 @@ var require_resolve_flow_collection = __commonJS({
             offset = props.end;
             continue;
           }
-          if (!isMap && ctx.options.strict && utilContainsNewline.containsNewline(key))
+          if (!isMap2 && ctx.options.strict && utilContainsNewline.containsNewline(key))
             onError(
               key,
               // checked by containsNewline()
@@ -12044,7 +12044,7 @@ var require_resolve_flow_collection = __commonJS({
             }
           }
         }
-        if (!isMap && !sep && !props.found) {
+        if (!isMap2 && !sep && !props.found) {
           const valueNode = value ? composeNode(ctx, value, props, onError) : composeEmptyNode(ctx, props.end, sep, null, props, onError);
           coll.items.push(valueNode);
           offset = valueNode.range[2];
@@ -12067,7 +12067,7 @@ var require_resolve_flow_collection = __commonJS({
             startOnNewline: false
           });
           if (valueProps.found) {
-            if (!isMap && !props.found && ctx.options.strict) {
+            if (!isMap2 && !props.found && ctx.options.strict) {
               if (sep)
                 for (const st of sep) {
                   if (st === valueProps.found)
@@ -12099,7 +12099,7 @@ var require_resolve_flow_collection = __commonJS({
           const pair = new Pair.Pair(keyNode, valueNode);
           if (ctx.options.keepSourceTokens)
             pair.srcToken = collItem;
-          if (isMap) {
+          if (isMap2) {
             const map = coll;
             if (utilMapIncludes.mapIncludes(ctx, map.items, keyNode))
               onError(keyStart, "DUPLICATE_KEY", "Map keys must be unique");
@@ -12115,7 +12115,7 @@ var require_resolve_flow_collection = __commonJS({
           offset = valueNode ? valueNode.range[2] : valueProps.end;
         }
       }
-      const expectedEnd = isMap ? "}" : "]";
+      const expectedEnd = isMap2 ? "}" : "]";
       const [ce, ...ee] = fc.end;
       let cePos = offset;
       if (ce?.source === expectedEnd)
@@ -15016,7 +15016,7 @@ var require_public_api = __commonJS({
         return docs;
       return Object.assign([], { empty: true }, composer$1.streamInfo());
     }
-    function parseDocument(source, options = {}) {
+    function parseDocument2(source, options = {}) {
       const { lineCounter: lineCounter2, prettyErrors } = parseOptions(options);
       const parser$1 = new parser.Parser(lineCounter2?.addNewLine);
       const composer$1 = new composer.Composer(options);
@@ -15042,7 +15042,7 @@ var require_public_api = __commonJS({
       } else if (options === void 0 && reviver && typeof reviver === "object") {
         options = reviver;
       }
-      const doc = parseDocument(src, options);
+      const doc = parseDocument2(src, options);
       if (!doc)
         return null;
       doc.warnings.forEach((warning) => log.warn(doc.options.logLevel, warning));
@@ -15078,7 +15078,7 @@ var require_public_api = __commonJS({
     }
     exports.parse = parse3;
     exports.parseAllDocuments = parseAllDocuments;
-    exports.parseDocument = parseDocument;
+    exports.parseDocument = parseDocument2;
     exports.stringify = stringify;
   }
 });
@@ -27243,7 +27243,7 @@ import { homedir as homedir2 } from "node:os";
 
 // src/core/canonical.ts
 var import_yaml = __toESM(require_dist2(), 1);
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join } from "node:path";
 
@@ -27260,6 +27260,10 @@ function resolveScope(scope, managedAgents) {
 }
 
 // src/core/canonical.ts
+function fromServerDefYaml(def) {
+  const { static_env, ...rest } = def;
+  return static_env ? { ...rest, staticEnv: static_env } : rest;
+}
 function trellisRoot(homeDir) {
   return join(homeDir, ".trellis");
 }
@@ -27303,8 +27307,9 @@ function loadServersYaml(path) {
     return { servers: {}, knownHostInjected: [] };
   }
   const parsed = (0, import_yaml.parse)(readFileSync(path, "utf-8")) ?? {};
+  const servers = Object.fromEntries(Object.entries(parsed.servers ?? {}).map(([name, def]) => [name, fromServerDefYaml(def)]));
   return {
-    servers: parsed.servers ?? {},
+    servers,
     knownHostInjected: parsed.known_host_injected ?? [],
     hub: parsed.hub
   };
@@ -27416,6 +27421,33 @@ function codexBearerTokenEnvVar(def) {
   return BEARER_TOKEN_VALUE_RE.exec(value)?.[1];
 }
 
+// src/lib/secretEnv.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
+var LINE_RE = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/;
+function parseDotenv(content) {
+  const result = {};
+  for (const rawLine of content.split("\n")) {
+    const line = rawLine.trim();
+    if (line === "" || line.startsWith("#")) continue;
+    const match = LINE_RE.exec(line);
+    if (match) result[match[1]] = match[2];
+  }
+  return result;
+}
+function loadEnvFile(path) {
+  return existsSync2(path) ? parseDotenv(readFileSync2(path, "utf-8")) : {};
+}
+function resolveSecretEnv(names, policy) {
+  const result = {};
+  if (policy.envFile) {
+    const map = loadEnvFile(policy.envFile);
+    for (const name of names) result[name] = map[name];
+  } else {
+    for (const name of names) result[name] = process.env[name];
+  }
+  return result;
+}
+
 // src/adapters/mcpPlan.ts
 var HUB_ENTRY_NAME = "trellis-hub";
 var CODEX_STDIO_URL_CRASH_NOTE = ' On Codex specifically, this crashes the entire process at startup ("url is not supported for stdio"), not just this one server \u2014 see docs/research.md.';
@@ -27429,7 +27461,9 @@ var DANGEROUS_LITERAL_PATTERNS = [
   { label: "mcp-router token (mcpr_)", pattern: /mcpr_/ }
 ];
 function findLiteralSecret(def) {
-  const candidates = [def.command, def.url, ...def.args ?? [], ...Object.values(def.headers ?? {})].filter((v) => typeof v === "string");
+  const candidates = [def.command, def.url, ...def.args ?? [], ...Object.values(def.headers ?? {}), ...Object.values(def.staticEnv ?? {})].filter(
+    (v) => typeof v === "string"
+  );
   for (const candidate of candidates) {
     for (const { label, pattern } of DANGEROUS_LITERAL_PATTERNS) {
       if (pattern.test(candidate)) {
@@ -27439,7 +27473,13 @@ function findLiteralSecret(def) {
   }
   return void 0;
 }
-function resolveMcpPlan(agentId, mcp, managedAgents) {
+function findUnresolvedEnvName(def, policy) {
+  const names = def.env ?? [];
+  if (names.length === 0) return void 0;
+  const resolved = resolveSecretEnv(names, policy);
+  return names.find((name) => !resolved[name]);
+}
+function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
   if (mcp.hub) {
     if (mcp.knownHostInjected.includes(HUB_ENTRY_NAME)) {
       return { desired: [], conflicts: [{ name: HUB_ENTRY_NAME, message: collisionMessage(HUB_ENTRY_NAME, agentId) }] };
@@ -27449,6 +27489,9 @@ function resolveMcpPlan(agentId, mcp, managedAgents) {
   const desired = [];
   const conflicts = [];
   for (const [name, def] of Object.entries(mcp.servers)) {
+    if (def.enabled === false) {
+      continue;
+    }
     if (!isInScope(agentId, def.agents, managedAgents)) {
       continue;
     }
@@ -27471,38 +27514,20 @@ function resolveMcpPlan(agentId, mcp, managedAgents) {
       });
       continue;
     }
+    const unresolvedName = findUnresolvedEnvName(def, policy);
+    if (unresolvedName) {
+      const source = policy.envFile ?? "process environment";
+      conflicts.push({
+        name,
+        message: `refusing to write MCP server "${name}": its declared env var "${unresolvedName}" has no resolvable value in ${source} \u2014 writing it now would silently break this server's connection once the agent starts it (trellis-mcp-static-env-and-disabled-servers)`
+      });
+      continue;
+    }
     desired.push({ name, def });
   }
   return { desired, conflicts };
 }
 
-// src/lib/secretEnv.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
-var LINE_RE = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/;
-function parseDotenv(content) {
-  const result = {};
-  for (const rawLine of content.split("\n")) {
-    const line = rawLine.trim();
-    if (line === "" || line.startsWith("#")) continue;
-    const match = LINE_RE.exec(line);
-    if (match) result[match[1]] = match[2];
-  }
-  return result;
-}
-function loadEnvFile(path) {
-  return existsSync2(path) ? parseDotenv(readFileSync2(path, "utf-8")) : {};
-}
-function resolveSecretEnv(names, policy) {
-  const result = {};
-  if (policy.envFile) {
-    const map = loadEnvFile(policy.envFile);
-    for (const name of names) result[name] = map[name];
-  } else {
-    for (const name of names) result[name] = process.env[name];
-  }
-  return result;
-}
-
 // src/lib/envVarNames.ts
 var TEMPLATE_VAR_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
 function extractTemplateVarNames(value) {
@@ -31974,7 +31999,12 @@ async function connectStdio(def, secretsPolicy, timeoutMs) {
   const transport = new StdioClientTransport({
     command: def.command,
     args: def.args,
-    env: { ...getDefaultEnvironment(), ...namedEnv }
+    // staticEnv merges last: a literal, intentionally-plain value (an
+    // email, an environment tag) always wins over an unresolved name-only
+    // 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 ?? {} }
   });
   return connectWithCleanup(client, transport, timeoutMs, `connect timed out after ${timeoutMs}ms`);
 }
@@ -32029,7 +32059,7 @@ function registerServerTools(pi, serverName, client, timeoutMs) {
 }
 async function trellisMcpBridge(pi, homeDir = homedir2(), connectTimeoutMs = DEFAULT_CONNECT_TIMEOUT_MS) {
   const canonical = loadCanonicalSource(homeDir);
-  const { desired } = resolveMcpPlan("pi", canonical.mcp, ALL_AGENTS);
+  const { desired } = resolveMcpPlan("pi", canonical.mcp, ALL_AGENTS, canonical.secretsPolicy);
   const clients = /* @__PURE__ */ new Set();
   const closeClient = async (client) => {
     if (!clients.delete(client)) return;

package/dist/pi-bridge/index.js

@@ -75,7 +75,12 @@ async function connectStdio(def, secretsPolicy, timeoutMs) {
     const transport = new StdioClientTransport({
         command: def.command,
         args: def.args,
-        env: { ...getDefaultEnvironment(), ...namedEnv },
+        // staticEnv merges last: a literal, intentionally-plain value (an
+        // email, an environment tag) always wins over an unresolved name-only
+        // 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 ?? {}) },
     });
     return connectWithCleanup(client, transport, timeoutMs, `connect timed out after ${timeoutMs}ms`);
 }
@@ -135,7 +140,7 @@ export default async function trellisMcpBridge(pi, homeDir = homedir(), connectT
     // independent of whether `trellis onboard` was ever run to add pi to
     // managed.yaml. managedAgents governs static config-file writes; this
     // is pi reading canonical directly at its own runtime, P4's own concern.
-    const { desired } = resolveMcpPlan("pi", canonical.mcp, ALL_AGENTS);
+    const { desired } = resolveMcpPlan("pi", canonical.mcp, ALL_AGENTS, canonical.secretsPolicy);
     const clients = new Set();
     const closeClient = async (client) => {
         if (!clients.delete(client))

package/dist/probes/codex.js

@@ -36,16 +36,24 @@ export async function probe(homeDir = homedir(), opts = {}) {
         return { agent: "codex", present: false, skillRoots: [], mcpServers: [], diagnostics: [] };
     }
     const diagnostics = [];
+    // `codex` resolves its own config via $HOME (confirmed by running it with
+    // an overridden HOME against an empty scratch dir — it returns `[]`, not
+    // the real machine's servers), so every subprocess call here must be
+    // scoped to `homeDir` explicitly — otherwise a caller probing a non-
+    // default `homeDir` would silently get this real machine's real MCP
+    // server list instead (trellis-migrate-mcp-servers found this gap in
+    // src/lib/mcpMigrateRead.ts's own equivalent call; fixed there first).
+    const codexEnv = { ...process.env, HOME: homeDir };
     let version;
     try {
-        version = execFileSync("codex", ["--version"], { encoding: "utf-8", timeout: 5_000 }).trim();
+        version = execFileSync("codex", ["--version"], { encoding: "utf-8", timeout: 5_000, env: codexEnv }).trim();
     }
     catch {
         // config exists without the binary on PATH — unusual, still probeable
     }
     let mcpEntries = [];
     try {
-        const raw = execFileSync("codex", ["mcp", "list", "--json"], { encoding: "utf-8", timeout: 5_000 });
+        const raw = execFileSync("codex", ["mcp", "list", "--json"], { encoding: "utf-8", timeout: 5_000, env: codexEnv });
         mcpEntries = JSON.parse(raw);
     }
     catch (err) {

package/docs/architecture.md

@@ -45,10 +45,13 @@ Aligned to the `.agents Protocol` draft, extended where the draft is silent:
 ├── memories/*.md             # shared memory entries (server-memory backed)
 ├── scope.yaml                 # exceptions to "shared with all agents" —
 │                             # see "Private / agent-specific capabilities"
-├── secrets.policy.yaml       # which var names are allowed, nothing else
-└── trellis.lock.json         # NOT YET BUILT — planned ownership-tracking
-                              # file for MCP removal (docs/roadmap.md's P2
-                              # note); nothing in src/ reads or writes this
+└── secrets.policy.yaml       # which var names are allowed, nothing else
+
+# Not user-authored, so not shown in the tree above — Trellis's own
+# bookkeeping, written/read only by `trellis mcp sync` itself:
+#   mcp/ownership.json  # what Trellis last wrote per (agent, server name) —
+#                       # the ownership marker MCP removal needed
+#                       # (docs/roadmap.md P14, src/lib/mcpOwnership.ts)
 ```
 
 ## Global vs. workspace scope

package/docs/getting-started.md

@@ -24,11 +24,14 @@ commands to type by hand:
    - **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 with a numbered choice (if you're at a real
-     terminal), or pass `--agent <id>` to skip the 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.
 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 numbered multi-select prompt.
+   pi,codex`) or `--manage none`, or answer the interactive checkbox prompt
+   (Space to toggle, Enter to confirm — same numbered fallback as above).
    **The source is not included by default** — migrating from Claude Code
    doesn't mean Trellis starts managing Claude Code too, unless you say so.
    Selecting an agent that isn't installed yet is itself the authorization to
@@ -134,27 +137,133 @@ Add `--dry-run` to see the plan without writing anything:
 $ trellis migrate --from codex --dry-run
 ```
 
+Add `--only skills`, `--only instructions`, or `--only mcp` to migrate
+just one category — useful when you only want part of it brought in
+right now. Omit it to migrate all three, exactly as above:
+
+```
+$ trellis migrate --from codex --only instructions
+```
+
 **What each action means:**
 
 | Action | Meaning |
 |---|---|
 | `create` | New to canonical source — copied in. |
-| `already-migrated` | Canonical already has byte-identical content (safe re-run, nothing happens). |
+| `already-migrated` | Canonical already has byte-identical (or, for MCP servers, structurally identical) content (safe re-run, nothing happens). |
 | `conflict` | Canonical already has *different* real content — **left untouched**, resolve by hand. |
 | `skip-symlink` | That agent's own copy is itself a symlink (already shared in from elsewhere) — nothing of that agent's own to import. |
 | `skip-case-broken` | Found as `skill.md` instead of `SKILL.md` — fix the case on the source agent first. |
+| `skip-unsupported` | MCP servers only — that agent's real definition can't be safely represented (see below); nothing was written for it. |
 
 Migrate never overwrites a genuine conflict, and never scopes a migrated
-skill to just the source agent — once in canonical, it's visible to every
-agent by default (see `sync`, below). If migrate reports a `conflict`, open
-the two files it names and decide by hand which content should actually be
-canonical, then re-run.
+skill (or MCP server) to just the source agent — once in canonical, it's
+visible to every agent by default (see `sync`, below). If migrate reports
+a `conflict`, open the two files/entries it names and decide by hand
+which content should actually be canonical, then re-run.
+
+**MCP servers** (claude-code, kiro, codex — not pi, which has no static
+MCP config to read at all) migrate the same way, into
+`~/.trellis/mcp/servers.yaml`:
+
+```
+$ trellis migrate --from claude-code --only mcp
+migrate --from claude-code
+  [create] mcp server "gitlab" — will add to servers.yaml
+```
+
+Two known fidelity limits, named rather than silently worked around:
+
+- **Codex remote servers migrate when they only use `url` and
+  `bearer_token_env_var`** — the one shape this codebase has verified
+  against a real `codex` binary, and the only shape Trellis's own writer
+  ever produces for Codex. Codex's own config schema has no way to tell
+  `http` apart from `sse`, so a migrated remote server always comes back
+  as `http` — not a guess, that distinction was never stored in the
+  first place. A server using Codex's other header mechanisms
+  (`http_headers`/`env_http_headers`/`http_headers_helper` — real fields
+  this project has no verified shape for) is reported `skip-unsupported`
+  rather than guessed at; use `trellis mcp add` for that one server as a
+  workaround.
+- **`headers` recovery depends on that agent's own real on-disk shape.**
+  claude-code/kiro read `headers` from the exact same JSON field Trellis
+  itself writes (`schema/servers.example.yaml`'s `figma` example) — if a
+  server was hand-authored with some other shape, it migrates whatever
+  is actually there, same as any other field.
 
 ## Starting from nothing
 
 Skip migrate. Edit `~/.trellis/agents.md` and add skills under
-`~/.trellis/skills/<name>/SKILL.md` directly. There's nothing else to set up
-before moving on to `sync`.
+`~/.trellis/skills/<name>/SKILL.md` directly, or use
+`trellis skill add` (below) instead of hand-editing. There's nothing else
+to set up before moving on to `sync`.
+
+The same applies to MCP servers — `~/.trellis/mcp/servers.yaml` can be
+hand-authored the same way (see
+[`schema/servers.example.yaml`](../schema/servers.example.yaml) for the
+full shape), or use `trellis mcp add` (below). Either way, move on to
+[`trellis mcp sync`](#trellis-mcp-sync) once you've added what you want.
+
+## `trellis skill` / `trellis mcp` — canonical CRUD via the CLI
+
+An alternative to hand-editing canonical files directly — useful for
+scripting, or when you'd rather not open a text editor for a one-line
+change. Both commands are canonical-side only: they never touch any
+agent's native config (that stays `sync`/`mcp sync`'s job).
+
+```
+$ trellis skill list
+my-skill — claude-code, codex, pi
+
+$ trellis skill add my-other-skill --from ./some/local/dir
+skill add my-other-skill
+  [create] will copy from ./some/local/dir
+
+$ trellis skill remove my-other-skill
+removed skill "my-other-skill" from canonical source.
+```
+
+`skill add` refuses (no write) if the name already exists with different
+content — same conflict posture as `migrate`, never silently overwritten.
+`skill remove` deletes the canonical directory; the *next* `trellis sync`
+then auto-removes the now-stale symlink on every agent that had it (skills
+carry their own ownership marker — the symlink itself — so this
+propagates automatically, unlike MCP servers below).
+
+```
+$ trellis mcp list
+tanka (http) — codex, pi
+  env: TANKA_TOKEN (values never read/printed)
+
+$ trellis mcp add local-server --transport stdio --command node --args server.js --env API_KEY
+mcp add local-server
+  [create] will add to servers.yaml
+
+$ trellis mcp remove local-server
+removed MCP server "local-server" from canonical source.
+```
+
+`mcp add` takes `--transport stdio|http|sse`; stdio requires `--command`
+(plus optional `--args a,b`, `--env NAME,...`, `--static-env k=v,...`),
+http/sse require `--url` (plus optional `--headers k=v,...`, values
+expected as `${VAR}` references, never literal secrets). Both accept
+`--agents id,...` (scope) and `--enabled true|false`. Same no-overwrite
+conflict posture as `skill add` — there is no `--force`.
+
+`mcp remove` is **canonical-only** — it does not remove the server from
+any agent that already has it from an earlier `mcp sync` (the same
+no-automatic-removal gap `mcp sync` itself has — see
+[README's Known limitations](../README.md#status)); remove it by hand on
+each agent in the meantime.
+
+`mcp list` never resolves or prints a secret value: `env` names are shown
+as bare names (the actual value is never read from your shell), and
+`static_env` values are shown in full since those were never secrets in
+the first place (see `mcp sync`'s own explanation of `env` vs.
+`static_env`, further below).
+
+All four of `skill add`/`skill remove`/`mcp add`/`mcp remove` support
+`--dry-run` and `--json`, same convention as every other command.
 
 ## `trellis sync`
 
@@ -220,6 +329,53 @@ already populates them. See
 for exactly how that resolution works for each agent, including the one
 narrow exception (pi's bridge has to read a value into its own process).
 
+Before writing any name-only `env` entry, `mcp sync` checks it actually
+resolves — a name with no value anywhere `secrets audit` would also
+check is refused as a conflict for that one server, not written and left
+to silently break that server once the agent tries to use it. Every
+other server, and every other agent, still syncs normally.
+
+For a value that isn't a secret at all — an email address, an
+environment tag — use `static_env` instead of `env`: written into the
+agent's config verbatim, never treated as a name to resolve (still
+scanned for an accidental real credential, same as every other literal
+field). `enabled: false` keeps a server's 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 `true`) to
+turn it back on everywhere at once. See
+[`schema/servers.example.yaml`](../schema/servers.example.yaml) for both.
+
+## `trellis memory sync`
+
+Ingests `~/.trellis/memories/*.md` into the actual on-disk file
+`@modelcontextprotocol/server-memory` reads at its own startup — closing
+the gap between "memory entries exist in canonical" and "the running
+memory server actually knows about them." Requires a `memory` server in
+`servers.yaml` with `static_env.MEMORY_FILE_PATH` set explicitly (see
+[`schema/servers.example.yaml`](../schema/servers.example.yaml)); without
+one, this is a no-op, not an error.
+
+```
+$ trellis memory sync
+memory sync — /Users/you/.trellis/memories/graph.jsonl
+  [create] "sprint-tasks" — will create a new entity
+```
+
+Every entry Trellis creates is tagged internally so a later sync can
+safely update or remove it; anything else already in that file — an
+entity or relation an agent added itself while actually using the memory
+server — is never touched. If a name collides with something already in
+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.
+
 ## `trellis secrets audit`
 
 ```