agent-trellis 0.6.0 → 0.6.3

package/dist/adapters/mcpPlan.d.ts

@@ -45,4 +45,20 @@ export interface McpPlanResult {
     desired: DesiredMcpEntry[];
     conflicts: McpConflict[];
 }
+/**
+ * Exported so `migrate`'s own read path (`src/commands/migrate.ts`) can
+ * apply the identical check on the way *into* canonical, not just on the
+ * way out to an agent's native config. Found via real-machine dogfooding:
+ * `migrate --from kiro --only mcp` happily copied a real, live
+ * `MCPR_TOKEN` literal into `~/.trellis/mcp/servers.yaml` because this
+ * check previously existed only here, in `resolveMcpPlan` — canonical
+ * itself was never guarded, only the sync-out boundary was. A canonical
+ * file that briefly held a real secret before a later `mcp sync` refused
+ * to propagate it further already violates "never write a literal
+ * secret, ever" — the write already happened, in a file meant to be
+ * read, diffed, and committed as plain text. One shared implementation,
+ * not two that can drift, for the same reason `mcpConnect.ts`/
+ * `mcpToolRegistry.ts` are shared between pi-bridge and the gateway.
+ */
+export declare function findLiteralSecret(def: McpServerDef): string | undefined;
 export declare function resolveMcpPlan(agentId: AgentId, mcp: McpConfig, managedAgents: readonly AgentId[], policy: SecretsPolicy): McpPlanResult;

package/dist/adapters/mcpPlan.js

@@ -57,7 +57,22 @@ const DANGEROUS_LITERAL_PATTERNS = [
     { label: "GitHub personal access token (ghp_)", pattern: /ghp_/ },
     { label: "mcp-router token (mcpr_)", pattern: /mcpr_/ },
 ];
