agent-trellis 0.8.0 → 0.8.2

package/dist/lib/envVarNames.d.ts

@@ -44,6 +44,9 @@ export declare function declaredEnvNames(def: McpServerDef): string[];
  * different command, not this extractor's job.
  */
 export declare function extractJsonEnvVarNames(content: string): string[];
+/** ZCode stores the same server value shape under `mcp.servers` rather than
+ * the top-level `mcpServers` map used by Claude Code and Kiro. */
+export declare function extractZcodeEnvVarNames(content: string): string[];
 /** Codex's config is TOML. The shapes audit needs: every `env_vars = [...]`
  * line's quoted string contents, plus a `bearer_token_env_var = "VAR"`
  * line's bare name (a name directly, not a `${VAR}` template — Codex's

package/dist/lib/envVarNames.js

@@ -71,6 +71,25 @@ export function extractJsonEnvVarNames(content) {
     }
     return names;
 }
+/** ZCode stores the same server value shape under `mcp.servers` rather than
+ * the top-level `mcpServers` map used by Claude Code and Kiro. */
+export function extractZcodeEnvVarNames(content) {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        return [];
+    }
+    const names = [];
+    for (const server of Object.values(parsed.mcp?.servers ?? {})) {
+        for (const value of Object.values(server.env ?? {}))
+            names.push(...extractTemplateVarNames(value));
+        for (const value of Object.values(server.headers ?? {}))
+            names.push(...extractTemplateVarNames(value));
+    }
+    return names;
+}
 const ENV_VARS_LINE_RE = /^\s*env_vars\s*=\s*\[(.*)\]\s*$/;
 const BEARER_TOKEN_ENV_VAR_LINE_RE = /^\s*bearer_token_env_var\s*=\s*"([^"]*)"\s*$/;
 const QUOTED_STRING_RE = /"((?:[^"\\]|\\.)*)"/g;

package/dist/lib/installAgent.d.ts

@@ -10,7 +10,7 @@ import type { AgentId } from "../core/types.js";
 /** Only agents with a real `npm install -g <pkg>` command — Kiro's own
  * `INSTALL_HINTS` entry is a download URL, not a package, and is never
  * looked up here. */
