agent-trellis 0.6.3 → 0.8.0

package/dist/adapters/mcpPlan.js

@@ -17,21 +17,32 @@
  * ever returns create/repair + refuse.
  */
 import { isInScope } from "../core/adapter.js";
+import { capabilityDeliveryForAgent } from "../core/types.js";
 import { codexBearerTokenEnvVar } from "../lib/tomlSection.js";
 import { resolveSecretEnv } from "../lib/secretEnv.js";
 export const HUB_ENTRY_NAME = "trellis-hub";
-export const GATEWAY_ENTRY_NAME = "trellis-gateway";
+export const GATEWAY_ENTRY_NAME = "trellis";
+export const LEGACY_GATEWAY_ENTRY_NAME = "trellis-gateway";
+export const RUNTIME_ENTRY_NAME = "trellis";
+export const LEGACY_RUNTIME_ENTRY_NAME = "trellis-runtime";
 /** The command an agent spawns in gateway mode. Bare `trellis` rather than
  * an absolute path: the entry has to keep working across reinstalls and
  * version bumps, and every agent resolves it through the same PATH the
  * user installed the CLI onto. */
 export const GATEWAY_COMMAND = "trellis";
+export const RUNTIME_COMMAND = "trellis";
+export function isOAuthMcpServer(def) {
+    return def.auth === "oauth";
+}
 /**
  * Gateway mode applies to every managed agent when `agents` is omitted —
  * the expected normal case (design.md D14). An explicit list narrows it,
  * letting some agents stay in direct or hub mode.
  */
 export function isGatewayAgent(agentId, mcp, managedAgents) {
+    const route = mcp.routes?.[agentId];
+    if (route)
+        return route.mode === "gateway";
     const gateway = mcp.gateway;
     if (!gateway?.enabled)
         return false;
@@ -39,6 +50,16 @@ export function isGatewayAgent(agentId, mcp, managedAgents) {
         return gateway.agents.includes(agentId);
     return managedAgents.includes(agentId);
 }
+function routeForAgent(agentId, mcp, managedAgents) {
+    const explicit = mcp.routes?.[agentId];
+    if (explicit)
+        return explicit;
+    if (isGatewayAgent(agentId, mcp, managedAgents))
+        return { mode: "gateway" };
+    if (mcp.hub)
+        return { mode: "hub" };
+    return { mode: "direct" };
+}
 const 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 — see docs/research.md.';
 function collisionMessage(name, agentId) {
     return `refusing to write MCP server "${name}": also appears in known_host_injected.${agentId === "codex" ? CODEX_STDIO_URL_CRASH_NOTE : ""}`;
@@ -71,13 +92,23 @@ const DANGEROUS_LITERAL_PATTERNS = [
  * 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.
+ *
+ * Scanning order is `command, url, args, headers, staticEnv` — a def
+ * matching in more than one field returns whichever is found first, same
+ * as before this function reported a field at all.
  */
 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) {
+    const candidates = [
+        ...(def.command !== undefined ? [{ value: def.command, field: "command" }] : []),
+        ...(def.url !== undefined ? [{ value: def.url, field: "url" }] : []),
+        ...(def.args ?? []).map((value) => ({ value, field: "args" })),
+        ...Object.entries(def.headers ?? {}).map(([key, value]) => ({ value, field: "headers", key })),
+        ...Object.entries(def.staticEnv ?? {}).map(([key, value]) => ({ value, field: "staticEnv", key })),
+    ];
+    for (const { value, field, key } of candidates) {
         for (const { label, pattern } of DANGEROUS_LITERAL_PATTERNS) {
-            if (pattern.test(candidate)) {
-                return label;
+            if (pattern.test(value)) {
+                return { label, field, key };
             }
         }
     }
@@ -106,54 +137,143 @@ function findUnresolvedEnvName(def, policy) {
     return names.find((name) => !resolved[name]);
 }
 export function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
+    const route = routeForAgent(agentId, mcp, managedAgents);
+    const runtimeEnabled = capabilityDeliveryForAgent(agentId, mcp) !== "native";
     // Checked before `hub`: only one entry can be "the" MCP entry for an
     // agent, and gateway is the newer, purpose-built path (design.md D6).
     // `hub` stays available, unchanged, for anyone pointing an agent at an
     // externally-operated endpoint — including a different agent in the
     // same canonical source.
-    if (isGatewayAgent(agentId, mcp, managedAgents)) {
-        if (mcp.knownHostInjected.includes(GATEWAY_ENTRY_NAME)) {
+    if (route.mode === "gateway") {
+        const entryName = runtimeEnabled ? RUNTIME_ENTRY_NAME : GATEWAY_ENTRY_NAME;
+        if (mcp.knownHostInjected.includes(entryName)) {
             return {
                 desired: [],
-                conflicts: [{ name: GATEWAY_ENTRY_NAME, message: collisionMessage(GATEWAY_ENTRY_NAME, agentId), remediation: collisionRemediation(GATEWAY_ENTRY_NAME) }],
+                conflicts: [{ name: entryName, message: collisionMessage(entryName, agentId), remediation: collisionRemediation(entryName) }],
             };
         }
+        const oauth = planDirectServers(agentId, mcp, managedAgents, policy, route, isOAuthMcpServer);
+        // Every ordinary per-server check (enabled, scope, literal secrets,
+        // unresolved env names, Codex's header shape) still runs at gateway
+        // startup. OAuth servers are the deliberate exception: they are written
+        // as direct entries so the gateway never owns their client connection.
         // Every per-server check (enabled, scope, literal secrets, unresolved
         // env names, Codex's header shape) still runs — but at gateway
         // *startup*, inside the subcommand, since no adapter sees an
         // individual server in this mode (design.md D6).
         return {
-            desired: [{ name: GATEWAY_ENTRY_NAME, def: { transport: "stdio", command: GATEWAY_COMMAND, args: ["mcp-gateway", "--agent", agentId] } }],
-            conflicts: [],
+            desired: [{
+                    name: entryName,
+                    def: {
+                        transport: "stdio",
+                        command: runtimeEnabled ? RUNTIME_COMMAND : GATEWAY_COMMAND,
+                        args: [runtimeEnabled ? "mcp-runtime" : "mcp-gateway", "--agent", agentId],
+                    },
+                }, ...oauth.desired],
+            conflicts: oauth.conflicts,
         };
     }
-    if (mcp.hub) {
+    if (route.mode === "hub") {
+        if (!mcp.hub) {
+            return {
+                desired: [],
+                conflicts: [{
+                        name: HUB_ENTRY_NAME,
+                        message: `cannot resolve hub route "${agentId}": canonical mcp.hub.url is not configured`,
+                        remediation: `configure mcp.hub.url or choose direct/gateway mode for ${agentId}`,
+                    }],
+            };
+        }
         if (mcp.knownHostInjected.includes(HUB_ENTRY_NAME)) {
             return {
                 desired: [],
                 conflicts: [{ name: HUB_ENTRY_NAME, message: collisionMessage(HUB_ENTRY_NAME, agentId), remediation: collisionRemediation(HUB_ENTRY_NAME) }],
             };
         }
-        return { desired: [{ name: HUB_ENTRY_NAME, def: { transport: "http", url: mcp.hub.url } }], conflicts: [] };
+        if (route.servers) {
+            return {
+                desired: [],
+                conflicts: [{
+                        name: HUB_ENTRY_NAME,
+                        message: `cannot restrict external hub route "${agentId}" to individual MCP servers: the hub owns its upstream set`,
+                        remediation: `remove the servers list from the ${agentId} hub route, or use direct/gateway mode for per-server selection`,
+                    }],
+            };
+        }
+        const desired = [{ name: HUB_ENTRY_NAME, def: { transport: "http", url: mcp.hub.url } }];
+        if (runtimeEnabled) {
+            if (mcp.knownHostInjected.includes(RUNTIME_ENTRY_NAME)) {
+                return {
+                    desired: [],
+                    conflicts: [{ name: RUNTIME_ENTRY_NAME, message: collisionMessage(RUNTIME_ENTRY_NAME, agentId), remediation: collisionRemediation(RUNTIME_ENTRY_NAME) }],
+                };
+            }
+            // The runtime provides Trellis-owned capabilities here. The external
+            // hub remains the upstream MCP edge; the runtime does not connect to
+            // canonical upstreams a second time for this route.
+            desired.push({
+                name: RUNTIME_ENTRY_NAME,
+                def: { transport: "stdio", command: RUNTIME_COMMAND, args: ["mcp-runtime", "--agent", agentId] },
+            });
+        }
+        return { desired, conflicts: [] };
     }
+    if (runtimeEnabled) {
+        if (mcp.knownHostInjected.includes(RUNTIME_ENTRY_NAME)) {
+            return {
+                desired: [],
+                conflicts: [{ name: RUNTIME_ENTRY_NAME, message: collisionMessage(RUNTIME_ENTRY_NAME, agentId), remediation: collisionRemediation(RUNTIME_ENTRY_NAME) }],
+            };
+        }
+        // Runtime mode owns the agent-facing MCP edge. It resolves the same
+        // direct/gateway-compatible upstream route at startup, so native
+        // per-server entries are not duplicated here.
+        return {
+            desired: [{
+                    name: RUNTIME_ENTRY_NAME,
+                    def: { transport: "stdio", command: RUNTIME_COMMAND, args: ["mcp-runtime", "--agent", agentId] },
+                }],
+            conflicts: [],
+        };
+    }
+    return planDirectServers(agentId, mcp, managedAgents, policy, route);
+}
+function planDirectServers(agentId, mcp, managedAgents, policy, route, filter) {
     const desired = [];
     const conflicts = [];
     for (const [name, def] of Object.entries(mcp.servers)) {
         if (def.enabled === false) {
             continue;
         }
+        if (filter && !filter(def))
+            continue;
         if (!isInScope(agentId, def.agents, managedAgents)) {
             continue;
         }
+        if (route.servers && !route.servers.includes(name)) {
+            continue;
+        }
         if (mcp.knownHostInjected.includes(name)) {
             conflicts.push({ name, message: collisionMessage(name, agentId), remediation: collisionRemediation(name) });
             continue;
         }
-        const secretLabel = findLiteralSecret(def);
-        if (secretLabel) {
+        // Only `staticEnv` is refused here: it's the one shape a real
+        // credential is meant to leave via `env`/`env_vars`, proven to
+        // resolve back to a real value for every consumer (pi-bridge,
+        // claude-code, codex, kiro) — a literal surviving there means
+        // something bypassed `migrate`'s own extraction (a hand-edited
+        // servers.yaml, most likely) and must still be refused outright. A
+        // match in `command`/`url`/`args`/`headers` is accepted and written
+        // as ordinary literal config instead (trellis-migrate-extract-static-env-secrets
+        // design.md D11) — none of those fields has a `${VAR}` resolution
+        // mechanism proven across every consumer, so a fake reference there
+        // would be strictly worse than the literal it replaced; `secrets
+        // audit` keeps flagging canonical itself so this isn't silent.
+        const secretMatch = findLiteralSecret(def);
+        if (secretMatch?.field === "staticEnv") {
             conflicts.push({
                 name,
-                message: `refusing to write MCP server "${name}": a value matches a known-dangerous literal pattern (${secretLabel}) — configs must hold variable NAMES only, never real values (docs/research.md "Secrets")`,
+                message: `refusing to write MCP server "${name}": a value matches a known-dangerous literal pattern (${secretMatch.label}) — configs must hold variable NAMES only, never real values (docs/research.md "Secrets")`,
                 remediation: `replace the literal value in servers.yaml with a \`\${VAR_NAME}\` reference and put the real value wherever secrets.policy.yaml resolves it from`,
             });
             continue;

package/dist/adapters/pi.js

@@ -9,13 +9,31 @@
  * mechanism from every other agent's config-generation adapter, but the
  * same symlink create/repair/remove machinery as skills/instructions.
  */
-import { dirname, join } from "node:path";
+import { dirname, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
+import { readFileSync } from "node:fs";
 import { isInScope } from "../core/adapter.js";
+import { usesNativeCapabilityDelivery } from "../core/types.js";
 import * as piProbe from "../probes/pi.js";
 import { applySymlinkPlan, planSymlinks } from "./symlinkPlan.js";
 const BRIDGE_SYMLINK_NAME = "trellis-mcp-bridge.js";
+/**
+ * A source-checkout bridge can survive a switch to the packaged CLI. Adopt it
+ * only when it has the Trellis bridge artifact shape and is byte-identical
+ * to the bundle this installation would write. This is intentionally not a
+ * general symlink ownership rule.
+ */
+function isEquivalentTrellisBridge(existingTarget, desiredTarget) {
+    if (!existingTarget.endsWith(`${sep}${join("dist", "pi-bridge", "bundle.js")}`))
+        return false;
+    try {
+        return readFileSync(existingTarget).equals(readFileSync(desiredTarget));
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * The bundled bridge file's location — always `<repo-root>/dist/pi-bridge/
  * bundle.js`, never `~/.trellis/` (it's Trellis's own packaged code, not a
@@ -56,7 +74,7 @@ export class PiAdapter {
         const canonicalRoot = dirname(canonical.instructionsFile);
         const agentDir = join(this.homeDir, ".pi", "agent");
         const desiredSkills = canonical.skills
-            .filter((skill) => isInScope(this.id, skill.scope, canonical.managedAgents))
+            .filter((skill) => usesNativeCapabilityDelivery(this.id, canonical.mcp) && isInScope(this.id, skill.scope, canonical.managedAgents))
             .map((skill) => ({ name: skill.name, target: skill.dir }));
         const skillItems = planSymlinks({
             rootDir: join(agentDir, "skills"),
@@ -79,6 +97,7 @@ export class PiAdapter {
             // (design.md D2), same role `canonicalRoot` plays for skills.
             canonicalRoot: dirname(bridgeFile),
             kind: "extension",
+            adoptExistingSymlink: isEquivalentTrellisBridge,
         });
         return [...skillItems, ...instructionsItems, ...extensionItems];
     }
@@ -91,7 +110,7 @@ export class PiAdapter {
             return { ok: false, mismatches: ["pi is not present on this machine"] };
         }
         const mismatches = [];
-        const desiredNames = new Set(canonical.skills.filter((s) => isInScope(this.id, s.scope, canonical.managedAgents)).map((s) => s.name));
+        const desiredNames = new Set(canonical.skills.filter((s) => usesNativeCapabilityDelivery(this.id, canonical.mcp) && isInScope(this.id, s.scope, canonical.managedAgents)).map((s) => s.name));
         const actualSkills = new Set(snapshot.skillRoots.flatMap((root) => root.skills).map((s) => s.name));
         for (const name of desiredNames) {
             if (!actualSkills.has(name)) {

package/dist/adapters/symlinkPlan.d.ts

@@ -12,6 +12,12 @@ export interface DesiredSymlink {
     /** Absolute path the symlink should point at (inside `canonicalRoot`). */
     target: string;
 }
+/**
+ * A narrowly-scoped escape hatch for artifacts that Trellis can identify
+ * across installation roots. The default ownership rule remains path-based;
+ * callers must opt in explicitly for a particular artifact kind.
+ */
+export type ExistingSymlinkAdoption = (existingTarget: string, desiredTarget: string) => boolean;
 /**
  * `rootDir` is the directory entries are named directly under (e.g.
  * `~/.claude/skills`, or the instructions file's own parent directory when
@@ -28,6 +34,7 @@ export declare function planSymlinks(opts: {
     desired: DesiredSymlink[];
     canonicalRoot: string;
     kind: "skill" | "instructions" | "extension";
+    adoptExistingSymlink?: ExistingSymlinkAdoption;
 }): AdapterPlanItem[];
 /** Executes a `planSymlinks` result through the run's backup session
  * (trellis-backup-rollback) — every create/repair/remove is recorded

package/dist/adapters/symlinkPlan.js

@@ -4,9 +4,9 @@
  * trellis-sync-p1/specs/skill-instructions-sync/spec.md) — built once,
  * reused by every adapter rather than reimplemented per agent.
  */
-import { existsSync, lstatSync, readdirSync, readlinkSync } from "node:fs";
+import { lstatSync, readdirSync, readlinkSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
-import { join, resolve, sep } from "node:path";
+import { dirname, join, resolve, sep } from "node:path";
 import { isSymlinkTo } from "../lib/fsIdentity.js";
 import { currentLinkTarget } from "../lib/backup.js";
 function isUnderRoot(path, root) {
@@ -29,7 +29,7 @@ function isUnderRoot(path, root) {
  * case this removal path exists to catch.
  */
 export function planSymlinks(opts) {
-    const { rootDir, desired, kind } = opts;
+    const { rootDir, desired, kind, adoptExistingSymlink } = opts;
     const items = [];
     const desiredNames = new Set(desired.map((d) => d.name));
     const canonicalRootResolved = resolve(opts.canonicalRoot);
@@ -38,8 +38,15 @@ export function planSymlinks(opts) {
         if (isSymlinkTo(path, target)) {
             continue; // already correct — no-op
         }
-        if (existsSync(path)) {
-            const isSymlink = lstatSync(path).isSymbolicLink();
+        // lstat sees dangling links too; existsSync would treat them as absent
+        // and bypass the foreign-link protection below.
+        const existing = lstatSync(path, { throwIfNoEntry: false });
+        if (existing) {
+            const isSymlink = existing.isSymbolicLink();
+            const rawExistingTarget = isSymlink ? readlinkSync(path) : undefined;
+            const resolvedExistingTarget = rawExistingTarget === undefined
+                ? undefined
+                : resolve(dirname(path), rawExistingTarget);
             // A symlink whose stored target resolves outside canonicalRoot is
             // owned by something else (e.g. a user's own dotfile-management
             // setup) — repairing it as if it were a stale Trellis entry would
@@ -47,14 +54,16 @@ export function planSymlinks(opts) {
             // symlink Trellis itself left pointing at a since-removed canonical
             // entry is broken by construction and must still be treated as
             // ours to repair, not thrown out to a conflict by a realpath error.
-            const isForeign = isSymlink && !isUnderRoot(readlinkSync(path), canonicalRootResolved);
+            const isForeign = resolvedExistingTarget !== undefined
+                && !isUnderRoot(resolvedExistingTarget, canonicalRootResolved)
+                && adoptExistingSymlink?.(resolvedExistingTarget, target) !== true;
             if (!isSymlink || isForeign) {
                 items.push({
                     action: "conflict",
                     kind,
                     target: path,
                     description: isForeign
-                        ? `${path} exists as a symlink to ${readlinkSync(path)}, not owned by Trellis — left untouched`
+                        ? `${path} exists as a symlink to ${rawExistingTarget}, not owned by Trellis — left untouched`
                         : `${path} exists and is not a Trellis-managed symlink — left untouched`,
                     remediation: isForeign
                         ? `remove the existing symlink at ${path} if you want Trellis to manage it, then re-run sync — otherwise leave it, Trellis will not touch it`

package/dist/cli.js

@@ -9,22 +9,33 @@ import { runInit } from "./commands/init.js";
 import { runMigrate } from "./commands/migrate.js";
 import { runOnboard } from "./commands/onboard.js";
 import { runSync } from "./commands/sync.js";
-import { runMcpSync, runMcpList, runMcpAdd, runMcpRemove, parseMcpAddArgs } from "./commands/mcp.js";
-import { parseMcpGatewayArgs, runMcpGateway } from "./commands/mcpGateway.js";
+import { runMcpSync, runMcpList, runMcpAdd, runMcpRemove, runMcpSetAuth, parseMcpAddArgs } from "./commands/mcp.js";
+import { runMcpImport } from "./commands/mcpImport.js";
+import { parseMcpGatewayArgs, runMcpGateway, runMcpRuntime } from "./commands/mcpGateway.js";
 import { runMcpAuth } from "./commands/mcpAuth.js";
 import { runSecretsAudit } from "./commands/secretsAudit.js";
 import { runRollback } from "./commands/rollback.js";
-import { runSkillList, runSkillAdd, runSkillRemove } from "./commands/skill.js";
+import { runSkillList, runSkillAdd, runSkillRemove, runSkillUpdateBuiltin } from "./commands/skill.js";
 import { runMemoryExtraction, runMemorySync } from "./commands/memory.js";
+import { parseManageArgs, runManage } from "./commands/manage.js";
+import { runKimi } from "./commands/kimi.js";
+import { TRELLIS_VERSION } from "./lib/cliMetadata.js";
 import { parseSyncArgs } from "./lib/syncArgs.js";
-const KNOWN_COMMANDS = ["onboard", "init", "migrate", "doctor", "sync", "mcp", "mcp-gateway", "skill", "memory", "secrets", "rollback"];
+const KNOWN_COMMANDS = ["onboard", "init", "migrate", "doctor", "sync", "mcp", "mcp-gateway", "mcp-runtime", "skill", "memory", "manage", "kimi", "secrets", "rollback"];
 function printUsage() {
     console.log(`trellis - a single source of capability for every coding agent
 
 Usage:
   trellis <command>
+  trellis --version
+  trellis --help
+
+Options:
+  -v, --version    print the installed Trellis version
+  -h, --help       show this help
 
 Commands:
+  help      Show this help
   onboard   Guided flow: init -> detect agents -> pick a migration source ->
             pick which agents to manage -> migrate -> sync -> mcp sync ->
             secrets audit, in one command. Source (read from) and managed
@@ -39,15 +50,21 @@ Commands:
                                     (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
+                                    direct = Agent 分别直连；gateway =
+                                    Trellis 本机统一托管（推荐）；hub =
+                                    连接已有的外部 MCP Hub
+              --hub-url <url>       required with --mcp-mode hub; Trellis
+                                    does not deploy an external 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
+              --memory-migrate <on|off>
+                                    import supported native Agent memory into
+                                    canonical; omit to leave it untouched
+              --selection <file>   item-level YAML/JSON selection for skills,
+                                    MCP servers, memories, and per-agent routes
               --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
@@ -55,12 +72,13 @@ Commands:
               missing) and prints which agents are present
               --json    machine-readable output, no report text
   migrate --from <agent>
-            Import an existing agent's real skills/instructions/MCP
+            Import an existing agent's real skills/instructions/MCP/memory
             servers into canonical source (claude-code | codex | kiro |
             pi — pi has no static MCP config, mcp migrate-in is a no-op
             for it). Never overwrites differing content — reports a
             conflict instead.
-              --only skills|instructions|mcp   restrict to one category
+            --only skills|instructions|mcp|memory
+                                    restrict to one category
               --dry-run    preview the plan, write nothing
               --json       machine-readable output, no report text
   doctor    Scan Claude Code / Codex / Kiro / pi for drift
@@ -83,12 +101,22 @@ Commands:
               --json    machine-readable output, no report text
   mcp add <name> --transport stdio|http|sse ...
             Add a canonical MCP server (refuses on an existing name,
-              no overwrite): --command <cmd> [--args a,b] (stdio) or
-              --url <url> (http/sse); [--headers k=v,...]
-              [--env NAME,...] [--static-env k=v,...] [--agents id,...]
-              [--enabled true|false]
-              --dry-run    preview the plan, write nothing
-              --json       machine-readable output, no report text
+            no overwrite): --command <cmd> [--args a,b] (stdio) or
+            --url <url> (http/sse); [--headers k=v,...]
+            [--auth oauth] [--env NAME,...] [--static-env k=v,...] [--agents id,...]
+            [--enabled true|false]
+            --dry-run    preview the plan, write nothing
+            --json       machine-readable output, no report text
+  mcp import <json-file>
+            Import a standard mcpServers JSON export without changing the
+            source; extracts credential env values into the ignored local
+            secret file, de-duplicates, and reports conflicts
+            --dry-run    preview without writing
+            --json       machine-readable output, no report text
+  mcp set <name> --auth oauth|none
+            Set or clear explicit OAuth classification; canonical only
+            --dry-run    preview the plan, write nothing
+            --json       machine-readable output, no report text
   mcp auth <server-name>
             Authorize a remote (http/sse) MCP server that uses OAuth —
               opens a browser once, stores the result 0600 under
@@ -97,6 +125,10 @@ Commands:
               refreshes silently on its own and never prompts.
               --force   re-authorize even if the stored token is valid
               --json    machine-readable output, no report text
+  mcp-runtime --agent <agent>
+            Internal MCP edge exposing Trellis providers and selected
+            upstream capabilities; existing mcp-gateway configs remain valid
+            as a compatibility alias
   mcp remove <name>
             Remove a canonical MCP server (canonical-side only — does
               not touch any agent's already-synced native config)
@@ -111,6 +143,11 @@ Commands:
               --dry-run    preview the plan, write nothing
               --json       machine-readable output, no report text
   skill remove <name>
+  skill update-builtin
+            Refresh the package-owned trellis-runtime Skill in canonical
+            source; existing native symlinks see the update
+            --dry-run    preview without writing
+            --json       machine-readable output, no report text
             Remove a canonical skill (the next sync auto-removes the
               now-stale symlink on every managed agent)
               --dry-run    preview the plan, write nothing
@@ -132,6 +169,20 @@ Commands:
               round-trip byte-for-byte back through memory sync.
               --dry-run    preview the plan, write nothing
               --json       machine-readable output, no report text
+  manage list
+            Show the canonical managed-agent write boundary.
+  manage set <ids|none>
+  manage add <ids>
+  manage remove <ids>
+            Explicitly replace, extend, or narrow the managed set. Removing
+              an agent preserves its existing native state; future Trellis
+              writes stop reaching it. Mutations are backup/rollback-enabled.
+              --dry-run    preview current -> desired, write nothing
+              --json       machine-readable output
+  kimi [args...]
+            Launch Kimi Code. When kimi-code Runtime delivery is \`mcp\`,
+            starts Kimi with an empty --skills-dir so Skills come from
+            trellis-runtime instead of native discovery.
   secrets audit
             Scan each present agent's real MCP config for leaked
             credentials and unexpected env var names
@@ -148,18 +199,38 @@ Commands:
 
 See docs/roadmap.md for what's built vs. planned.`);
 }
+function printVersion() {
+    console.log(TRELLIS_VERSION);
+}
 async function main(argv) {
     const [command, ...rest] = argv;
     if (!command || command === "--help" || command === "-h") {
         printUsage();
         return;
     }
+    if (command === "--version" || command === "-v") {
+        printVersion();
+        return;
+    }
+    if (command === "help") {
+        printUsage();
+        return;
+    }
     if (!KNOWN_COMMANDS.includes(command)) {
         console.error(`Unknown command: ${command}\n`);
         printUsage();
         process.exitCode = 1;
         return;
     }
+    // `--help`/`-h` anywhere in a subcommand's own args short-circuits before
+    // any parsing or real action — a typo'd or exploratory flag (e.g. `mcp
+    // sync --help`) must never fall through to actually running the command
+    // it was asking about (real incident: `--help` isn't a flag any branch
+    // recognizes, so it silently ran a real, non-dry-run `mcp sync`).
+    if (command !== "kimi" && (rest.includes("--help") || rest.includes("-h"))) {
+        printUsage();
+        return;
+    }
     if (command === "onboard") {
         const agentIndex = rest.indexOf("--agent");
         const agent = agentIndex >= 0 ? rest[agentIndex + 1] : undefined;
@@ -173,6 +244,10 @@ async function main(argv) {
         const gatewayAgents = gatewayAgentsIndex >= 0 ? rest[gatewayAgentsIndex + 1] : undefined;
         const memoryIndex = rest.indexOf("--memory");
         const memory = memoryIndex >= 0 ? rest[memoryIndex + 1] : undefined;
+        const memoryMigrateIndex = rest.indexOf("--memory-migrate");
+        const memoryMigrate = memoryMigrateIndex >= 0 ? rest[memoryMigrateIndex + 1] : undefined;
+        const selectionIndex = rest.indexOf("--selection");
+        const selectionFile = selectionIndex >= 0 ? rest[selectionIndex + 1] : undefined;
         const { exitCode } = await runOnboard({
             agent,
             manage,
@@ -180,6 +255,8 @@ async function main(argv) {
             hubUrl,
             gatewayAgents,
             memory,
+            memoryMigrate,
+            selectionFile,
             dryRun: rest.includes("--dry-run"),
             json: rest.includes("--json"),
         });
@@ -208,14 +285,16 @@ async function main(argv) {
     // Spawned by an agent, never typed by a person: stdout is the MCP
     // protocol stream for the rest of this process's life, so nothing here
     // may print to it (trellis-mcp-gateway-hosting design.md D2).
-    if (command === "mcp-gateway") {
+    if (command === "mcp-gateway" || command === "mcp-runtime") {
         const parsed = parseMcpGatewayArgs(rest);
         if ("error" in parsed) {
             console.error(parsed.error);
             process.exitCode = 1;
             return;
         }
-        const { exitCode } = await runMcpGateway({ agentId: parsed.agentId });
+        const { exitCode } = command === "mcp-runtime"
+            ? await runMcpRuntime({ agentId: parsed.agentId })
+            : await runMcpGateway({ agentId: parsed.agentId });
         process.exitCode = exitCode;
         return;
     }
@@ -249,6 +328,18 @@ async function main(argv) {
             process.exitCode = runMcpAdd(name, parseMcpAddArgs(mcpRest), { json, dryRun }).exitCode;
             return;
         }
+        if (subcommand === "import") {
+            const [file] = mcpRest;
+            process.exitCode = runMcpImport(file, { json, dryRun }).exitCode;
+            return;
+        }
+        if (subcommand === "set") {
+            const [name] = mcpRest;
+            const authIndex = mcpRest.indexOf("--auth");
+            const auth = authIndex >= 0 ? mcpRest[authIndex + 1] : undefined;
+            process.exitCode = runMcpSetAuth(name, auth, { json, dryRun }).exitCode;
+            return;
+        }
         if (subcommand === "remove") {
             const [name] = mcpRest;
             if (!name) {
@@ -270,7 +361,7 @@ async function main(argv) {
             process.exitCode = exitCode;
             return;
         }
-        console.error(`Unknown mcp subcommand: ${subcommand ?? "(none)"}\nUsage: trellis mcp sync|list|add <name>|remove <name>|auth <name>\n`);
+        console.error(`Unknown mcp subcommand: ${subcommand ?? "(none)"}\nUsage: trellis mcp sync|list|add <name>|set <name>|remove <name>|auth <name>\n`);
         process.exitCode = 1;
         return;
     }
@@ -304,7 +395,11 @@ async function main(argv) {
             process.exitCode = runSkillRemove(name, { json, dryRun }).exitCode;
             return;
         }
-        console.error(`Unknown skill subcommand: ${subcommand ?? "(none)"}\nUsage: trellis skill list|add <name> --from <path>|remove <name>\n`);
+        if (subcommand === "update-builtin") {
+            process.exitCode = runSkillUpdateBuiltin({ json, dryRun }).exitCode;
+            return;
+        }
+        console.error(`Unknown skill subcommand: ${subcommand ?? "(none)"}\nUsage: trellis skill list|add <name> --from <path>|remove <name>|update-builtin\n`);
         process.exitCode = 1;
         return;
     }
@@ -324,6 +419,20 @@ async function main(argv) {
         process.exitCode = 1;
         return;
     }
+    if (command === "manage") {
+        const parsed = parseManageArgs(rest);
+        if ("error" in parsed) {
+            console.error(`${parsed.error}\nUsage: trellis manage list|set <ids|none>|add <ids>|remove <ids> [--dry-run] [--json]\n`);
+            process.exitCode = 1;
+            return;
+        }
+        process.exitCode = runManage(parsed).exitCode;
+        return;
+    }
+    if (command === "kimi") {
+        process.exitCode = (await runKimi(rest)).exitCode;
+        return;
+    }
     if (command === "secrets") {
         const [subcommand] = rest;
         if (subcommand !== "audit") {