-function findLiteralSecret(def) {
+/**
+ * Exported so `migrate`'s own read path (`src/commands/migrate.ts`) can
+ * apply the identical check on the way *into* canonical, not just on the
+ * way out to an agent's native config. Found via real-machine dogfooding:
+ * `migrate --from kiro --only mcp` happily copied a real, live
+ * `MCPR_TOKEN` literal into `~/.trellis/mcp/servers.yaml` because this
+ * check previously existed only here, in `resolveMcpPlan` — canonical
+ * itself was never guarded, only the sync-out boundary was. A canonical
+ * file that briefly held a real secret before a later `mcp sync` refused
+ * to propagate it further already violates "never write a literal
+ * secret, ever" — the write already happened, in a file meant to be
+ * read, diffed, and committed as plain text. One shared implementation,
+ * not two that can drift, for the same reason `mcpConnect.ts`/
+ * `mcpToolRegistry.ts` are shared between pi-bridge and the gateway.
+ */
+export function findLiteralSecret(def) {
     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) {

package/dist/cli.js

@@ -38,6 +38,16 @@ Commands:
                                     means "add nothing new this run"
                                     (required with no terminal to prompt
                                     in, e.g. --json)
+              --mcp-mode <direct|hub|gateway>
+                                    change the MCP mode; omit to leave
+                                    whatever's already configured
+                                    untouched (never prompted)
+              --hub-url <url>       required with --mcp-mode hub
+              --gateway-agents <ids>
+                                    optional with --mcp-mode gateway;
+                                    omit for every managed agent
+              --memory <on|off>     enable/disable the shared memory MCP
+                                    server; omit to leave it untouched
               --dry-run             preview the whole flow, write nothing
               --json                machine-readable output, no report text
   init      Create ~/.trellis/ with a minimal valid skeleton if missing
@@ -155,7 +165,24 @@ async function main(argv) {
         const agent = agentIndex >= 0 ? rest[agentIndex + 1] : undefined;
         const manageIndex = rest.indexOf("--manage");
         const manage = manageIndex >= 0 ? rest[manageIndex + 1] : undefined;
-        const { exitCode } = await runOnboard({ agent, manage, dryRun: rest.includes("--dry-run"), json: rest.includes("--json") });
+        const mcpModeIndex = rest.indexOf("--mcp-mode");
+        const mcpMode = mcpModeIndex >= 0 ? rest[mcpModeIndex + 1] : undefined;
+        const hubUrlIndex = rest.indexOf("--hub-url");
+        const hubUrl = hubUrlIndex >= 0 ? rest[hubUrlIndex + 1] : undefined;
+        const gatewayAgentsIndex = rest.indexOf("--gateway-agents");
+        const gatewayAgents = gatewayAgentsIndex >= 0 ? rest[gatewayAgentsIndex + 1] : undefined;
+        const memoryIndex = rest.indexOf("--memory");
+        const memory = memoryIndex >= 0 ? rest[memoryIndex + 1] : undefined;
+        const { exitCode } = await runOnboard({
+            agent,
+            manage,
+            mcpMode,
+            hubUrl,
+            gatewayAgents,
+            memory,
+            dryRun: rest.includes("--dry-run"),
+            json: rest.includes("--json"),
+        });
         process.exitCode = exitCode;
         return;
     }

package/dist/commands/memory.d.ts

@@ -12,7 +12,22 @@
  * server process — both are plain file operations, same posture as
  * every other Trellis write.
  */
+import type { McpServerDef } from "../core/types.js";
 import { type MemoryExtractionPlan, type MemorySyncPlan } from "../lib/memoryGraph.js";
+/** Exported so `onboard` (`trellis onboard --memory on|off`,
+ * trellis-onboard-mcp-mode) can look up and write this same entry
+ * without hardcoding the name a second time. */
+export declare const MEMORY_SERVER_NAME = "memory";
+/**
+ * The literal definition `trellis onboard --memory on` writes — the
+ * same shape `schema/servers.example.yaml`'s commented-out `memory:`
+ * block documents, now a real, code-owned constant instead of the only
+ * place this shape existed being prose a user hand-transcribes
+ * (trellis-onboard-mcp-mode design.md D9). `MEMORY_FILE_PATH` must be
+ * set explicitly — see `resolveMemoryServerGraphPath`'s own comment for
+ * why an unset one isn't safe to leave to the server's own default.
+ */
+export declare const DEFAULT_MEMORY_SERVER_DEF: McpServerDef;
 export interface RunMemorySyncOptions {
     homeDir?: string;
     json?: boolean;

package/dist/commands/memory.js

@@ -17,7 +17,25 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { loadCanonicalSource } from "../core/canonical.js";
 import { parseMemoryGraph, planMemoryExtraction, planMemorySync, renderMemoryGraph } from "../lib/memoryGraph.js";
-const MEMORY_SERVER_NAME = "memory";
+/** Exported so `onboard` (`trellis onboard --memory on|off`,
+ * trellis-onboard-mcp-mode) can look up and write this same entry
+ * without hardcoding the name a second time. */
+export const MEMORY_SERVER_NAME = "memory";
+/**
+ * The literal definition `trellis onboard --memory on` writes — the
+ * same shape `schema/servers.example.yaml`'s commented-out `memory:`
+ * block documents, now a real, code-owned constant instead of the only
+ * place this shape existed being prose a user hand-transcribes
+ * (trellis-onboard-mcp-mode design.md D9). `MEMORY_FILE_PATH` must be
+ * set explicitly — see `resolveMemoryServerGraphPath`'s own comment for
+ * why an unset one isn't safe to leave to the server's own default.
+ */
+export const DEFAULT_MEMORY_SERVER_DEF = {
+    transport: "stdio",
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-memory"],
+    staticEnv: { MEMORY_FILE_PATH: "~/.trellis/memories/graph.jsonl" },
+};
 /**
  * Looks up `mcp.servers["memory"]` specifically (matching `schema/
  * servers.example.yaml`'s own naming convention for the default shared-

package/dist/commands/migrate.js

@@ -15,6 +15,7 @@ import { AGENTS_MD_TEMPLATE } from "./init.js";
 import { decideDirImport } from "../lib/dirEquals.js";
 import { deepEqual } from "../lib/deepEqual.js";
 import { readClaudeCodeMcpDefs, readCodexMcpDefs, readKiroMcpDefs, resolvedEnvTextMap } from "../lib/mcpMigrateRead.js";
+import { findLiteralSecret } from "../adapters/mcpPlan.js";
 import { loadCanonicalSource, upsertServerYaml } from "../core/canonical.js";
 import { ALL_AGENTS } from "../core/types.js";
 const PROBES = {
@@ -110,6 +111,23 @@ export function isSafeReclassification(existing, def) {
     return deepEqual(resolvedEnvTextMap(existing), resolvedEnvTextMap(def));
 }
 function planMcpServer(name, def, existing) {
+    // Checked first, before any comparison against `existing`: a source
+    // agent's real config holding a literal credential must never reach
+    // canonical at all, regardless of whether canonical already has
+    // something for this name. `resolveMcpPlan`'s own guard only protects
+    // the sync-OUT boundary (canonical -> agent) — this is the matching
+    // guard for the migrate-IN boundary (agent -> canonical), the gap a
+    // real `mcp-router` token in a real `kiro` config exposed.
+    const secretLabel = findLiteralSecret(def);
+    if (secretLabel) {
+        return {
+            kind: "mcp",
+            name,
+            action: "conflict",
+            detail: `refusing to import MCP server "${name}": a value matches a known-dangerous literal pattern (${secretLabel}) — canonical must hold variable NAMES only, never real values (docs/research.md "Secrets")`,
+            remediation: `move the real value in the source agent's own config to an environment variable (or your secrets manager), leaving only a name behind, then re-run migrate — canonical never accepts a literal credential, even briefly`,
+        };
+    }
     if (existing === undefined) {
         return { kind: "mcp", name, action: "create", detail: "will add to servers.yaml", mcpDef: def };
     }

package/dist/commands/onboard.d.ts

@@ -46,6 +46,20 @@ export interface RunOnboardOptions {
      * the literal string "none" for "add nothing new this run" — distinct
      * from omitting the flag, which requires a prompt or refuses. */
     manage?: string;
+    /** Non-interactive MCP-mode choice (trellis-onboard-mcp-mode). Omitted
+     * leaves whatever canonical already has untouched and prompts for
+     * nothing — "no change requested," not "please choose" (design.md
+     * D1), unlike `agent`/`manage` above. */
+    mcpMode?: string;
+    /** Required when `mcpMode === "hub"`; refused if given otherwise. */
+    hubUrl?: string;
+    /** Optional when `mcpMode === "gateway"` (comma-separated agent ids;
+     * omitted = every managed agent); refused if given otherwise. */
+    gatewayAgents?: string;
+    /** Non-interactive shared-memory-server toggle: `"on"` or `"off"`.
+     * Omitted leaves whatever's already configured untouched — same
+     * no-prompt posture as `mcpMode` (design.md D12). */
+    memory?: string;
     dryRun?: boolean;
     json?: boolean;
     /** Defaults to the real `~`; overridable for tests only. */
@@ -117,6 +131,25 @@ export interface OnboardResult {
      * inconsistent across agents independent of this run.
      */
     doctorReport?: DoctorReport;
+    /**
+     * The resolved MCP mode after this run (trellis-onboard-mcp-mode
+     * design.md D7) — `current` reflects canonical's state whether or not
+     * this run changed it, `changed` is `true` only when `--mcp-mode` was
+     * given and differed from what canonical had before this run. Absent
+     * on every early-refusal path before mode resolution is reached.
+     */
+    mcpMode?: {
+        current: "direct" | "hub" | "gateway";
+        previous: "direct" | "hub" | "gateway";
+        changed: boolean;
+    };
+    /** The resolved shared-memory-server state after this run, mirroring
+     * `mcpMode` (design.md D13). */
+    memory?: {
+        current: "on" | "off";
+        previous: "on" | "off";
+        changed: boolean;
+    };
     refusal?: string;
     /** Only set when no agent is present — the same values `--json` and
      * text output both surface, so a machine caller doesn't have to

package/dist/commands/onboard.js

@@ -22,13 +22,13 @@ import * as codexProbe from "../probes/codex.js";
 import * as kiroProbe from "../probes/kiro.js";
 import * as piProbe from "../probes/pi.js";
 import { ALL_AGENTS } from "../core/types.js";
-import { loadCanonicalSource } from "../core/canonical.js";
+import { loadCanonicalSource, removeServerYaml, upsertServerYaml, writeMcpModeYaml } from "../core/canonical.js";
 import { INSTALL_HINTS, collectInitReport } from "./init.js";
 import { applyMigratePlan, collectMigratePlan, printPlan as printMigratePlan } from "./migrate.js";
 import { collectSyncReport, printReport as printSyncReport } from "./sync.js";
 import { collectMcpSyncReport, printReport as printMcpSyncReport } from "./mcp.js";
 import { collectSecretsAuditReport, printReport as printSecretsAuditReport } from "./secretsAudit.js";
-import { applyMemorySync, collectMemorySyncResult, printMemorySyncResult } from "./memory.js";
+import { applyMemorySync, collectMemorySyncResult, printMemorySyncResult, DEFAULT_MEMORY_SERVER_DEF, MEMORY_SERVER_NAME } from "./memory.js";
 import { collectDoctorReport, printReport as printDoctorReport, resolveKnownHostInjected } from "./doctor.js";
 import { openBackupSession } from "../lib/backup.js";
 import { confirmAndInstall } from "../lib/installAgent.js";
@@ -230,6 +230,120 @@ function parseManagedSelection(raw, candidates) {
     }
     return { agents: [...new Set(agents)] };
 }
+/** Comma-separated agent ids only — unlike `parseManagedSelection`, no
+ * numbered-index shorthand, since `--gateway-agents` never has a
+ * numbered list on screen to refer back to (it's flag-only, never
+ * prompted; design.md D1/D4). */
+function parseAgentIdList(raw) {
+    const tokens = raw.split(",").map((t) => t.trim()).filter((t) => t.length > 0);
+    const agents = [];
+    for (const token of tokens) {
+        if (!ALL_AGENTS.includes(token)) {
+            return { error: `"${token}" is not a valid agent id — use one of ${ALL_AGENTS.join(", ")}` };
+        }
+        agents.push(token);
+    }
+    return [...new Set(agents)];
+}
+/**
+ * Validates `--mcp-mode`/`--hub-url`/`--gateway-agents` together, before
+ * any other work (trellis-onboard-mcp-mode design.md D4) — a bad
+ * combination refuses the whole run rather than being discovered
+ * partway through. `mode` is only set when `mcpMode` was actually
+ * given; omitted resolves to `{}`, meaning "no change requested," not
+ * an error (design.md D1) — distinct from every other field on
+ * `RunOnboardOptions`, where omission usually requires a prompt.
+ */
+function validateMcpModeOption(opts) {
+    const { mcpMode, hubUrl, gatewayAgents } = opts;
+    if (mcpMode === undefined) {
+        if (hubUrl !== undefined)
+            return { error: "--hub-url was given without --mcp-mode hub" };
+        if (gatewayAgents !== undefined)
+            return { error: "--gateway-agents was given without --mcp-mode gateway" };
+        return {};
+    }
+    if (mcpMode !== "direct" && mcpMode !== "hub" && mcpMode !== "gateway") {
+        return { error: `--mcp-mode must be one of direct, hub, gateway (got "${mcpMode}")` };
+    }
+    if (mcpMode !== "hub" && hubUrl !== undefined) {
+        return { error: "--hub-url was given without --mcp-mode hub" };
+    }
+    if (mcpMode !== "gateway" && gatewayAgents !== undefined) {
+        return { error: "--gateway-agents was given without --mcp-mode gateway" };
+    }
+    if (mcpMode === "direct")
+        return { mode: { kind: "direct" } };
+    if (mcpMode === "hub") {
+        if (!hubUrl)
+            return { error: "--mcp-mode hub requires --hub-url <url>" };
+        return { mode: { kind: "hub", url: hubUrl } };
+    }
+    // mcpMode === "gateway"
+    if (gatewayAgents === undefined)
+        return { mode: { kind: "gateway" } };
+    const agents = parseAgentIdList(gatewayAgents);
+    if ("error" in agents)
+        return agents;
+    return { mode: { kind: "gateway", agents } };
+}
+/** Same "omitted means no change requested" posture as
+ * `validateMcpModeOption` (design.md D12). */
+function validateMemoryOption(memory) {
+    if (memory === undefined)
+        return {};
+    if (memory !== "on" && memory !== "off")
+        return { error: `--memory must be "on" or "off" (got "${memory}")` };
+    return { value: memory };
+}
+function mcpModeValueOf(mcp) {
+    if (mcp.gateway?.enabled)
+        return "gateway";
+    if (mcp.hub)
+        return "hub";
+    return "direct";
+}
+function resolveMcpModeChange(mode, currentValue) {
+    if (!mode)
+        return { current: currentValue, previous: currentValue, changed: false };
+    return { current: mode.kind, previous: currentValue, changed: mode.kind !== currentValue, write: mode };
+}
+/**
+ * `value === "on"` against an already-host-injected `"memory"` refuses
+ * outright rather than writing a definition `mcp sync` would refuse to
+ * propagate to any agent a moment later (design.md D10) — the same fact
+ * `schema/servers.example.yaml`'s own comment already explains to a
+ * human reading it by hand.
+ */
+function resolveMemoryToggle(value, configuredBefore, knownHostInjected) {
+    const previous = configuredBefore ? "on" : "off";
+    if (value === undefined)
+        return { current: previous, previous, changed: false };
+    if (value === "on") {
+        if (configuredBefore)
+            return { current: "on", previous, changed: false };
+        if (knownHostInjected.includes(MEMORY_SERVER_NAME)) {
+            return {
+                refusal: `refusing to enable the memory server: "${MEMORY_SERVER_NAME}" is already listed in known_host_injected — a host on this machine is presumed to already inject its own memory connector under that name, so a static definition here would only collide the next time \`mcp sync\` runs`,
+            };
+        }
+        return { current: "on", previous, changed: true };
+    }
+    // value === "off"
+    if (!configuredBefore)
+        return { current: "off", previous, changed: false };
+    return { current: "off", previous, changed: true };
+}
+function mcpModeStatusLine(mode) {
+    if (!mode.changed)
+        return `mcp mode: ${mode.current} (unchanged) — pass --mcp-mode direct|hub|gateway to change`;
+    return `mcp mode: ${mode.current} (changed from ${mode.previous})`;
+}
+function memoryStatusLine(memory) {
+    if (!memory.changed)
+        return `memory: ${memory.current} (unchanged) — pass --memory ${memory.current === "on" ? "off" : "on"} to change`;
+    return `memory: ${memory.current} (changed from ${memory.previous})`;
+}
 async function resolveManagedAgents(opts, summary, alreadyManaged) {
     if (opts.manage !== undefined) {
         const parsed = parseManagedSelection(opts.manage, summary);
@@ -262,6 +376,20 @@ export async function collectOnboardPlan(opts = {}) {
     if (present.length === 0) {
         return { summary, installHints: { ...INSTALL_HINTS }, verdict: [] };
     }
+    // Validated up front, before any of this run's own writes (managed.yaml
+    // included) — a bad `--mcp-mode`/`--hub-url`/`--gateway-agents`/
+    // `--memory` combination refuses the whole run cleanly rather than
+    // being discovered partway through (design.md D4). The parsed results
+    // are reused later, once managed-set resolution has run (design.md
+    // D5/D11).
+    const mcpModeValidation = validateMcpModeOption(opts);
+    if ("error" in mcpModeValidation) {
+        return { summary, refusal: mcpModeValidation.error, verdict: [] };
+    }
+    const memoryValidation = validateMemoryOption(opts.memory);
+    if ("error" in memoryValidation) {
+        return { summary, refusal: memoryValidation.error, verdict: [] };
+    }
     const sourceCandidates = present.filter(hasContent);
     let source;
     let sourceReason;
@@ -341,6 +469,34 @@ export async function collectOnboardPlan(opts = {}) {
     if (!opts.dryRun) {
         writeManagedYaml(homeDir, managedAgents);
     }
+    // MCP mode + memory-server resolution (design.md D5/D11) — grouped
+    // with managed-set above as "how is this machine configured"
+    // decisions resolved once per run, ahead of migrate/sync/mcp-sync/
+    // memory-sync below, which act on the result. Both flags were already
+    // validated before managed-set was even touched; omitting either
+    // resolves to "no change requested" here too (design.md D1/D12) — no
+    // writer call at all, on either a first run or a later one.
+    const canonicalForModeAndMemory = loadCanonicalSource(homeDir);
+    const mcpModeResolution = resolveMcpModeChange(mcpModeValidation.mode, mcpModeValueOf(canonicalForModeAndMemory.mcp));
+    const mcpMode = { current: mcpModeResolution.current, previous: mcpModeResolution.previous, changed: mcpModeResolution.changed };
+    const serversYamlPath = join(homeDir, ".trellis", "mcp", "servers.yaml");
+    if (mcpModeResolution.write && !opts.dryRun) {
+        writeMcpModeYaml(serversYamlPath, mcpModeResolution.write);
+    }
+    const memoryConfiguredBefore = canonicalForModeAndMemory.mcp.servers[MEMORY_SERVER_NAME] !== undefined;
+    const memoryResolution = resolveMemoryToggle(memoryValidation.value, memoryConfiguredBefore, canonicalForModeAndMemory.mcp.knownHostInjected);
+    if ("refusal" in memoryResolution) {
+        return { summary, source, sourceReason, managedAgents, mcpMode, refusal: memoryResolution.refusal, verdict: [] };
+    }
+    const memory = { current: memoryResolution.current, previous: memoryResolution.previous, changed: memoryResolution.changed };
+    if (memory.changed && !opts.dryRun) {
+        if (memory.current === "on") {
+            upsertServerYaml(serversYamlPath, MEMORY_SERVER_NAME, DEFAULT_MEMORY_SERVER_DEF);
+        }
+        else {
+            removeServerYaml(serversYamlPath, MEMORY_SERVER_NAME);
+        }
+    }
     let migratePlan;
     let migrateSkipped;
     logProgress(opts, "migrate");
@@ -427,6 +583,8 @@ export async function collectOnboardPlan(opts = {}) {
         memorySyncResult,
         secretsAuditReport,
         doctorReport,
+        mcpMode,
+        memory,
         verdict,
     };
 }
@@ -453,7 +611,7 @@ export async function runOnboard(opts = {}) {
         console.log(JSON.stringify(result, null, 2));
     }
     else {
-        printResult(result, opts.dryRun ?? false);
+        printResult(result, opts.dryRun ?? false, shouldShowProgress(opts));
         // Always last — including on a fully clean run and on a refusal —
         // so the terminal state of the run is never a green line from
         // whichever stage happened to print last (spec: "Every run
@@ -482,7 +640,7 @@ export async function runOnboard(opts = {}) {
     const hasBlocked = result.verdict.some((item) => item.severity === "blocked");
     return { exitCode: hasBlocked ? 1 : 0 };
 }
-function printResult(result, dryRun) {
+function printResult(result, dryRun, showStatusLine) {
     if (dryRun)
         console.log("[dry run]");
     const present = result.summary.filter((s) => s.present);
@@ -517,6 +675,17 @@ function printResult(result, dryRun) {
                 : `${install.agent} has no npm package to install (see \`trellis init\`'s install hint) — left out of this run's managed set.`);
     }
     console.log(`Managed agents: ${result.managedAgents && result.managedAgents.length > 0 ? result.managedAgents.join(", ") : "(none)"}`);
+    // Informational only, never a prompt (design.md D6/D12,
+    // trellis-onboard-mcp-mode) — this is what keeps `--mcp-mode`/
+    // `--memory` discoverable without costing every run a keystroke.
+    // Suppressed under `--json` and non-TTY, same gate stage progress
+    // already uses.
+    if (showStatusLine && result.mcpMode) {
+        console.log(mcpModeStatusLine(result.mcpMode));
+    }
+    if (showStatusLine && result.memory) {
+        console.log(memoryStatusLine(result.memory));
+    }
     // Reuse `migrate`/`sync`'s own printing verbatim (including the
     // "nothing to migrate" / "already in sync" cases) rather than a second,
     // easily-drifting copy of this formatting. `dryRun: false` here since

package/dist/core/canonical.d.ts

@@ -4,7 +4,7 @@
  * workspace scope"). See openspec/changes/trellis-sync-p1/specs/
  * canonical-source-loading/spec.md for the exact contract this implements.
  */
-import type { CanonicalSource, McpServerDef } from "./types.js";
+import type { AgentId, CanonicalSource, McpServerDef } from "./types.js";
 /**
  * The on-disk shape for one server entry — `static_env`/`env_aliases`
  * (snake_case, like every other multi-word key across `.trellis/*.yaml`)
@@ -31,6 +31,32 @@ export declare function upsertServerYaml(path: string, name: string, def: McpSer
 /** Inverse of `upsertServerYaml` — same preservation guarantee, same
  * refusal posture on a missing/unparseable file. */
 export declare function removeServerYaml(path: string, name: string): ServersYamlWriteResult;
+/**
+ * `trellis onboard --mcp-mode <value>` (trellis-onboard-mcp-mode) —
+ * everything needed to select or clear the top-level `hub`/`gateway`
+ * mode fields, mutually exclusive by construction (design.md D3): a
+ * `"direct"` mode carries nothing to set, only two keys to clear.
+ */
+export type McpMode = {
+    kind: "direct";
+} | {
+    kind: "hub";
+    url: string;
+} | {
+    kind: "gateway";
+    agents?: AgentId[];
+};
+/**
+ * Sets or clears `servers.yaml`'s top-level `hub`/`gateway` keys — the
+ * write path `upsertServerYaml`/`removeServerYaml` don't cover, since
+ * both are scoped to one `servers` entry (design.md D2). Same
+ * `Document`-based mechanism, same refusal posture on a missing or
+ * unparseable file, same `forceBlockStyle` correction for a key set for
+ * the first time into a still-flow-style document (`trellis init`'s
+ * starter file). Selecting one mode always clears the other two
+ * (design.md D3) — never left for the caller to remember.
+ */
+export declare function writeMcpModeYaml(path: string, mode: McpMode): ServersYamlWriteResult;
 /**
  * `homeDir` defaults to the real `~` and is only ever overridden for tests
  * and `scripts/sandbox.sh` — the same seam P0's probes use

package/dist/core/canonical.js

@@ -165,6 +165,52 @@ export function removeServerYaml(path, name) {
     writeFileSync(path, doc.toString());
     return { ok: true };
 }
+/**
+ * Sets or clears `servers.yaml`'s top-level `hub`/`gateway` keys — the
+ * write path `upsertServerYaml`/`removeServerYaml` don't cover, since
+ * both are scoped to one `servers` entry (design.md D2). Same
+ * `Document`-based mechanism, same refusal posture on a missing or
+ * unparseable file, same `forceBlockStyle` correction for a key set for
+ * the first time into a still-flow-style document (`trellis init`'s
+ * starter file). Selecting one mode always clears the other two
+ * (design.md D3) — never left for the caller to remember.
+ */
+export function writeMcpModeYaml(path, mode) {
+    if (!existsSync(path)) {
+        return { ok: false, error: `${path} does not exist — run \`trellis init\` first` };
+    }
+    let doc;
+    try {
+        doc = parseDocument(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        return { ok: false, error: `could not parse ${path}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    switch (mode.kind) {
+        case "direct":
+            doc.delete("hub");
+            doc.delete("gateway");
+            break;
+        case "hub":
+            doc.setIn(["hub", "url"], mode.url);
+            doc.delete("gateway");
+            forceBlockStyle(doc.get("hub", true));
+            break;
+        case "gateway":
+            doc.setIn(["gateway", "enabled"], true);
+            if (mode.agents !== undefined) {
+                doc.setIn(["gateway", "agents"], mode.agents);
+            }
+            else {
+                doc.deleteIn(["gateway", "agents"]);
+            }
+            doc.delete("hub");
+            forceBlockStyle(doc.get("gateway", true));
+            break;
+    }
+    writeFileSync(path, doc.toString());
+    return { ok: true };
+}
 function loadSecretsPolicyYaml(path, homeDir) {
     if (!existsSync(path)) {
         return { allowedVars: [], rejectPatterns: [] };

package/dist/lib/envVarNames.d.ts

@@ -20,12 +20,29 @@ export declare function extractTemplateVarNames(value: string): string[];
  * same answer to "what names does this def reference," not two
  * separately-maintained collections. */
 export declare function declaredEnvNames(def: McpServerDef): string[];
-/** Claude Code / Kiro's config is real JSON — parse it and walk each
- * server's `env` object keys plus names embedded in `headers` object
- * *values* (unlike `env`, a header's key is an arbitrary header name,
- * not a variable name — the variable name lives inside the `${...}`
- * value). Returns `[]` (not a throw) on invalid JSON; that's a
- * diagnostic for a different command, not this extractor's job. */
+/**
+ * Claude Code / Kiro's config is real JSON — parse it and walk each
+ * server's `env` object *values*, plus names embedded in `headers`
+ * object values. Both read the same way: the variable name lives inside
+ * a `${...}` reference in the value, never the key alone.
+ *
+ * This matters because `env`/`staticEnv` share one JSON object with no
+ * structural tag distinguishing them (`renderJsonServerEntry`'s own doc
+ * comment) — `env`/`envAliases` render as a `${NAME}` reference,
+ * `staticEnv` renders as its literal value verbatim, same map. Reading
+ * every KEY unconditionally (as this function did before) swept
+ * `staticEnv`'s literal, never-a-secret keys into the same
+ * `allowed_vars` check `env` names need, and got `envAliases` wrong in
+ * the opposite direction — its value's `${sourceName}` differs from its
+ * own key, so a key-based read checked the wrong name against
+ * `allowed_vars` entirely. Extracting from the value fixes both at once:
+ * a literal `staticEnv` value has no `${...}` to match, so it
+ * contributes nothing; an `envAliases` entry correctly contributes its
+ * referenced source name, not its target key.
+ *
+ * Returns `[]` (not a throw) on invalid JSON; that's a diagnostic for a
+ * different command, not this extractor's job.
+ */
 export declare function extractJsonEnvVarNames(content: string): string[];
 /** Codex's config is TOML. The shapes audit needs: every `env_vars = [...]`
  * line's quoted string contents, plus a `bearer_token_env_var = "VAR"`

package/dist/lib/envVarNames.js

@@ -29,12 +29,29 @@ export function declaredEnvNames(def) {
     }
     return [...names];
 }
-/** Claude Code / Kiro's config is real JSON — parse it and walk each
- * server's `env` object keys plus names embedded in `headers` object
- * *values* (unlike `env`, a header's key is an arbitrary header name,
- * not a variable name — the variable name lives inside the `${...}`
- * value). Returns `[]` (not a throw) on invalid JSON; that's a
- * diagnostic for a different command, not this extractor's job. */
+/**
+ * Claude Code / Kiro's config is real JSON — parse it and walk each
+ * server's `env` object *values*, plus names embedded in `headers`
+ * object values. Both read the same way: the variable name lives inside
+ * a `${...}` reference in the value, never the key alone.
+ *
+ * This matters because `env`/`staticEnv` share one JSON object with no
+ * structural tag distinguishing them (`renderJsonServerEntry`'s own doc
+ * comment) — `env`/`envAliases` render as a `${NAME}` reference,
+ * `staticEnv` renders as its literal value verbatim, same map. Reading
+ * every KEY unconditionally (as this function did before) swept
+ * `staticEnv`'s literal, never-a-secret keys into the same
+ * `allowed_vars` check `env` names need, and got `envAliases` wrong in
+ * the opposite direction — its value's `${sourceName}` differs from its
+ * own key, so a key-based read checked the wrong name against
+ * `allowed_vars` entirely. Extracting from the value fixes both at once:
+ * a literal `staticEnv` value has no `${...}` to match, so it
+ * contributes nothing; an `envAliases` entry correctly contributes its
+ * referenced source name, not its target key.
+ *
+ * Returns `[]` (not a throw) on invalid JSON; that's a diagnostic for a
+ * different command, not this extractor's job.
+ */
 export function extractJsonEnvVarNames(content) {
     let parsed;
     try {
@@ -45,7 +62,9 @@ export function extractJsonEnvVarNames(content) {
     }
     const names = [];
     for (const server of Object.values(parsed.mcpServers ?? {})) {
-        names.push(...Object.keys(server.env ?? {}));
+        for (const value of Object.values(server.env ?? {})) {
+            names.push(...extractTemplateVarNames(value));
+        }
         for (const value of Object.values(server.headers ?? {})) {
             names.push(...extractTemplateVarNames(value));
         }

package/docs/architecture.md

@@ -176,9 +176,13 @@ regardless of hub mode.
 ## MCP hub mode
 
 Every agent's MCP surface can be either N direct server definitions
-(default) or one static entry pointing at a single HTTP endpoint — set
-`mcp.hub.url` in `mcp/servers.yaml` to switch (see
-`schema/servers.example.yaml`). Nothing about *what* runs behind that URL
+(default) or one static entry pointing at a single HTTP endpoint — `mcp.hub.url`
+in `mcp/servers.yaml` is the field, but the supported way to set it is
+`trellis onboard --mcp-mode hub --hub-url <url>` (trellis-onboard-mcp-mode),
+not hand-editing the file: onboard's own writer clears any conflicting
+`gateway` block for you and is the same command that later turns hub mode
+back off again (`--mcp-mode direct`). `schema/servers.example.yaml` still
+documents the raw field shape for reference. Nothing about *what* runs behind that URL
 is part of Trellis's design: a self-hosted
 [mcp-hub](https://github.com/ravitemer/mcp-hub) instance, a hosted
 mcp-router account, anything else speaking MCP over HTTP all look
@@ -275,11 +279,19 @@ native OAuth flow, exactly as before.
 
 Gateway mode collapses an agent's MCP config to one entry, like hub mode
 — but what sits behind it is a local subprocess Trellis owns
-(`trellis mcp-gateway --agent <id>`), not a URL someone operates. Set
-`mcp.gateway.enabled` in `mcp/servers.yaml`; add `mcp.gateway.agents` to
-narrow it to specific agents, or omit it to cover every managed agent.
-`gateway` and `hub` are independent fields and may both be set — gateway
-wins for any agent it covers.
+(`trellis mcp-gateway --agent <id>`), not a URL someone operates. Turn it
+on with `trellis onboard --mcp-mode gateway` (optionally
+`--gateway-agents <ids>` to narrow it to specific agents instead of every
+managed agent); `trellis onboard --mcp-mode direct` turns it back off.
+The underlying fields (`mcp.gateway.enabled`/`.agents` in
+`mcp/servers.yaml`) are what onboard's writer sets — hand-editing them is
+unsupported now that a real command exists for it
+(trellis-onboard-mcp-mode). Selecting `hub` instead always clears
+`gateway`, and vice versa (a mode selector, not two independently
+toggleable fields) — see "MCP hub mode" above for why onboard treats them
+as one mutually-exclusive choice rather than exposing the field-level
+"both set, gateway wins" flexibility `resolveMcpPlan` itself still
+tolerates for anyone who reaches this state some other way.
 
 **Lifecycle: there isn't one.** The agent spawns it like any other stdio
 MCP server and it exits when the session ends. No daemon, no
@@ -326,9 +338,11 @@ re-sync and nothing the user notices.
   subprocess with no lifecycle; hub mode points at something you operate.
   Neither is a service Trellis starts, supervises, or keeps running.
 - A memory backend (defaults to `@modelcontextprotocol/server-memory`,
-  documented in `schema/servers.example.yaml`; mem0/OpenMemory and
-  totalrecallai-class semantic-search servers documented as opt-in
-  upgrades — see docs/research.md "Shared memory")
+  turned on with `trellis onboard --memory on` (trellis-onboard-mcp-mode)
+  rather than hand-editing `servers.yaml`, documented in
+  `schema/servers.example.yaml`; mem0/OpenMemory and totalrecallai-class
+  semantic-search servers documented as opt-in upgrades — see
+  docs/research.md "Shared memory")
 - A secret vault (reads `${VAR}` from whatever the environment already
   provides — `~/.config/agent-env/secrets.env`, 1Password's `op run`,
   anything that populates `process.env` before an adapter's generated

package/docs/getting-started.md

@@ -16,10 +16,15 @@ $ 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`, `memory sync`, `secrets audit`, and a final health scan — the
-whole onboarding path, no follow-up commands to type by hand, and no need
-to run `trellis doctor` separately to know whether it actually worked.
+then resolves two interactive choices and two flag-only ones before running
+`migrate`, `sync`, `mcp sync`, `memory sync`, `secrets audit`, and a final
+health scan — the whole onboarding path, no follow-up commands to type by
+hand, and no need to run `trellis doctor` separately to know whether it
+actually worked. This is also the one command for reconfiguring an
+already-onboarded machine later: every one of the four choices below reads
+what's already there first, so a bare `trellis onboard` re-run changes
+nothing about them, and re-running with a new flag value updates exactly
+that.
 
 1. **Migration source** — read from, at most one, never written back to.
    "Real content" means skills, custom instructions, *or* real MCP servers
@@ -44,11 +49,36 @@ to run `trellis doctor` separately to know whether it actually worked.
    Selecting an agent that isn't installed yet is itself the authorization to
    install it (one confirmation, then a real `npm install -g <package>`);
    Kiro has no CLI package and is refused with its download URL instead.
+3. **MCP mode** — direct (the default), hub, or gateway. Flag-only, never
+   prompted: pass `--mcp-mode direct|hub|gateway` to change it (`--hub-url
+   <url>` is required with `hub`; `--gateway-agents <ids>` is optional with
+   `gateway`, omitted meaning every managed agent). Omitting `--mcp-mode`
+   entirely leaves whatever's already configured untouched — on a fresh
+   machine that's direct, on one you've already switched that's whatever
+   you last set — so a plain `trellis onboard` re-run never resets it. This
+   is the only supported way to turn gateway or hub mode on or off; there's
+   no reason to hand-edit `~/.trellis/mcp/servers.yaml`'s `hub`/`gateway`
+   keys directly.
+4. **The shared memory server** — off by default. Pass `--memory on` to add
+   the default `@modelcontextprotocol/server-memory` definition (refused if
+   a host on this machine already injects a connector named `memory` — see
+   [`trellis memory sync`](#trellis-memory-sync) below) or
+   `--memory off` to remove it. Omitting `--memory` preserves whatever's
+   already configured, same rule as MCP mode. Turning it on and seeing it
+   actually reach every managed agent and get populated from canonical
+   `memories/*.md` happens in the very same run — no second command needed.
+
+Both flags print a one-line status on a real terminal (`mcp mode: direct
+(unchanged) — pass --mcp-mode hub|gateway to change`, or `memory: on
+(changed from off)`) so they stay discoverable without turning into a
+prompt you have to answer on every run.
 
 ```
 $ trellis onboard --agent claude-code --manage pi
 Using claude-code as the migration source (--agent).
 Managed agents: pi
+mcp mode: direct (unchanged) — pass --mcp-mode direct|hub|gateway to change
+memory: off (unchanged) — pass --memory on to change
 
 migrate --from claude-code
   [create] skill "my-skill" — will copy from /Users/you/.claude/skills/my-skill
@@ -123,7 +153,8 @@ entirely under `--json` or when stdout isn't a real terminal.
 
 Add `--dry-run` to preview the entire chain — init/migrate/sync/mcp
 sync/memory sync, including what would be written to
-`~/.trellis/managed.yaml` — with zero writes anywhere (secrets audit and
+`~/.trellis/managed.yaml` and to `servers.yaml`'s mode/memory keys — with
+zero writes anywhere (secrets audit and
 the health scan are always read-only, with or without the flag; the
 write-verification step above has nothing to check on a dry run and is
 skipped entirely). On a real terminal, a `--dry-run` ends by offering to
@@ -490,7 +521,10 @@ 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.
+one, this is a no-op, not an error. `trellis onboard --memory on` is the
+easiest way to get that entry there — no hand-editing `servers.yaml`
+required — and this stage is already chained into `onboard`, so enabling
+it and syncing real canonical content into it happens in one run.
 
 ```
 $ trellis memory sync

package/docs/roadmap.md

@@ -953,6 +953,7 @@ tests passing.
 | 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 |
 | P21 | ✅ MCP gateway hosting: collapses each agent's MCP config to ONE native stdio entry (`trellis mcp-gateway --agent <id>`) that Trellis itself spawns — no Docker, no daemon, no lifecycle command. Four third-party gateways were evaluated and excluded on hard constraints (MetaMCP is Docker-only; mcp-local-hub is Windows-only today; `@samanhappy/mcphub` is a 43-dependency authenticated web product with no importable SDK surface; `@pcandido/mcphub` has correct OAuth but zero `${VAR}` expansion in its stdio `env`, verified by inspecting what a spawned child actually received — adopting it would mean plaintext secrets or a second resolution path outside `secrets audit`). Built instead on `pi-bridge`'s already-proven connect logic, extracted to `src/lib/mcpConnect.ts`, behind a `GatewayBackend` seam so the confirmed next step — one shared service for all agents, with the per-session process becoming a thin MCP-over-Unix-socket client — is a substitution at one construction site, with every agent's written config identical either way. Includes Trellis's own OAuth client (RFC 8414/9728 discovery, RFC 7591 DCR, RFC 7636 PKCE S256, refresh), tested against a hand-built Authorization Server that *enforces* those RFCs rather than rubber-stamping them; tokens live 0600 one-file-per-server outside canonical, never the OS keychain (macOS `security add-generic-password` measurably fails exit 152/154 with no GUI session — the gateway's exact context). Two bugs the design caught before shipping: the MCP SDK's stdio transport reports no EOF, so without explicit teardown every agent session would leak a gateway plus its whole upstream process set; and concurrent OAuth refresh silently kills a rotated refresh token, so it is serialized by a per-server lock. Remaining: the shared service itself (v2) | P2 |
 | P22 | ✅ Onboard closed loop: onboard used to stop the moment files were written, never checking whether any of it took effect, and never telling the user how the run went — a real run with a genuine sync conflict still ended its printed output on a later stage's unrelated green line. Two distinct fixes, not one: a **self-verification re-plan** (the mechanism that actually closes the loop) runs `sync`/`mcp sync` a second time, dry-run, immediately after their real apply, and treats anything still outstanding as its own blocking finding — `trellis doctor` was tried first and rejected for this job, since its six detectors compare agents against each other and never read canonical, so they cannot prove a write took effect even in principle. Doctor still runs, last, as a secondary whole-machine health scan (never `--probe-mcp` — the worst moment to spawn every configured MCP server is a user's first run of this command), with findings on an unmanaged agent demoted to a warning rather than hidden. Every stage's conflicts and findings normalize into one `VerdictItem[]`, printed as a terminal verdict block that is always the last thing on screen and always agrees with the exit code, each blocking item carrying a concrete remediation instead of a restatement of the problem. Also adds stage progress to stderr (never stdout, so `onboard > report.txt` stays exactly the report) and, on a real terminal, a `--dry-run` that ends by offering to apply (declining is the default; accepting re-plans against current state rather than replaying a now-stale preview) | P0 |
+| P23 | ✅ Onboard MCP mode + memory toggle: closes the last hand-editing gap — turning on gateway or hub mode, or the shared memory server, meant directly editing `~/.trellis/mcp/servers.yaml`'s top-level `hub`/`gateway` keys or its commented-out `memory:` example, since no command wrote them (`trellis mcp add`'s flags are all per-server). New `writeMcpModeYaml` in `src/core/canonical.ts` (`Document`-based, mirrors `upsertServerYaml`'s comment-preserving edit) plus `trellis onboard --mcp-mode direct\|hub\|gateway` (`--hub-url`, `--gateway-agents`) and `--memory on\|off` close it. Both follow onboard's existing managed-set idempotency shape rather than a new one: read current state first, omitting the flag always preserves it untouched with zero prompting — identical on a first run (nothing configured) and a later one (something already is), which is the actual point: one command for both, not a setup path and a separate reconfigure path. Deliberately flag-only, never an interactive picker (a mode change reroutes every managed agent's MCP transport at once — too wide a blast radius for Enter-mashing through a prompt sequence to trigger by accident); a one-line, non-prompting status line on a real terminal keeps the flags discoverable anyway. `--memory on` refuses outright if `"memory"` is already in `known_host_injected`, rather than writing a definition the very next `mcp sync` would refuse to propagate to any agent. Because mode/memory resolution runs before onboard's existing `mcp sync`/`memory sync` stages in the same chain, `trellis onboard --memory on` enables the server, syncs it to every managed agent, and populates it from canonical `memories/*.md` — all in one run | P17, P21, P22 |
 
 **Cross-machine / cloud sharing — confirmed future direction, not yet
 scoped as a phase.** Surveyed 2026-09-15 (`docs/research.md`'s "Cross-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-trellis",
-  "version": "0.6.0",
+  "version": "0.6.3",
   "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",
@@ -47,7 +47,6 @@
     "agents.md"
   ],
   "devDependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
     "@types/node": "^22.0.0",
     "esbuild": "^0.28.2",
     "tsx": "^4.19.0",
@@ -55,6 +54,7 @@
     "typescript": "^5.6.0"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "yaml": "^2.9.1"
   }
 }

package/schema/servers.example.yaml

@@ -35,8 +35,12 @@
 servers:
   # Default shared-memory backend (docs/research.md "Shared memory") —
   # @modelcontextprotocol/server-memory: zero-dependency, local JSON
-  # knowledge graph, MIT-licensed. Left commented out here because this
-  # exact example ALSO lists "memory" under known_host_injected below —
+  # knowledge graph, MIT-licensed. `trellis onboard --memory on` writes
+  # exactly this shape for you (src/commands/memory.ts's
+  # DEFAULT_MEMORY_SERVER_DEF) — uncommenting it by hand below is only
+  # for understanding what that flag does, not required to use it.
+  # Left commented out here because this exact example ALSO lists
+  # "memory" under known_host_injected below —
   # uncommenting both would self-collide (Trellis's own collision guard
   # would correctly refuse to write it). Which situation you're actually
   # in depends on your host:
@@ -44,8 +48,9 @@ servers:
   #     under this name — check with `trellis doctor` — leave this
   #     commented out and keep "memory" in known_host_injected below;
   #     you already have it, just not from a static definition.
-  #   - If your host injects nothing under this name, uncomment this
-  #     entry AND remove "memory" from known_host_injected below (it's
+  #   - If your host injects nothing under this name, run `trellis
+  #     onboard --memory on` (or uncomment this entry by hand) AND
+  #     remove "memory" from known_host_injected below (it's
   #     only there as inherited example content, not a fact about your
   #     environment) — that's what actually wires the default.
   # mem0/OpenMemory or a totalrecallai-class semantic-search server are