-export declare const NPM_INSTALLABLE: Record<Exclude<AgentId, "kiro" | "kimi-code">, string>;
+export declare const NPM_INSTALLABLE: Record<Exclude<AgentId, "kiro" | "kimi-code" | "zcode">, string>;
 export interface ConfirmAndInstallOptions {
     /** Test/real seam, same pattern as onboard's `promptForAgent` — a real
      * terminal confirmation by default. */

package/dist/lib/installAgent.js

@@ -32,7 +32,7 @@ function runInstallReal(pkg) {
     execFileSync("npm", ["install", "-g", pkg], { stdio: "inherit" });
 }
 export async function confirmAndInstall(agent, opts = {}) {
-    if (agent === "kiro" || agent === "kimi-code") {
+    if (agent === "kiro" || agent === "kimi-code" || agent === "zcode") {
         return { installed: false, installable: false };
     }
     const pkg = NPM_INSTALLABLE[agent];

package/dist/lib/mcpMigrateRead.d.ts

@@ -38,6 +38,7 @@ export declare function resolvedEnvTextMap(def: Pick<McpServerDef, "env" | "envA
 export declare function readClaudeCodeMcpDefs(homeDir: string): McpMigrateReadResult;
 export declare function readKiroMcpDefs(homeDir: string): McpMigrateReadResult;
 export declare function readKimiCodeMcpDefs(homeDir: string): McpMigrateReadResult;
+export declare function readZcodeMcpDefs(homeDir: string): McpMigrateReadResult;
 export interface CodexMcpEntryRich {
     name: string;
     enabled: boolean;

package/dist/lib/mcpMigrateRead.js

@@ -15,6 +15,8 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { readJsonFile } from "./probeCommon.js";
 import { readServerEnvTable } from "./tomlSection.js";
+import { resolveZcodeProfile } from "../probes/zcode.js";
+import { codexEnv } from "../probes/codex.js";
 const EMPTY_RESULT = { entries: [], unsupported: [] };
 /**
  * Trellis's own `env` (self-referencing name) vs. `envAliases`
@@ -111,6 +113,22 @@ export function readKiroMcpDefs(homeDir) {
 export function readKimiCodeMcpDefs(homeDir) {
     return readRichJsonMcpDefs(join(homeDir, ".kimi-code", "mcp.json"));
 }
+export function readZcodeMcpDefs(homeDir) {
+    const profile = resolveZcodeProfile(homeDir);
+    if (!profile)
+        return EMPTY_RESULT;
+    const parsed = readJsonFile(profile.configPath);
+    const entries = [];
+    const unsupported = [];
+    for (const [name, raw] of Object.entries(parsed?.mcp?.servers ?? {})) {
+        const def = fromRichJsonServerDef(raw);
+        if (def)
+            entries.push({ name, def });
+        else
+            unsupported.push({ name, reason: "stdio entry has no command — malformed, skipped" });
+    }
+    return { entries, unsupported };
+}
 /**
  * Pure conversion half — separated from the subprocess/file-read effects
  * below so the stdio/non-stdio/malformed decision logic is unit-testable
@@ -202,7 +220,7 @@ export function readCodexMcpDefs(homeDir) {
         // `[]`, not the real machine's servers), so this must be scoped to
         // `homeDir` explicitly — `src/probes/codex.ts`'s own equivalent call
         // has this same gap, unaddressed there; not touched by this change.
-        raw = execFileSync("codex", ["mcp", "list", "--json"], { encoding: "utf-8", timeout: 5_000, env: { ...process.env, HOME: homeDir } });
+        raw = execFileSync("codex", ["mcp", "list", "--json"], { encoding: "utf-8", timeout: 5_000, env: codexEnv(homeDir) });
     }
     catch {
         return EMPTY_RESULT;

package/dist/lib/realHomeSnapshot.js

@@ -21,6 +21,11 @@ export const REAL_HOME_ALLOWLIST = [
     ".codex/config.toml",
     ".agents/skills",
     ".codex/skills",
+    // zcode (src/probes/zcode.ts)
+    ".zcode/cli/config.json",
+    ".zcode/cli/setting.json",
+    ".zcode/skills",
+    ".zcode/AGENTS.md",
     // kiro (src/probes/kiro.ts)
     ".kiro/settings/mcp.json",
     ".kiro/skills",

package/dist/lib/runtimeControlProvider.js

@@ -9,6 +9,7 @@ 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 { TRELLIS_VERSION } from "./cliMetadata.js";
 import { inspectMemoryReadiness } from "./memoryStatus.js";
 const MAX_INSTRUCTIONS_BYTES = 256 * 1024;
@@ -37,6 +38,7 @@ const PROBES = {
     kiro: (homeDir) => kiroProbe.probe(homeDir),
     pi: (homeDir) => piProbe.probe(homeDir),
     "kimi-code": (homeDir) => kimiCodeProbe.probe(homeDir),
+    zcode: (homeDir) => zcodeProbe.probe(homeDir),
 };
 function textResult(value) {
     return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], structuredContent: value };

package/dist/lib/taskStore.js

@@ -42,7 +42,7 @@ function now() {
     return new Date().toISOString();
 }
 function assertAgent(value, label) {
-    if (value !== "claude-code" && value !== "codex" && value !== "kiro" && value !== "pi" && value !== "kimi-code") {
+    if (value !== "claude-code" && value !== "codex" && value !== "kiro" && value !== "pi" && value !== "kimi-code" && value !== "zcode") {
         throw new Error(`${label} must be a supported Agent id`);
     }
 }

package/dist/lib/terminalPicker.js

@@ -6,7 +6,31 @@
  * handling, color, wrapping, cursor cleanup, and cancellation; the injected
  * streams keep the prompt loop testable without a real terminal.
  */
-import { CANCEL_SYMBOL, autocompleteMultiselect, isCancel, multiselect, select } from "@clack/prompts";
+/**
+ * `@clack/prompts` (and its `@clack/core` dependency) is loaded lazily,
+ * inside each picker function below, rather than via a top-level
+ * `import` — deliberately, not an oversight. A top-level import runs the
+ * moment ANY module that transitively imports this file is evaluated,
+ * which for `trellis-gui`'s sidecar means every process start, since
+ * `onboard.ts` (imported unconditionally by the sidecar's `/plan/onboard`
+ * route) imports these functions even though the sidecar's `json: true`
+ * contract (see `planApply.ts`'s `OnboardWizardInput` doc comment)
+ * guarantees they are never actually called. Compiling the sidecar to a
+ * single-file binary (tasks.md 5.1) surfaced a real, current limitation
+ * in `@yao-pkg/pkg`'s ESM support: `@clack/prompts`' `exports`-map
+ * `.mjs` entry fails to resolve inside pkg's snapshot filesystem
+ * (`Cannot find module '.../@clack/prompts/dist/index.mjs'`), which
+ * previously crashed the packaged sidecar at startup even though its own
+ * code never uses the interactive picker at all. A dynamic `import()`
+ * only resolves at the point it actually runs, so the sidecar (whose
+ * `!opts.json` gates keep every real call site below unreached) never
+ * triggers that resolution attempt — while a real, interactive CLI run
+ * (`tsx`/`node`, not a pkg snapshot) resolves the dynamic import exactly
+ * as it would a static one, so this is behavior-preserving for the CLI.
+ */
+async function clack() {
+    return import("@clack/prompts");
+}
 function defaultStreams() {
     return { input: process.stdin, output: process.stderr };
 }
@@ -29,14 +53,15 @@ export function toggled(checked, index) {
     next[index] = !next[index];
     return next;
 }
-function wasCancelled(value) {
-    return value === CANCEL_SYMBOL || isCancel(value);
+function wasCancelled(value, cancelSymbol, isCancelFn) {
+    return value === cancelSymbol || isCancelFn(value);
 }
 /**
  * Single-select prompt. The returned number is the original item index, so
  * callers do not depend on display labels or prompt-library values.
  */
 export async function runSingleSelectPicker(items, streams = defaultStreams(), message = "请选择一个迁移来源") {
+    const { select, CANCEL_SYMBOL, isCancel } = await clack();
     const result = await select({
         message,
         options: items.map((item, value) => ({
@@ -48,13 +73,14 @@ export async function runSingleSelectPicker(items, streams = defaultStreams(), m
         output: streams.output,
         showInstructions: true,
     });
-    return wasCancelled(result) ? null : result;
+    return wasCancelled(result, CANCEL_SYMBOL, isCancel) ? null : result;
 }
 /**
  * Checkbox prompt. The returned indices preserve the existing onboard
  * contract, while Clack handles checked state, wrapping, colors, and cleanup.
  */
 export async function runMultiSelectPicker(items, initiallyChecked, streams = defaultStreams(), message = "请选择要启用的项目") {
+    const { multiselect, CANCEL_SYMBOL, isCancel } = await clack();
     const result = await multiselect({
         message,
         options: items.map((label, value) => ({ label, value })),
@@ -64,12 +90,13 @@ export async function runMultiSelectPicker(items, initiallyChecked, streams = de
         required: false,
         showInstructions: true,
     });
-    return wasCancelled(result) ? null : [...result].sort((left, right) => left - right);
+    return wasCancelled(result, CANCEL_SYMBOL, isCancel) ? null : [...result].sort((left, right) => left - right);
 }
 /** Searchable multiselect for large skill/MCP inventories. It returns the
  * selected labels as stable names, preserving the semantic adapter contract
  * while avoiding a wall of dozens of rows in the onboarding terminal. */
 export async function runSearchMultiSelectPicker(items, streams = defaultStreams(), message = "选择要迁移的项目") {
+    const { autocompleteMultiselect, CANCEL_SYMBOL, isCancel } = await clack();
     const result = await autocompleteMultiselect({
         message,
         placeholder: "输入关键词筛选",
@@ -79,5 +106,5 @@ export async function runSearchMultiSelectPicker(items, streams = defaultStreams
         output: streams.output,
         required: false,
     });
-    return wasCancelled(result) ? null : result;
+    return wasCancelled(result, CANCEL_SYMBOL, isCancel) ? null : result;
 }

package/dist/lib/zcodeOwnership.d.ts

@@ -0,0 +1,17 @@
+/** Ownership record for the two ZCode native-Skill controls Trellis changes
+ * during strict Runtime delivery. MCP ownership stays in mcpOwnership.ts;
+ * this separate record lets a later native/both delivery restore the user's
+ * prior values without treating an ordinary config key as an MCP server. */
+export interface ZcodeSkillControlValues {
+    featuresSkill: boolean | null;
+    skillsEnabled: boolean | null;
+}
+export interface ZcodeSettingsOwnership {
+    configPath: string;
+    managed: ZcodeSkillControlValues;
+    previous: ZcodeSkillControlValues;
+}
+export declare function zcodeSettingsOwnershipPath(homeDir: string): string;
+export declare function loadZcodeSettingsOwnership(homeDir: string): ZcodeSettingsOwnership | undefined;
+export declare function saveZcodeSettingsOwnership(homeDir: string, value: ZcodeSettingsOwnership): void;
+export declare function forgetZcodeSettingsOwnership(homeDir: string): void;

package/dist/lib/zcodeOwnership.js

@@ -0,0 +1,37 @@
+/** Ownership record for the two ZCode native-Skill controls Trellis changes
+ * during strict Runtime delivery. MCP ownership stays in mcpOwnership.ts;
+ * this separate record lets a later native/both delivery restore the user's
+ * prior values without treating an ordinary config key as an MCP server. */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export function zcodeSettingsOwnershipPath(homeDir) {
+    return join(homeDir, ".trellis", "zcode", "settings-ownership.json");
+}
+export function loadZcodeSettingsOwnership(homeDir) {
+    const path = zcodeSettingsOwnershipPath(homeDir);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof value.configPath !== "string"
+            || typeof value.managed?.featuresSkill !== "boolean"
+            || typeof value.managed?.skillsEnabled !== "boolean"
+            || (value.previous?.featuresSkill !== null && typeof value.previous?.featuresSkill !== "boolean")
+            || (value.previous?.skillsEnabled !== null && typeof value.previous?.skillsEnabled !== "boolean"))
+            return undefined;
+        return value;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function saveZcodeSettingsOwnership(homeDir, value) {
+    const path = zcodeSettingsOwnershipPath(homeDir);
+    mkdirSync(join(homeDir, ".trellis", "zcode"), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+export function forgetZcodeSettingsOwnership(homeDir) {
+    const path = zcodeSettingsOwnershipPath(homeDir);
+    if (existsSync(path))
+        writeFileSync(path, "");
+}

package/dist/pi-bridge/bundle.js

@@ -15150,7 +15150,8 @@ var ALL_AGENTS = [
   "codex",
   "kiro",
   "pi",
-  "kimi-code"
+  "kimi-code",
+  "zcode"
 ];
 function resolveScope(scope, managedAgents) {
   const candidates = scope ?? managedAgents;

package/dist/probes/codex.d.ts

@@ -21,4 +21,11 @@ export interface ProbeOptions {
      * default — see docs/architecture.md "MCP handshake probing is opt-in". */
     probeMcp?: boolean;
 }
+/**
+ * Codex resolves its config through HOME, but Volta's shim resolves its own
+ * installation through VOLTA_HOME. A probe against a scratch HOME must keep
+ * those identities separate or `codex mcp list` fails before it can read the
+ * scratch config.
+ */
+export declare function codexEnv(homeDir: string, env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 export declare function probe(homeDir?: string, opts?: ProbeOptions): Promise<AgentSnapshot>;

package/dist/probes/codex.js

@@ -11,7 +11,7 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { delimiter, join } from "node:path";
 import { probeMcpServer } from "../lib/mcpProbe.js";
 import { pathRef, resolveEnvRefs, scanSkillRoot } from "../lib/probeCommon.js";
 /**
@@ -30,6 +30,30 @@ export function readInstructionsPath(configTomlPath) {
     }
     return /^\s*instructions\s*=\s*"([^"]*)"/m.exec(content)?.[1];
 }
+/**
+ * Codex resolves its config through HOME, but Volta's shim resolves its own
+ * installation through VOLTA_HOME. A probe against a scratch HOME must keep
+ * those identities separate or `codex mcp list` fails before it can read the
+ * scratch config.
+ */
+export function codexEnv(homeDir, env = process.env) {
+    const voltaHome = env.VOLTA_HOME ?? join(homedir(), ".volta");
+    const voltaBin = join(voltaHome, "bin");
+    const pathParts = (env.PATH ?? "").split(delimiter).filter(Boolean);
+    const hasVolta = existsSync(voltaBin);
+    if (hasVolta && !pathParts.includes(voltaBin))
+        pathParts.unshift(voltaBin);
+    return {
+        ...env,
+        HOME: homeDir,
+        // A host may inject CODEX_HOME for its own relay/session state. It has
+        // higher priority than HOME inside Codex, so override it as well or a
+        // scratch-home probe silently reads the host's real configuration.
+        CODEX_HOME: join(homeDir, ".codex"),
+        ...(hasVolta ? { VOLTA_HOME: voltaHome } : {}),
+        ...(pathParts.length ? { PATH: pathParts.join(delimiter) } : {}),
+    };
+}
 export async function probe(homeDir = homedir(), opts = {}) {
     const configTomlPath = join(homeDir, ".codex", "config.toml");
     if (!existsSync(configTomlPath)) {
@@ -43,21 +67,29 @@ export async function probe(homeDir = homedir(), opts = {}) {
     // default `homeDir` would silently get this real machine's real MCP
     // server list instead (trellis-migrate-mcp-servers found this gap in
     // src/lib/mcpMigrateRead.ts's own equivalent call; fixed there first).
-    const codexEnv = { ...process.env, HOME: homeDir };
+    const scopedCodexEnv = codexEnv(homeDir);
     let version;
     try {
-        version = execFileSync("codex", ["--version"], { encoding: "utf-8", timeout: 5_000, env: codexEnv }).trim();
+        version = execFileSync("codex", ["--version"], { encoding: "utf-8", timeout: 5_000, env: scopedCodexEnv }).trim();
     }
     catch {
         // config exists without the binary on PATH — unusual, still probeable
     }
     let mcpEntries = [];
     try {
-        const raw = execFileSync("codex", ["mcp", "list", "--json"], { encoding: "utf-8", timeout: 5_000, env: codexEnv });
+        const raw = execFileSync("codex", ["mcp", "list", "--json"], { encoding: "utf-8", timeout: 5_000, env: scopedCodexEnv });
         mcpEntries = JSON.parse(raw);
     }
     catch (err) {
-        diagnostics.push(`codex mcp list --json failed: ${err instanceof Error ? err.message : String(err)}`);
+        // ENOENT means the binary itself isn't on PATH — the same benign,
+        // config-without-binary condition the `--version` check above already
+        // swallows silently, not a real failure worth alarming the user with a
+        // raw spawn error string. Anything else (malformed JSON, a non-zero
+        // exit for another reason, a timeout) is a genuine, unexpected failure
+        // and stays a diagnostic.
+        if (err?.code !== "ENOENT") {
+            diagnostics.push(`codex mcp list --json failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
     }
     const mcpServers = mcpEntries.map((entry) => ({
         name: entry.name,

package/dist/probes/zcode.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ZCode probe and profile selection.
+ *
+ * ZCode has two public configuration layouts in circulation. The official
+ * source/distribution reads ~/.zcode/cli/config.json, while the installed
+ * zcode-app-cli compatibility distribution keeps runtime settings (including
+ * mcp.servers) in ~/.zcode/cli/setting.json. We select one profile before any
+ * adapter plans a write; writing both would make ZCode's native precedence
+ * ambiguous and can hide a managed MCP entry.
+ */
+import type { AgentSnapshot } from "../core/types.js";
+export type ZcodeProfileKind = "community-cli" | "official" | "configuration-only";
+export interface ZcodeProfile {
+    kind: ZcodeProfileKind;
+    configPath: string;
+    executable?: string;
+    executableVersion?: string;
+    supportsExecution: boolean;
+}
+export interface ProbeOptions {
+    probeMcp?: boolean;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function zcodeEnv(homeDir: string, env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function selectZcodeProfile(homeDir: string, facts?: {
+    command?: string;
+    version?: string;
+    help?: string;
+    outputFormatSupported?: boolean;
+}): ZcodeProfile | undefined;
+export declare function resolveZcodeProfile(homeDir?: string, env?: NodeJS.ProcessEnv): ZcodeProfile | undefined;
+export declare function probe(homeDir?: string, opts?: ProbeOptions): Promise<AgentSnapshot>;

package/dist/probes/zcode.js

@@ -0,0 +1,140 @@
+/**
+ * ZCode probe and profile selection.
+ *
+ * ZCode has two public configuration layouts in circulation. The official
+ * source/distribution reads ~/.zcode/cli/config.json, while the installed
+ * zcode-app-cli compatibility distribution keeps runtime settings (including
+ * mcp.servers) in ~/.zcode/cli/setting.json. We select one profile before any
+ * adapter plans a write; writing both would make ZCode's native precedence
+ * ambiguous and can hide a managed MCP entry.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { probeMcpServer } from "../lib/mcpProbe.js";
+import { pathRef, readJsonFile, resolveEnvRefs, scanSkillRoot } from "../lib/probeCommon.js";
+export function zcodeEnv(homeDir, env = process.env) {
+    // A Node host can inherit Volta's selected Node binary without inheriting
+    // Volta's shim directory in PATH. Keep the user's explicit PATH order, but
+    // add the documented Volta bin location when necessary so `zcode` resolves
+    // the same way it does in their interactive terminal.
+    const voltaBin = env.VOLTA_HOME ? join(env.VOLTA_HOME, "bin") : undefined;
+    const pathParts = (env.PATH ?? "").split(delimiter).filter(Boolean);
+    if (voltaBin && !pathParts.includes(voltaBin))
+        pathParts.unshift(voltaBin);
+    return { ...env, HOME: homeDir, ...(pathParts.length ? { PATH: pathParts.join(delimiter) } : {}) };
+}
+function configPaths(homeDir) {
+    const root = join(homeDir, ".zcode");
+    return {
+        root,
+        community: join(root, "cli", "setting.json"),
+        official: join(root, "cli", "config.json"),
+    };
+}
+function publicCommand(env) {
+    return env.TRELLIS_ZCODE_BIN?.trim() || "zcode";
+}
+function cliFacts(homeDir, env) {
+    const command = publicCommand(env);
+    const childEnv = zcodeEnv(homeDir, env);
+    try {
+        const version = execFileSync(command, ["version"], { encoding: "utf-8", timeout: 5_000, env: childEnv }).trim();
+        let help;
+        let outputFormatSupported = false;
+        try {
+            help = execFileSync(command, ["--help"], { encoding: "utf-8", timeout: 5_000, env: childEnv });
+        }
+        catch {
+            // A version identity still permits a configuration-only profile.
+        }
+        try {
+            // Some zcode-app-cli builds accept --output-format but omit it from
+            // their generated help text. --version never starts a model turn, so
+            // it is a safe capability probe for the public argument contract.
+            execFileSync(command, ["--output-format", "stream-json", "--version"], { encoding: "utf-8", timeout: 5_000, env: childEnv });
+            outputFormatSupported = true;
+        }
+        catch {
+            // Keep the false value; callers then leave execution disabled.
+        }
+        return { command, version, ...(help ? { help } : {}), outputFormatSupported };
+    }
+    catch {
+        return {};
+    }
+}
+export function selectZcodeProfile(homeDir, facts = {}) {
+    const paths = configPaths(homeDir);
+    const version = facts.version ?? "";
+    const supportsExecution = Boolean(facts.command
+        && facts.help?.includes("--prompt")
+        && facts.help.includes("--resume")
+        && (facts.help.includes("--output-format") || facts.outputFormatSupported === true));
+    if (/^zcode-app-cli\b/im.test(version) || (existsSync(paths.community) && !existsSync(paths.official))) {
+        return {
+            kind: "community-cli",
+            configPath: paths.community,
+            ...(facts.command ? { executable: facts.command } : {}),
+            ...(facts.version ? { executableVersion: facts.version } : {}),
+            supportsExecution,
+        };
+    }
+    if (facts.command || existsSync(paths.official)) {
+        return {
+            kind: facts.command ? "official" : "configuration-only",
+            configPath: paths.official,
+            ...(facts.command ? { executable: facts.command } : {}),
+            ...(facts.version ? { executableVersion: facts.version } : {}),
+            supportsExecution,
+        };
+    }
+    if (existsSync(paths.root)) {
+        return { kind: "configuration-only", configPath: paths.official, supportsExecution: false };
+    }
+    return undefined;
+}
+export function resolveZcodeProfile(homeDir = homedir(), env = process.env) {
+    // A public `zcode` binary is installed system-wide, whereas probes run
+    // against an explicit home directory. Do not let the real machine's CLI
+    // make an empty sandbox home appear to have ZCode installed; the profile
+    // must have local `.zcode` state before any executable is queried.
+    if (!existsSync(configPaths(homeDir).root))
+        return undefined;
+    return selectZcodeProfile(homeDir, cliFacts(homeDir, env));
+}
+export async function probe(homeDir = homedir(), opts = {}) {
+    const env = opts.env ?? process.env;
+    const profile = resolveZcodeProfile(homeDir, env);
+    if (!profile)
+        return { agent: "zcode", present: false, skillRoots: [], mcpServers: [], diagnostics: [] };
+    const config = readJsonFile(profile.configPath);
+    const mcpServers = Object.entries(config?.mcp?.servers ?? {}).map(([name, def]) => ({
+        name,
+        transport: def.url ? (def.type === "sse" ? "sse" : "http") : "stdio",
+    }));
+    if (opts.probeMcp) {
+        await Promise.all(Object.entries(config?.mcp?.servers ?? {}).map(async ([name, def], index) => {
+            if (def.url || !def.command)
+                return;
+            mcpServers[index].probe = await probeMcpServer({ transport: "stdio", command: def.command, args: def.args }, resolveEnvRefs(def.env, zcodeEnv(homeDir, env)));
+        }));
+    }
+    const skillRoots = [
+        scanSkillRoot(join(homeDir, ".zcode", "skills")),
+        scanSkillRoot(join(homeDir, ".agents", "skills")),
+    ].filter((root) => root !== undefined);
+    const diagnostics = [];
+    if (!profile.supportsExecution)
+        diagnostics.push("ZCode public CLI execution is unavailable; configuration-only management is supported");
+    return {
+        agent: "zcode",
+        present: true,
+        ...(profile.executableVersion ? { version: profile.executableVersion } : {}),
+        skillRoots,
+        mcpServers,
+        instructionsFile: pathRef(join(homeDir, ".zcode", "AGENTS.md")),
+        diagnostics,
+    };
+}

package/docs/architecture.md

@@ -18,7 +18,7 @@ required reading for that.
                 │  trellis sync / trellis doctor
         ┌───────┼────────┬─────────────┬──────────────┐
         ▼                ▼             ▼              ▼
-   Claude Code         Codex          Kiro            pi          Kimi Code
+   Claude Code         Codex          Kiro            pi          Kimi Code       ZCode
   (symlink adapter) (incremental   (symlink adapter) (bridge
                      TOML writer)                    extension)
 ```
@@ -57,7 +57,7 @@ Aligned to the `.agents Protocol` draft, extended where the draft is silent:
 ## Global vs. workspace scope
 
 **Global only, for now.** Trellis manages `~/.trellis` — one canonical
-source per machine, applied to that machine's five supported agents. It does not yet
+source per machine, applied to that machine's six supported agents. It does not yet
 read or merge a project-local `.trellis/` in a specific repo.
 
 The `.agents Protocol` draft (see `research.md`) describes a two-layer
@@ -72,7 +72,7 @@ that's scope creep against this section, not a natural extension.
 
 ## Private / agent-specific capabilities
 
-Not everything belongs to all five agents. A skill built around Claude
+Not everything belongs to all six agents. A skill built around Claude
 Code's Task-based subagent delegation has no equivalent to delegate to on
 Codex; an MCP server might only make sense for one agent's workflow. Every
 scopable item — skill, subagent profile, memory entry, MCP server —
@@ -483,8 +483,12 @@ portable Skill contract.
   provides — `~/.config/agent-env/secrets.env`, 1Password's `op run`,
   anything that populates `process.env` before an adapter's generated
   command runs)
-- A GUI (P5 in the roadmap evaluates embedding into an existing one —
-  mcp-router's or skills-hub's — before building a new one)
+- A GUI is now `@trellis/gui` — P10 in the roadmap, not P5 (P5 is
+  `@trellis/sdk`, the read-only API the GUI's own read views could have
+  used but didn't, per `openspec/changes/trellis-gui/design.md` Decision
+  1 — the GUI's sidecar imports internal command modules directly
+  instead, to reuse write/backup mechanics `@trellis/sdk`'s read-only
+  barrel deliberately excludes)
 
 ## MCP handshake probing is opt-in, not default
 

package/docs/assets/brand-v3/trellis-mark-v3-a.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96" role="img" aria-labelledby="title desc">
+  <title id="title">Trellis mark</title>
+  <desc id="desc">A letter T whose beam is a trellis lattice.</desc>
+  <g fill="none" stroke="#161c24" stroke-linecap="round">
+    <rect x="16" y="18" width="64" height="18" rx="9" stroke-width="5.5"/>
+    <g stroke-width="2.6" clip-path="url(#a-beam)"><path d="M-64.5 32 L-55.5 23"/><path d="M-64.5 23 L-55.5 32"/><path d="M-46.5 32 L-37.5 23"/><path d="M-46.5 23 L-37.5 32"/><path d="M-28.5 32 L-19.5 23"/><path d="M-28.5 23 L-19.5 32"/><path d="M-10.5 32 L-1.5 23"/><path d="M-10.5 23 L-1.5 32"/><path d="M7.5 32 L16.5 23"/><path d="M7.5 23 L16.5 32"/><path d="M25.5 32 L34.5 23"/><path d="M25.5 23 L34.5 32"/><path d="M43.5 32 L52.5 23"/><path d="M43.5 23 L52.5 32"/><path d="M61.5 32 L70.5 23"/><path d="M61.5 23 L70.5 32"/><path d="M79.5 32 L88.5 23"/><path d="M79.5 23 L88.5 32"/><path d="M97.5 32 L106.5 23"/><path d="M97.5 23 L106.5 32"/><path d="M115.5 32 L124.5 23"/><path d="M115.5 23 L124.5 32"/></g>
+    <path d="M48 36 V78" stroke-width="8"/>
+  </g>
+  <defs><clipPath id="a-beam"><rect x="21" y="23" width="54" height="9" rx="4.5"/></clipPath></defs>
+</svg>