agent-trellis 0.6.3 → 0.8.0

package/dist/commands/onboardVerdict.js

@@ -42,12 +42,25 @@ export function normalizeMigrateVerdict(plan) {
         return [];
     const items = [];
     for (const item of plan.items) {
-        if (item.action !== "conflict")
-            continue;
-        const verdict = { stage: "migrate", severity: "blocked", message: item.detail };
-        if (item.remediation)
-            verdict.remediation = item.remediation;
-        items.push(verdict);
+        if (item.action === "conflict") {
+            const verdict = { stage: "migrate", severity: "blocked", message: item.detail };
+            if (item.remediation)
+                verdict.remediation = item.remediation;
+            items.push(verdict);
+        }
+        else if (item.action === "extract-secret") {
+            // The run succeeded — never `blocked` — but stands as a standing
+            // reminder, not a silent success: migrate never writes to the
+            // source agent's own file (design.md D2), so it still holds the
+            // real value in plaintext forever, independent of this extraction
+            // (trellis-migrate-extract-static-env-secrets design.md D8).
+            items.push({
+                stage: "migrate",
+                severity: "warning",
+                message: item.detail,
+                remediation: `the source agent's own configuration for "${item.name}" was not modified and may still hold "${item.extractVarName}"'s real value in plaintext — clean it up by hand if you want it gone from there too`,
+            });
+        }
     }
     return items;
 }
