agent-trellis 0.7.0 → 0.8.2

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 { runMemoryExtraction, runMemorySync } from "./commands/memory.js";
+import { runSkillList, runSkillAdd, runSkillRemove, runSkillUpdateBuiltin } from "./commands/skill.js";
+import { collectMemoryList, 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,9 +125,14 @@ 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)
+            Remove a canonical MCP server, then run the same sync as
+            mcp sync so every managed agent's Trellis-owned entry for
+            it is removed too
               --dry-run    preview the plan, write nothing
               --json       machine-readable output, no report text
   skill list
@@ -111,6 +144,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 +170,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,12 +200,23 @@ 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();
@@ -165,7 +228,7 @@ async function main(argv) {
     // 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 (rest.includes("--help") || rest.includes("-h")) {
+    if (command !== "kimi" && (rest.includes("--help") || rest.includes("-h"))) {
         printUsage();
         return;
     }
@@ -182,6 +245,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,
@@ -189,6 +256,8 @@ async function main(argv) {
             hubUrl,
             gatewayAgents,
             memory,
+            memoryMigrate,
+            selectionFile,
             dryRun: rest.includes("--dry-run"),
             json: rest.includes("--json"),
         });
@@ -217,14 +286,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;
     }
@@ -255,7 +326,19 @@ async function main(argv) {
         }
         if (subcommand === "add") {
             const [name] = mcpRest;
-            process.exitCode = runMcpAdd(name, parseMcpAddArgs(mcpRest), { json, dryRun }).exitCode;
+            process.exitCode = (await runMcpAdd(name, parseMcpAddArgs(mcpRest), { json, dryRun })).exitCode;
+            return;
+        }
+        if (subcommand === "import") {
+            const [file] = mcpRest;
+            process.exitCode = (await 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") {
@@ -265,7 +348,7 @@ async function main(argv) {
                 process.exitCode = 1;
                 return;
             }
-            process.exitCode = runMcpRemove(name, { json, dryRun }).exitCode;
+            process.exitCode = (await runMcpRemove(name, { json, dryRun })).exitCode;
             return;
         }
         if (subcommand === "auth") {
@@ -279,7 +362,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;
     }
@@ -300,7 +383,7 @@ async function main(argv) {
                 process.exitCode = 1;
                 return;
             }
-            process.exitCode = runSkillAdd(name, from, { json, dryRun }).exitCode;
+            process.exitCode = (await runSkillAdd(name, from, { json, dryRun })).exitCode;
             return;
         }
         if (subcommand === "remove") {
@@ -310,10 +393,14 @@ async function main(argv) {
                 process.exitCode = 1;
                 return;
             }
-            process.exitCode = runSkillRemove(name, { json, dryRun }).exitCode;
+            process.exitCode = (await runSkillRemove(name, { json, dryRun })).exitCode;
+            return;
+        }
+        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>\n`);
+        console.error(`Unknown skill subcommand: ${subcommand ?? "(none)"}\nUsage: trellis skill list|add <name> --from <path>|remove <name>|update-builtin\n`);
         process.exitCode = 1;
         return;
     }
@@ -321,6 +408,21 @@ async function main(argv) {
         const [subcommand, ...memoryRest] = rest;
         const json = memoryRest.includes("--json");
         const dryRun = memoryRest.includes("--dry-run");
+        if (subcommand === "list") {
+            const entries = collectMemoryList();
+            if (json) {
+                console.log(JSON.stringify(entries, null, 2));
+            }
+            else if (entries.length === 0) {
+                console.log("No memories in canonical source yet.");
+            }
+            else {
+                for (const { name, scope } of entries) {
+                    console.log(`${name} — ${scope.length > 0 ? scope.join(", ") : "(no managed agent reaches it)"}`);
+                }
+            }
+            return;
+        }
         if (subcommand === "sync") {
             process.exitCode = runMemorySync({ json, dryRun }).exitCode;
             return;
@@ -329,10 +431,24 @@ async function main(argv) {
             process.exitCode = runMemoryExtraction({ json, dryRun }).exitCode;
             return;
         }
-        console.error(`Unknown memory subcommand: ${subcommand ?? "(none)"}\nUsage: trellis memory sync|extract\n`);
+        console.error(`Unknown memory subcommand: ${subcommand ?? "(none)"}\nUsage: trellis memory list|sync|extract\n`);
         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") {

package/dist/commands/doctor.d.ts

@@ -1,9 +1,10 @@
 /**
  * `trellis doctor` — read-only cross-agent scan. No `.trellis/` canonical
- * source required (docs/roadmap.md): this compares the four agents' own
+ * source required (docs/roadmap.md): this compares the five agents' own
  * current state against each other, the same manual process used
  * throughout docs/research.md's investigation, now formalized.
  */
+import { loadCanonicalSource } from "../core/canonical.js";
 import type { AgentId, AgentSnapshot } from "../core/types.js";
 /**
  * Interim default until P1 wires this from `.trellis/mcp/servers.yaml`'s
@@ -13,7 +14,7 @@ import type { AgentId, AgentSnapshot } from "../core/types.js";
  * machine.
  */
 export declare const DEFAULT_KNOWN_HOST_INJECTED: readonly string[];
-export type FindingKind = "probe-failed" | "duplication" | "collision" | "drift" | "case-mismatch" | "parse-diagnostic" | "mcp-unreachable";
+export type FindingKind = "probe-failed" | "duplication" | "collision" | "drift" | "case-mismatch" | "parse-diagnostic" | "runtime-drift" | "mcp-unreachable";
 export interface Finding {
     kind: FindingKind;
     /** Omitted for a finding that names more than one agent (drift). */
@@ -92,6 +93,10 @@ export declare function detectCrossAgentDrift(snapshots: AgentSnapshot[]): Findi
 export declare function detectCaseMismatches(snapshots: AgentSnapshot[]): Finding[];
 export declare function detectParseDiagnostics(snapshots: AgentSnapshot[]): Finding[];
 export declare function detectMcpUnreachable(snapshots: AgentSnapshot[]): Finding[];
+/** Compares runtime entries against the same canonical MCP plan that sync
+ * uses. Only missing Trellis-owned runtime edges are reported; extra
+ * user-authored MCP entries remain outside doctor ownership. */
+export declare function detectRuntimeDrift(snapshots: AgentSnapshot[], canonical: Pick<ReturnType<typeof loadCanonicalSource>, "mcp" | "managedAgents" | "secretsPolicy">): Finding[];
 /** Exported so `trellis onboard` can reuse it verbatim for its own final
  * stage (trellis-onboard-closed-loop) rather than a second copy of this
  * formatting. */

package/dist/commands/doctor.js

@@ -1,6 +1,6 @@
 /**
  * `trellis doctor` — read-only cross-agent scan. No `.trellis/` canonical
- * source required (docs/roadmap.md): this compares the four agents' own
+ * source required (docs/roadmap.md): this compares the five agents' own
  * current state against each other, the same manual process used
  * throughout docs/research.md's investigation, now formalized.
  */
@@ -9,7 +9,10 @@ import * as claudeCodeProbe from "../probes/claude-code.js";
 import * as codexProbe from "../probes/codex.js";
 import * as kiroProbe from "../probes/kiro.js";
 import * as piProbe from "../probes/pi.js";
+import * as kimiCodeProbe from "../probes/kimi-code.js";
+import * as zcodeProbe from "../probes/zcode.js";
 import { loadCanonicalSource } from "../core/canonical.js";
+import { GATEWAY_ENTRY_NAME, RUNTIME_ENTRY_NAME, resolveMcpPlan } from "../adapters/mcpPlan.js";
 import { ALL_AGENTS } from "../core/types.js";
 /**
  * Interim default until P1 wires this from `.trellis/mcp/servers.yaml`'s
@@ -32,6 +35,7 @@ const EXIT_NONZERO_KINDS = new Set([
     "drift",
     "case-mismatch",
     "parse-diagnostic",
+    "runtime-drift",
 ]);
 /** Exported so tests can assert on this resolution directly, without
  * routing through real per-agent probes `runDoctor` also runs. */
@@ -72,6 +76,8 @@ export async function collectDoctorReport(homeDir = homedir(), knownHostInjected
         { agent: "codex", run: () => codexProbe.probe(homeDir, { probeMcp }) },
         { agent: "kiro", run: () => kiroProbe.probe(homeDir, { probeMcp }) },
         { agent: "pi", run: () => piProbe.probe(homeDir) },
+        { agent: "kimi-code", run: () => kimiCodeProbe.probe(homeDir, { probeMcp }) },
+        { agent: "zcode", run: () => zcodeProbe.probe(homeDir, { probeMcp }) },
     ];
     // One agent erroring must not blank the other three's results.
     const settled = await Promise.allSettled(probeList.map((p) => p.run()));
@@ -89,7 +95,15 @@ export async function collectDoctorReport(homeDir = homedir(), knownHostInjected
             });
         }
     });
-    findings.push(...detectDuplication(snapshots), ...detectCollisions(snapshots, knownHostInjected), ...detectCrossAgentDrift(snapshots), ...detectCaseMismatches(snapshots), ...detectParseDiagnostics(snapshots), ...detectMcpUnreachable(snapshots));
+    let canonical;
+    try {
+        canonical = loadCanonicalSource(homeDir);
+    }
+    catch {
+        // Doctor remains useful as a standalone cross-agent scanner when
+        // canonical has not been initialized yet.
+    }
+    findings.push(...detectDuplication(snapshots), ...detectCollisions(snapshots, knownHostInjected), ...detectCrossAgentDrift(snapshots), ...detectCaseMismatches(snapshots), ...detectParseDiagnostics(snapshots), ...(canonical ? detectRuntimeDrift(snapshots, canonical) : []), ...detectMcpUnreachable(snapshots));
     return { snapshots, findings };
 }
 /**
@@ -233,6 +247,30 @@ export function detectMcpUnreachable(snapshots) {
     }
     return findings;
 }
+/** Compares runtime entries against the same canonical MCP plan that sync
+ * uses. Only missing Trellis-owned runtime edges are reported; extra
+ * user-authored MCP entries remain outside doctor ownership. */
+export function detectRuntimeDrift(snapshots, canonical) {
+    const findings = [];
+    for (const snap of snapshots) {
+        if (!snap.present || !canonical.managedAgents.includes(snap.agent) || snap.agent === "pi")
+            continue;
+        const expected = resolveMcpPlan(snap.agent, canonical.mcp, canonical.managedAgents, canonical.secretsPolicy).desired
+            .map((entry) => entry.name)
+            .filter((name) => name === RUNTIME_ENTRY_NAME || name === GATEWAY_ENTRY_NAME);
+        const actual = new Set(snap.mcpServers.map((server) => server.name));
+        for (const name of expected) {
+            if (!actual.has(name)) {
+                findings.push({
+                    kind: "runtime-drift",
+                    agent: snap.agent,
+                    message: "canonical expects MCP runtime entry \"" + name + "\" for " + snap.agent + ", but it is missing from the agent static configuration",
+                });
+            }
+        }
+    }
+    return findings;
+}
 /** Exported so `trellis onboard` can reuse it verbatim for its own final
  * stage (trellis-onboard-closed-loop) rather than a second copy of this
  * formatting. */

package/dist/commands/init.d.ts

@@ -29,7 +29,7 @@ export interface InitReport {
 /** Exported so `migrate` can byte-compare canonical `agents.md` against
  * this exact string (design.md D3, trellis-cli-migrate) rather than
  * retyping an equivalent one that could silently drift from this. */
-export declare const AGENTS_MD_TEMPLATE = "# Shared instructions\n\nWrite what every agent should know here \u2014 communication preferences,\nproject conventions, anything you'd otherwise repeat per agent.\n\nAlready using Claude Code, Codex, Kiro, or pi? `trellis migrate --from\n<agent>` imports its real instructions and skills instead of starting\nfrom this placeholder.\n";
+export declare const AGENTS_MD_TEMPLATE = "# Shared instructions\n\nWrite what every agent should know here \u2014 communication preferences,\nproject conventions, anything you'd otherwise repeat per agent.\n\nAlready using Claude Code, Codex, Kiro, pi, Kimi Code, or ZCode? `trellis migrate --from\n<agent>` imports its real instructions and skills instead of starting\nfrom this placeholder.\n";
 /**
  * Trellis never spawns an installer itself (global package installs are
  * exactly the kind of irreversible, system-wide action that needs the
@@ -38,7 +38,9 @@ export declare const AGENTS_MD_TEMPLATE = "# Shared instructions\n\nWrite what e
  * own current install docs, same discipline as everything else here.
  */
 export declare const INSTALL_HINTS: Record<AgentId, string>;
-export declare function collectInitReport(homeDir?: string): Promise<InitReport>;
+export declare function collectInitReport(homeDir?: string, options?: {
+    write?: boolean;
+}): Promise<InitReport>;
 export declare function runInit(opts?: RunInitOptions): Promise<{
     exitCode: number;
 }>;

package/dist/commands/init.js

@@ -15,6 +15,8 @@ import * as claudeCodeProbe from "../probes/claude-code.js";
 import * as codexProbe from "../probes/codex.js";
 import * as kiroProbe from "../probes/kiro.js";
 import * as piProbe from "../probes/pi.js";
+import * as kimiCodeProbe from "../probes/kimi-code.js";
+import * as zcodeProbe from "../probes/zcode.js";
 import { ALL_AGENTS } from "../core/types.js";
 /** Exported so `migrate` can byte-compare canonical `agents.md` against
  * this exact string (design.md D3, trellis-cli-migrate) rather than
@@ -24,7 +26,7 @@ export const AGENTS_MD_TEMPLATE = `# Shared instructions
 Write what every agent should know here — communication preferences,
 project conventions, anything you'd otherwise repeat per agent.
 