@@ -103,7 +116,7 @@ export function normalizeSecretsAuditVerdict(report) {
         return [];
     return report.findings.map((finding) => {
         const item = { stage: "secrets audit", severity: "blocked", message: `${finding.file}: ${finding.detail}` };
-        if (finding.agent !== "environment")
+        if (finding.agent !== "environment" && finding.agent !== "canonical")
             item.agent = finding.agent;
         return item;
     });

package/dist/commands/rollback.js

@@ -134,7 +134,10 @@ async function restoreOperation(homeDir, runId, op) {
 }
 export async function applyRollbackPlan(homeDir, runId, manifest, items) {
     const restorePaths = new Set(items.filter((i) => i.action === "restore").map((i) => i.path));
-    for (const op of manifest.operations) {
+    // Restore in reverse write order. A single onboarding transaction may
+    // update servers.yaml several times (mode, memory, routes); replaying
+    // restores forward would leave the file at an intermediate snapshot.
+    for (const op of [...manifest.operations].reverse()) {
         if (!restorePaths.has(op.path))
             continue;
         await restoreOperation(homeDir, runId, op);

package/dist/commands/secretsAudit.d.ts

@@ -1,15 +1,23 @@
 /**
  * `trellis secrets audit` — reads every present, MCP-capable agent's real
- * config file (never the canonical source) and checks it against
- * `CanonicalSource.secretsPolicy`: a literal-value scan against
- * `rejectPatterns`, and a declared-env-var-name check against
- * `allowedVars`. Also checks, agent-agnostically, whether every env var
- * name declared across canonical `mcp.servers[*].env` actually resolves
- * to a value via the same `resolveSecretEnv` the pi bridge uses
- * (trellis-secrets-env-management) — authoritative for pi, a best-effort
- * proxy for the other three (design.md D3 in that change). Read-only —
- * never writes anything. Fails non-zero on any finding
- * (trellis-secrets-audit-p3).
+ * config file and checks it against `CanonicalSource.secretsPolicy`: a
+ * literal-value scan against `rejectPatterns`, and a declared-env-var-name
+ * check against `allowedVars`. Also checks, agent-agnostically, whether
+ * every env var name declared across canonical `mcp.servers[*].env`
+ * actually resolves to a value via the same `resolveSecretEnv` the pi
+ * bridge uses (trellis-secrets-env-management) — authoritative for pi, a
+ * best-effort proxy for the other three (design.md D3 in that change).
+ *
+ * Also scans canonical's own `mcp/servers.yaml` for the reject-pattern
+ * literal-value check (trellis-migrate-extract-static-env-secrets design.md
+ * D11): a literal in `command`/`url`/`args`/`headers` is now accepted into
+ * canonical by `migrate` rather than refused (no natural name to extract
+ * to, or no `${VAR}` resolution proven for every consumer), so canonical
+ * is no longer guaranteed clean by construction the way it used to be —
+ * this keeps that acceptance from being silent. Never the
+ * unexpected-var-name check, which is about agent-native serialized
+ * `env`/`env_vars` syntax specifically. Read-only — never writes
+ * anything. Fails non-zero on any finding (trellis-secrets-audit-p3).
  */
 import type { AgentId } from "../core/types.js";
 export interface RunSecretsAuditOptions {
@@ -23,8 +31,9 @@ export interface RunSecretsAuditOptions {
 }
 export interface SecretsFinding {
     /** "environment" for `missing-env-value` — that check isn't scoped to
-     * any single agent's config file (see module doc comment). */
-    agent: AgentId | "environment";
+     * any single agent's config file. "canonical" for a literal found in
+     * `~/.trellis/mcp/servers.yaml` itself (see module doc comment). */
+    agent: AgentId | "environment" | "canonical";
     file: string;
     kind: "literal-secret" | "unexpected-var-name" | "missing-env-value";
     detail: string;

package/dist/commands/secretsAudit.js

@@ -1,15 +1,23 @@
 /**
  * `trellis secrets audit` — reads every present, MCP-capable agent's real
- * config file (never the canonical source) and checks it against
- * `CanonicalSource.secretsPolicy`: a literal-value scan against
- * `rejectPatterns`, and a declared-env-var-name check against
- * `allowedVars`. Also checks, agent-agnostically, whether every env var
- * name declared across canonical `mcp.servers[*].env` actually resolves
- * to a value via the same `resolveSecretEnv` the pi bridge uses
- * (trellis-secrets-env-management) — authoritative for pi, a best-effort
- * proxy for the other three (design.md D3 in that change). Read-only —
- * never writes anything. Fails non-zero on any finding
- * (trellis-secrets-audit-p3).
+ * config file and checks it against `CanonicalSource.secretsPolicy`: a
+ * literal-value scan against `rejectPatterns`, and a declared-env-var-name
+ * check against `allowedVars`. Also checks, agent-agnostically, whether
+ * every env var name declared across canonical `mcp.servers[*].env`
+ * actually resolves to a value via the same `resolveSecretEnv` the pi
+ * bridge uses (trellis-secrets-env-management) — authoritative for pi, a
+ * best-effort proxy for the other three (design.md D3 in that change).
+ *
+ * Also scans canonical's own `mcp/servers.yaml` for the reject-pattern
+ * literal-value check (trellis-migrate-extract-static-env-secrets design.md
+ * D11): a literal in `command`/`url`/`args`/`headers` is now accepted into
+ * canonical by `migrate` rather than refused (no natural name to extract
+ * to, or no `${VAR}` resolution proven for every consumer), so canonical
+ * is no longer guaranteed clean by construction the way it used to be —
+ * this keeps that acceptance from being silent. Never the
+ * unexpected-var-name check, which is about agent-native serialized
+ * `env`/`env_vars` syntax specifically. Read-only — never writes
+ * anything. Fails non-zero on any finding (trellis-secrets-audit-p3).
  */
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -57,6 +65,26 @@ function findMissingEnvValues(servers, policy) {
         detail: `"${name}" is declared by a canonical MCP server's env but has no resolvable value`,
     }));
 }
+/**
+ * Reject-pattern-only scan of canonical's own `mcp/servers.yaml` (design.md
+ * D11) — no `unexpected-var-name` check here, that one is specifically
+ * about names extracted from an agent's own serialized `env`/`env_vars`
+ * syntax, not canonical's `env:` name list (which holding a name matching
+ * a reject pattern would be an absurd false positive, not a real finding).
+ */
+function auditCanonicalServersYaml(homeDir, policy) {
+    const file = join(homeDir, ".trellis", "mcp", "servers.yaml");
+    if (!existsSync(file))
+        return [];
+    const content = readFileSync(file, "utf-8");
+    const findings = [];
+    for (const pattern of policy.rejectPatterns) {
+        if (pattern.test(content)) {
+            findings.push({ agent: "canonical", file, kind: "literal-secret", detail: `matches reject pattern ${pattern}` });
+        }
+    }
+    return findings;
+}
 function auditFile(agent, file, content, policy, extractNames) {
     const findings = [];
     for (const pattern of policy.rejectPatterns) {
@@ -88,6 +116,7 @@ export async function collectSecretsAuditReport(opts = {}) {
         findings.push(...auditFile(agent.id, file, content, canonical.secretsPolicy, agent.extractNames));
     }
     findings.push(...findMissingEnvValues(canonical.mcp.servers, canonical.secretsPolicy));
+    findings.push(...auditCanonicalServersYaml(homeDir, canonical.secretsPolicy));
     return { findings };
 }
 export async function runSecretsAudit(opts = {}) {

package/dist/commands/skill.d.ts

@@ -8,6 +8,23 @@
  * symlinkPlan.ts`'s pre-existing stale-symlink removal.
  */
 import type { AgentId } from "../core/types.js";
+import { type BackupSession } from "../lib/backup.js";
+export type BuiltinSkillUpdateAction = "create" | "update" | "already-current";
+export interface BuiltinSkillUpdatePlan {
+    name: "trellis-runtime";
+    action: BuiltinSkillUpdateAction;
+    detail: string;
+    path: string;
+}
+export declare function collectBuiltinSkillUpdatePlan(homeDir?: string): BuiltinSkillUpdatePlan;
+export declare function applyBuiltinSkillUpdatePlan(plan: BuiltinSkillUpdatePlan, backup?: BackupSession): void;
+export declare function runSkillUpdateBuiltin(opts?: {
+    homeDir?: string;
+    json?: boolean;
+    dryRun?: boolean;
+}): {
+    exitCode: number;
+};
 export interface SkillListEntry {
     name: string;
     scope: readonly AgentId[];

package/dist/commands/skill.js

@@ -7,16 +7,56 @@
  * `decideDirImport` (src/lib/dirEquals.ts) and `src/adapters/
  * symlinkPlan.ts`'s pre-existing stale-symlink removal.
  */
-import { cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { decideDirImport } from "../lib/dirEquals.js";
 import { findSkillFile } from "../lib/skillFile.js";
 import { loadCanonicalSource } from "../core/canonical.js";
 import { resolveScope } from "../core/types.js";
+import { isBuiltinSkillName } from "../lib/builtinSkills.js";
+import { openBackupSession } from "../lib/backup.js";
+function builtinSkillTemplate() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return readFileSync(join(here, "..", "..", "schema", "builtin-skills", "trellis-runtime", "SKILL.md"), "utf8");
+}
+export function collectBuiltinSkillUpdatePlan(homeDir = homedir()) {
+    const path = join(homeDir, ".trellis", "skills", "trellis-runtime", "SKILL.md");
+    if (!existsSync(path))
+        return { name: "trellis-runtime", action: "create", detail: "will install the package-owned Runtime Skill", path };
+    if (readFileSync(path, "utf8") === builtinSkillTemplate())
+        return { name: "trellis-runtime", action: "already-current", detail: "package-owned Runtime Skill is already current", path };
+    return { name: "trellis-runtime", action: "update", detail: "will refresh the package-owned Runtime Skill; existing Agent symlinks will see the update", path };
+}
+export function applyBuiltinSkillUpdatePlan(plan, backup) {
+    if (plan.action === "already-current")
+        return;
+    const content = builtinSkillTemplate();
+    mkdirSync(dirname(plan.path), { recursive: true });
+    if (backup)
+        backup.writeFile(plan.path, content);
+    else
+        writeFileSync(plan.path, content);
+}
+export function runSkillUpdateBuiltin(opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const plan = collectBuiltinSkillUpdatePlan(homeDir);
+    if (!opts.dryRun && plan.action !== "already-current") {
+        const backup = openBackupSession(homeDir, "skill-update-builtin");
+        applyBuiltinSkillUpdatePlan(plan, backup);
+        backup.finalize();
+    }
+    if (opts.json)
+        console.log(JSON.stringify(plan, null, 2));
+    else
+        console.log(`${opts.dryRun ? "[dry run] " : ""}skill update-builtin\n  [${plan.action}] ${plan.detail}`);
+    return { exitCode: 0 };
+}
 export function collectSkillList(homeDir = homedir()) {
     const canonical = loadCanonicalSource(homeDir);
-    return canonical.skills.map((skill) => ({
+    return canonical.skills.filter((skill) => !isBuiltinSkillName(skill.name)).map((skill) => ({
         name: skill.name,
         scope: resolveScope(skill.scope, canonical.managedAgents),
     }));
@@ -37,6 +77,9 @@ export function runSkillList(opts = {}) {
     return { exitCode: 0 };
 }
 export function collectSkillAddPlan(name, fromPath, homeDir = homedir()) {
+    if (isBuiltinSkillName(name)) {
+        return { name, action: "conflict", detail: `"${name}" is a Trellis package-owned Skill and cannot be replaced with skill add` };
+    }
     const skillFile = findSkillFile(fromPath);
     if (!skillFile) {
         return { name, action: "invalid-source", detail: `${fromPath} has no SKILL.md` };
@@ -77,6 +120,8 @@ export function runSkillAdd(name, fromPath, opts = {}) {
     return { exitCode: plan.action === "conflict" || plan.action === "invalid-source" ? 1 : 0 };
 }
 export function collectSkillRemovePlan(name, homeDir = homedir()) {
+    if (isBuiltinSkillName(name))
+        return { name, action: "not-found" };
     const dir = join(homeDir, ".trellis", "skills", name);
     return { name, action: existsSync(dir) ? "removed" : "not-found" };
 }

package/dist/commands/sync.js

@@ -11,12 +11,14 @@ import { ClaudeCodeAdapter } from "../adapters/claude-code.js";
 import { CodexAdapter } from "../adapters/codex.js";
 import { KiroAdapter } from "../adapters/kiro.js";
 import { PiAdapter } from "../adapters/pi.js";
+import { KimiCodeAdapter } from "../adapters/kimi-code.js";
 import { openBackupSession } from "../lib/backup.js";
 const ADAPTER_FACTORY = {
     "claude-code": (homeDir) => new ClaudeCodeAdapter(homeDir),
     codex: (homeDir) => new CodexAdapter(homeDir),
     kiro: (homeDir) => new KiroAdapter(homeDir),
     pi: (homeDir) => new PiAdapter(homeDir),
+    "kimi-code": (homeDir) => new KimiCodeAdapter(homeDir),
 };
 /** Only agents in `canonical.managedAgents` — an agent present on this
  * machine but not managed gets no adapter at all, not a zero-item plan

package/dist/core/canonical.d.ts

@@ -4,7 +4,8 @@
  * workspace scope"). See openspec/changes/trellis-sync-p1/specs/
  * canonical-source-loading/spec.md for the exact contract this implements.
  */
-import type { AgentId, CanonicalSource, McpServerDef } from "./types.js";
+import type { AgentId, CapabilityDelivery, CanonicalSource, McpRoute, McpServerDef } from "./types.js";
+import type { BackupSession } from "../lib/backup.js";
 /**
  * The on-disk shape for one server entry — `static_env`/`env_aliases`
  * (snake_case, like every other multi-word key across `.trellis/*.yaml`)
@@ -27,10 +28,10 @@ export type ServersYamlWriteResult = {
     ok: false;
     error: string;
 };
-export declare function upsertServerYaml(path: string, name: string, def: McpServerDef): ServersYamlWriteResult;
+export declare function upsertServerYaml(path: string, name: string, def: McpServerDef, backup?: BackupSession): ServersYamlWriteResult;
 /** Inverse of `upsertServerYaml` — same preservation guarantee, same
  * refusal posture on a missing/unparseable file. */
-export declare function removeServerYaml(path: string, name: string): ServersYamlWriteResult;
+export declare function removeServerYaml(path: string, name: string, backup?: BackupSession): ServersYamlWriteResult;
 /**
  * `trellis onboard --mcp-mode <value>` (trellis-onboard-mcp-mode) —
  * everything needed to select or clear the top-level `hub`/`gateway`
@@ -56,7 +57,60 @@ export type McpMode = {
  * 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;
+export declare function writeMcpModeYaml(path: string, mode: McpMode, backup?: BackupSession): ServersYamlWriteResult;
+export type McpRoutesWriteResult = ServersYamlWriteResult;
+/** Writes explicit per-agent routes while preserving legacy hub/gateway
+ * shorthand. An empty route map removes the optional key. */
+export declare function writeMcpRoutesYaml(path: string, routes: Partial<Record<AgentId, McpRoute>>, backup?: BackupSession): McpRoutesWriteResult;
+/** Writes per-agent capability delivery preferences into servers.yaml.
+ * Omitted entries continue to use the native default. */
+export declare function writeMcpRuntimeDeliveryYaml(path: string, delivery: Partial<Record<AgentId, CapabilityDelivery>>, backup?: BackupSession): ServersYamlWriteResult;
+export type SecretsPolicyWriteResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * `trellis migrate`'s static-env secret extraction
+ * (trellis-migrate-extract-static-env-secrets design.md D6) — the
+ * missing writer for `secrets.policy.yaml`, mirroring `writeMcpModeYaml`'s
+ * `Document`-based, comment-preserving mechanism. Sets `env_file` only
+ * when it is not already set — an already-configured value is a
+ * deliberate prior choice (design.md D3) and `resolveSecretEnv` treats
+ * `env_file` as the sole source once set, so silently repointing it
+ * would orphan every name already resolving from the old file. Appends
+ * `varName` to `allowed_vars` only if not already present (dedup, same
+ * "already there is a no-op" rule every other Trellis writer follows).
+ */
+export declare function writeSecretsPolicyExtraction(path: string, extraction: {
+    varName: string;
+    envFilePath: string;
+}, backup?: BackupSession): SecretsPolicyWriteResult;
+/**
+ * Ensures one exact line is present in a `.gitignore` file, creating the
+ * file if it doesn't exist yet — idempotent (a no-op if the line is
+ * already there), never disturbing any other line
+ * (trellis-migrate-extract-static-env-secrets design.md D5). Called
+ * lazily, immediately before the first real write to the local secrets
+ * file migrate's static-env extraction produces — never from `trellis
+ * init`'s own bootstrap, so a machine that never extracts a secret never
+ * gains this file at all.
+ */
+export declare function ensureGitignoreEntry(gitignorePath: string, line: string, backup?: BackupSession): void;
+/**
+ * Ensures a shell rc file sources the local secrets env file on every new
+ * shell — one generic pointer block, appended once, idempotent (detected
+ * by its own marker comment, never duplicated). Deliberately never writes
+ * a literal secret value into the rc file: the block only names the path
+ * to the real `NAME=value` file migrate's extraction already writes and
+ * protects — adding a new variable later means editing that one file, the
+ * rc file never needs a second edit (trellis-migrate-extract-static-env-secrets
+ * design.md D10). `set -a`/`set +a` auto-exports the plain dotenv-format
+ * lines `parseDotenv` already expects, so that format never needs an
+ * `export` prefix of its own.
+ */
+export declare function ensureShellEnvSource(rcPath: string, envFilePath: string, backup?: BackupSession): void;
 /**
  * `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

@@ -4,10 +4,10 @@
  * workspace scope"). See openspec/changes/trellis-sync-p1/specs/
  * canonical-source-loading/spec.md for the exact contract this implements.
  */
-import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, join } from "node:path";
-import { isMap, parse as parseYaml, parseDocument } from "yaml";
+import { basename, dirname, join } from "node:path";
+import { isMap, isSeq, parse as parseYaml, parseDocument } from "yaml";
 import { ALL_AGENTS } from "./types.js";
 function fromServerDefYaml(def) {
     const { static_env, env_aliases, ...rest } = def;
@@ -89,8 +89,39 @@ function loadServersYaml(path) {
         knownHostInjected: parsed.known_host_injected ?? [],
         hub: parsed.hub,
         gateway: fromGatewayYaml(parsed.gateway),
+        routes: fromRoutesYaml(parsed.routes),
+        runtime: fromRuntimeYaml(parsed.runtime),
     };
 }
+function fromRuntimeYaml(runtime) {
+    if (!runtime?.delivery)
+        return undefined;
+    const delivery = {};
+    for (const [rawAgent, rawDelivery] of Object.entries(runtime.delivery)) {
+        if (!ALL_AGENTS.includes(rawAgent))
+            continue;
+        if (rawDelivery !== "native" && rawDelivery !== "mcp" && rawDelivery !== "both")
+            continue;
+        delivery[rawAgent] = rawDelivery;
+    }
+    return Object.keys(delivery).length > 0 ? { delivery } : undefined;
+}
+function fromRoutesYaml(routes) {
+    if (!routes)
+        return undefined;
+    const out = {};
+    for (const [rawAgent, rawRoute] of Object.entries(routes)) {
+        if (!ALL_AGENTS.includes(rawAgent))
+            continue;
+        if (!rawRoute?.mode || !["direct", "gateway", "hub"].includes(rawRoute.mode))
+            continue;
+        out[rawAgent] = {
+            mode: rawRoute.mode,
+            ...(rawRoute.servers ? { servers: rawRoute.servers } : {}),
+        };
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
 /**
  * A `gateway:` block with no `enabled` key reads as off, not as on — the
  * only safe default for a field whose whole effect is to stop writing the
@@ -126,12 +157,26 @@ function fromGatewayYaml(gateway) {
  * one-line, local fix — it never touches any sibling entry's own style,
  * so a file someone deliberately kept flow-style elsewhere is untouched.
  */
+/** Handles both a map (`servers: {}`) and a sequence (`allowed_vars: []`)
+ * — `trellis init`'s starter files use flow style for both kinds of
+ * still-empty collection, and inserting into either one via `Document`
+ * methods keeps rendering it as flow otherwise (same real bug this
+ * function was first written to fix, just a second collection type
+ * hitting it — trellis-migrate-extract-static-env-secrets). */
 function forceBlockStyle(node) {
-    if (isMap(node)) {
+    if (isMap(node) || isSeq(node)) {
         node.flow = false;
     }
 }
-export function upsertServerYaml(path, name, def) {
+function persistText(path, content, backup) {
+    if (existsSync(path) && readFileSync(path, "utf-8") === content)
+        return;
+    if (backup)
+        backup.writeFile(path, content);
+    else
+        writeFileSync(path, content);
+}
+export function upsertServerYaml(path, name, def, backup) {
     if (!existsSync(path)) {
         return { ok: false, error: `${path} does not exist — run \`trellis init\` first` };
     }
@@ -145,12 +190,12 @@ export function upsertServerYaml(path, name, def) {
     doc.setIn(["servers", name], toServerDefYaml(def));
     forceBlockStyle(doc.get("servers", true));
     forceBlockStyle(doc.getIn(["servers", name], true));
-    writeFileSync(path, doc.toString());
+    persistText(path, doc.toString(), backup);
     return { ok: true };
 }
 /** Inverse of `upsertServerYaml` — same preservation guarantee, same
  * refusal posture on a missing/unparseable file. */
-export function removeServerYaml(path, name) {
+export function removeServerYaml(path, name, backup) {
     if (!existsSync(path)) {
         return { ok: false, error: `${path} does not exist — run \`trellis init\` first` };
     }
@@ -162,7 +207,7 @@ export function removeServerYaml(path, name) {
         return { ok: false, error: `could not parse ${path}: ${err instanceof Error ? err.message : String(err)}` };
     }
     doc.deleteIn(["servers", name]);
-    writeFileSync(path, doc.toString());
+    persistText(path, doc.toString(), backup);
     return { ok: true };
 }
 /**
@@ -175,7 +220,7 @@ export function removeServerYaml(path, name) {
  * 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) {
+export function writeMcpModeYaml(path, mode, backup) {
     if (!existsSync(path)) {
         return { ok: false, error: `${path} does not exist — run \`trellis init\` first` };
     }
@@ -208,7 +253,56 @@ export function writeMcpModeYaml(path, mode) {
             forceBlockStyle(doc.get("gateway", true));
             break;
     }
-    writeFileSync(path, doc.toString());
+    persistText(path, doc.toString(), backup);
+    return { ok: true };
+}
+/** Writes explicit per-agent routes while preserving legacy hub/gateway
+ * shorthand. An empty route map removes the optional key. */
+export function writeMcpRoutesYaml(path, routes, backup) {
+    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)}` };
+    }
+    const serialized = Object.fromEntries(Object.entries(routes).map(([agent, route]) => [agent, { mode: route.mode, ...(route.servers ? { servers: route.servers } : {}) }]));
+    if (Object.keys(serialized).length === 0) {
+        doc.delete("routes");
+    }
+    else {
+        doc.set("routes", serialized);
+        forceBlockStyle(doc.get("routes", true));
+    }
+    persistText(path, doc.toString(), backup);
+    return { ok: true };
+}
+/** Writes per-agent capability delivery preferences into servers.yaml.
+ * Omitted entries continue to use the native default. */
+export function writeMcpRuntimeDeliveryYaml(path, delivery, backup) {
+    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)}` };
+    }
+    const serialized = Object.fromEntries(Object.entries(delivery).map(([agent, mode]) => [agent, mode]));
+    if (Object.keys(serialized).length === 0) {
+        doc.delete("runtime");
+    }
+    else {
+        doc.setIn(["runtime", "delivery"], serialized);
+        forceBlockStyle(doc.get("runtime", true));
+        forceBlockStyle(doc.getIn(["runtime", "delivery"], true));
+    }
+    persistText(path, doc.toString(), backup);
     return { ok: true };
 }
 function loadSecretsPolicyYaml(path, homeDir) {
@@ -222,8 +316,86 @@ function loadSecretsPolicyYaml(path, homeDir) {
         envFile: parsed.env_file ? parsed.env_file.replace(/^~(?=$|\/)/, homeDir) : undefined,
     };
 }
+/**
+ * `trellis migrate`'s static-env secret extraction
+ * (trellis-migrate-extract-static-env-secrets design.md D6) — the
+ * missing writer for `secrets.policy.yaml`, mirroring `writeMcpModeYaml`'s
+ * `Document`-based, comment-preserving mechanism. Sets `env_file` only
+ * when it is not already set — an already-configured value is a
+ * deliberate prior choice (design.md D3) and `resolveSecretEnv` treats
+ * `env_file` as the sole source once set, so silently repointing it
+ * would orphan every name already resolving from the old file. Appends
+ * `varName` to `allowed_vars` only if not already present (dedup, same
+ * "already there is a no-op" rule every other Trellis writer follows).
+ */
+export function writeSecretsPolicyExtraction(path, extraction, backup) {
+    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)}` };
+    }
+    if (doc.get("env_file") === undefined) {
+        doc.set("env_file", extraction.envFilePath);
+    }
+    // `.get()` returns the raw Seq node for a collection, not a plain
+    // array — `.toJS()` on the whole document is the reliable way to read
+    // a fully-unwrapped value back out before deciding whether to append.
+    const currentAllowedVars = (doc.toJS().allowed_vars ?? []);
+    if (!currentAllowedVars.includes(extraction.varName)) {
+        doc.set("allowed_vars", [...currentAllowedVars, extraction.varName]);
+        forceBlockStyle(doc.get("allowed_vars", true));
+    }
+    persistText(path, doc.toString(), backup);
+    return { ok: true };
+}
+/**
+ * Ensures one exact line is present in a `.gitignore` file, creating the
+ * file if it doesn't exist yet — idempotent (a no-op if the line is
+ * already there), never disturbing any other line
+ * (trellis-migrate-extract-static-env-secrets design.md D5). Called
+ * lazily, immediately before the first real write to the local secrets
+ * file migrate's static-env extraction produces — never from `trellis
+ * init`'s own bootstrap, so a machine that never extracts a secret never
+ * gains this file at all.
+ */
+export function ensureGitignoreEntry(gitignorePath, line, backup) {
+    const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf-8") : "";
+    const lines = existing.split("\n").map((l) => l.trim());
+    if (lines.includes(line))
+        return;
+    const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    persistText(gitignorePath, `${existing}${separator}${line}\n`, backup);
+}
+const SHELL_ENV_SOURCE_MARKER = "# >>> trellis mcp secrets >>>";
+const SHELL_ENV_SOURCE_END_MARKER = "# <<< trellis mcp secrets <<<";
+/**
+ * Ensures a shell rc file sources the local secrets env file on every new
+ * shell — one generic pointer block, appended once, idempotent (detected
+ * by its own marker comment, never duplicated). Deliberately never writes
+ * a literal secret value into the rc file: the block only names the path
+ * to the real `NAME=value` file migrate's extraction already writes and
+ * protects — adding a new variable later means editing that one file, the
+ * rc file never needs a second edit (trellis-migrate-extract-static-env-secrets
+ * design.md D10). `set -a`/`set +a` auto-exports the plain dotenv-format
+ * lines `parseDotenv` already expects, so that format never needs an
+ * `export` prefix of its own.
+ */
+export function ensureShellEnvSource(rcPath, envFilePath, backup) {
+    const existing = existsSync(rcPath) ? readFileSync(rcPath, "utf-8") : "";
+    if (existing.includes(SHELL_ENV_SOURCE_MARKER))
+        return;
+    const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    const block = `${SHELL_ENV_SOURCE_MARKER}\nif [ -f "${envFilePath}" ]; then\n  set -a\n  source "${envFilePath}"\n  set +a\nfi\n${SHELL_ENV_SOURCE_END_MARKER}\n`;
+    mkdirSync(dirname(rcPath), { recursive: true });
+    persistText(rcPath, `${existing}${separator}${block}`, backup);
+}
 /** `undefined` if the name has no entry in scope.yaml's map — "shared with
- * all four agents," the default. A recognized but empty list is left as
+ * all managed agents by default. A recognized but empty list is left as
  * authored (an explicitly agent-less scope), not coerced to "all". */
 /** Missing file and `agents: []` both resolve to `[]` — zero managed
  * agents (D1), never "everyone." An unrecognized id is dropped with a