-Already using Claude Code, Codex, Kiro, or pi? \`trellis migrate --from
+Already using Claude Code, Codex, Kiro, pi, Kimi Code, or ZCode? \`trellis migrate --from
 <agent>\` imports its real instructions and skills instead of starting
 from this placeholder.
 `;
@@ -93,32 +95,46 @@ export const INSTALL_HINTS = {
     codex: "npm install -g @openai/codex",
     kiro: "https://kiro.dev/downloads/",
     pi: "npm install -g @earendil-works/pi-coding-agent",
+    "kimi-code": "curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash",
+    zcode: "https://zcode.z.ai/en/docs/install",
 };
-function ensureFile(path, template) {
+function ensureFile(path, template, write = true) {
     if (existsSync(path)) {
         return { path, action: "already-present" };
     }
-    writeFileSync(path, template);
+    if (write)
+        writeFileSync(path, template);
     return { path, action: "create" };
 }
-export async function collectInitReport(homeDir = homedir()) {
+export async function collectInitReport(homeDir = homedir(), options = {}) {
+    const write = options.write !== false;
     const root = join(homeDir, ".trellis");
-    mkdirSync(root, { recursive: true });
-    mkdirSync(join(root, "mcp"), { recursive: true });
-    mkdirSync(join(root, "skills"), { recursive: true });
-    mkdirSync(join(root, "agents"), { recursive: true });
-    mkdirSync(join(root, "memories"), { recursive: true });
+    if (write) {
+        mkdirSync(root, { recursive: true });
+        mkdirSync(join(root, "mcp"), { recursive: true });
+        mkdirSync(join(root, "skills"), { recursive: true });
+        mkdirSync(join(root, "agents"), { recursive: true });
+        mkdirSync(join(root, "memories"), { recursive: true });
+    }
     const files = [
-        ensureFile(join(root, "agents.md"), AGENTS_MD_TEMPLATE),
-        ensureFile(join(root, "mcp", "servers.yaml"), serversYamlTemplate()),
-        ensureFile(join(root, "secrets.policy.yaml"), secretsPolicyYamlTemplate()),
-        ensureFile(join(root, "managed.yaml"), managedYamlTemplate()),
+        ensureFile(join(root, "agents.md"), AGENTS_MD_TEMPLATE, write),
+        ensureFile(join(root, "mcp", "servers.yaml"), serversYamlTemplate(), write),
+        ensureFile(join(root, "secrets.policy.yaml"), secretsPolicyYamlTemplate(), write),
+        ensureFile(join(root, "managed.yaml"), managedYamlTemplate(), write),
     ];
+    const here = dirname(fileURLToPath(import.meta.url));
+    const builtinSkillPath = join(root, "skills", "trellis-runtime", "SKILL.md");
+    const builtinSkillTemplate = readFileSync(join(here, "..", "..", "schema", "builtin-skills", "trellis-runtime", "SKILL.md"), "utf8");
+    if (write)
+        mkdirSync(dirname(builtinSkillPath), { recursive: true });
+    files.push(ensureFile(builtinSkillPath, builtinSkillTemplate, write));
     const probes = [
         { agent: "claude-code", run: () => claudeCodeProbe.probe(homeDir) },
         { agent: "codex", run: () => codexProbe.probe(homeDir) },
         { agent: "kiro", run: () => kiroProbe.probe(homeDir) },
         { agent: "pi", run: () => piProbe.probe(homeDir) },
+        { agent: "kimi-code", run: () => kimiCodeProbe.probe(homeDir) },
+        { agent: "zcode", run: () => zcodeProbe.probe(homeDir) },
     ];
     const settled = await Promise.allSettled(probes.map((p) => p.run()));
     const agents = settled.map((result, index) => {

package/dist/commands/kimi.d.ts

@@ -0,0 +1,16 @@
+/** Runtime-first Kimi Code launcher.
+ *
+ * Kimi automatically discovers ~/.agents/skills. When canonical delivery is
+ * `mcp`, passing one empty --skills-dir is the only documented way to replace
+ * both user/project Skill roots for this launch and prevent duplicate native
+ * Skill delivery. Native/both modes invoke Kimi normally.
+ */
+import { spawn as spawnProcess } from "node:child_process";
+export interface RunKimiOptions {
+    homeDir?: string;
+    env?: NodeJS.ProcessEnv;
+    spawn?: typeof spawnProcess;
+}
+export declare function runKimi(args?: readonly string[], opts?: RunKimiOptions): Promise<{
+    exitCode: number;
+}>;

package/dist/commands/kimi.js

@@ -0,0 +1,64 @@
+/** Runtime-first Kimi Code launcher.
+ *
+ * Kimi automatically discovers ~/.agents/skills. When canonical delivery is
+ * `mcp`, passing one empty --skills-dir is the only documented way to replace
+ * both user/project Skill roots for this launch and prevent duplicate native
+ * Skill delivery. Native/both modes invoke Kimi normally.
+ */
+import { execFileSync, spawn as spawnProcess } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { capabilityDeliveryForAgent } from "../core/types.js";
+import { loadCanonicalSource } from "../core/canonical.js";
+function resolveKimiCommand(homeDir, env) {
+    const explicit = env.TRELLIS_KIMI_BIN;
+    if (explicit && existsSync(explicit))
+        return explicit;
+    const homeBinary = join(env.KIMI_CODE_HOME ?? join(homeDir, ".kimi-code"), "bin", "kimi");
+    if (existsSync(homeBinary))
+        return homeBinary;
+    try {
+        return execFileSync("which", ["kimi"], { encoding: "utf8", env }).trim() || "kimi";
+    }
+    catch {
+        return "kimi";
+    }
+}
+function hasSkillsDirArg(args) {
+    return args.some((arg) => arg === "--skills-dir" || arg.startsWith("--skills-dir="));
+}
+export async function runKimi(args = [], opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const env = { ...process.env, ...(opts.env ?? {}) };
+    let canonical;
+    try {
+        canonical = loadCanonicalSource(homeDir);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
+    }
+    const delivery = capabilityDeliveryForAgent("kimi-code", canonical.mcp);
+    const runtimeOnly = delivery === "mcp";
+    if (runtimeOnly && hasSkillsDirArg(args)) {
+        console.error("trellis kimi: --skills-dir cannot be combined with Runtime-only delivery; change mcp.runtime.delivery.kimi-code or use native Kimi directly");
+        return { exitCode: 1 };
+    }
+    let emptySkillsDir;
+    const launchArgs = [...args];
+    if (runtimeOnly) {
+        emptySkillsDir = mkdtempSync(join(tmpdir(), "trellis-kimi-empty-skills-"));
+        launchArgs.unshift("--skills-dir", emptySkillsDir);
+    }
+    const command = resolveKimiCommand(homeDir, env);
+    const spawn = opts.spawn ?? spawnProcess;
+    const child = spawn(command, launchArgs, { stdio: "inherit", env });
+    const exitCode = await new Promise((resolve) => {
+        child.once("error", () => resolve(1));
+        child.once("exit", (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+    });
+    if (emptySkillsDir)
+        rmSync(emptySkillsDir, { recursive: true, force: true });
+    return { exitCode };
+}