agent-trellis 0.8.0 → 0.9.0

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>

package/docs/assets/poster-series-v3/README.md

@@ -0,0 +1,60 @@
+# Agent Trellis poster series
+
+The canonical brand mark and social poster series. The earlier v1 and v2
+iterations were retired and removed; they remain in git history (`f4e5136`,
+`1045bb6`).
+
+Design notes:
+
+- The hero zone of each poster is a purpose-built diagram (agent paths,
+  migration flow, shared memory rail, context handoff) instead of the logo
+  scaled up inside empty corner brackets.
+- Each theme gets its own quiet accent color (indigo / teal / violet /
+  orange); the mark itself stays single-ink.
+- The kicker/title overlap in the v1 English layout is fixed; all metrics are
+  computed from the title baseline.
+- One horizontal 1200x675 master (X/Twitter, WeChat article header) joins the
+  3:4 verticals, in both English and Chinese.
+- Vertical posters are phone-first (feed width ~390 css px): body text runs at
+  34/35 px, diagram labels at 16-17 px, install line at 32 px. The horizontal
+  masters are desktop-first and keep the denser metrics.
+
+## Mark
+
+The brand mark is the **Lattice T** — the letter T whose beam is a trellis
+lattice: [svg](../brand-v3/trellis-mark-v3-a.svg) /
+[png](../brand-v3/trellis-mark-v3-a.png). It is a single-ink symbol and is the
+same mark used in the README header and every poster. Two retired alternates
+(constellation T, lattice panel) remain in git history.
+
+## Posters
+
+Vertical masters are 1080x1440 (3:4, Xiaohongshu / WeChat Moments); horizontal
+masters are 1200x675 (16:9). SVG sources are the editable masters.
+
+| Theme | EN | ZH |
+|---|---|---|
+| Unified runtime | [svg](agent-trellis-poster-v3-unified-en.svg) / [png](agent-trellis-poster-v3-unified-en.png) | [svg](agent-trellis-poster-v3-unified-zh.svg) / [png](agent-trellis-poster-v3-unified-zh.png) |
+| One-command migration | [svg](agent-trellis-poster-v3-migrate-en.svg) / [png](agent-trellis-poster-v3-migrate-en.png) | [svg](agent-trellis-poster-v3-migrate-zh.svg) / [png](agent-trellis-poster-v3-migrate-zh.png) |
+| Shared memory | [svg](agent-trellis-poster-v3-memory-en.svg) / [png](agent-trellis-poster-v3-memory-en.png) | [svg](agent-trellis-poster-v3-memory-zh.svg) / [png](agent-trellis-poster-v3-memory-zh.png) |
+| Switch agents | [svg](agent-trellis-poster-v3-switch-en.svg) / [png](agent-trellis-poster-v3-switch-en.png) | [svg](agent-trellis-poster-v3-switch-zh.svg) / [png](agent-trellis-poster-v3-switch-zh.png) |
+| Horizontal hero | [svg](agent-trellis-poster-v3-horizontal-en.svg) / [png](agent-trellis-poster-v3-horizontal-en.png) | [svg](agent-trellis-poster-v3-horizontal-zh.svg) / [png](agent-trellis-poster-v3-horizontal-zh.png) |
+
+## Copy
+
+Same approved copy as v1:
+
+- `One Runtime. Every Code Agent.` / 一个 Runtime，统一所有 Code Agent。
+- `Migrate in one command.` / 一条命令，迁移现有配置。
+- `Keep context in the loop.` / 让上下文始终在线。
+- `Change Agents. Keep moving.` / 切换 Agent，不丢上下文。
+
+## Regenerate
+
+```bash
+node scripts/generate-brand-v3.mjs          # brand mark
+node scripts/generate-poster-series-v3.mjs  # 8 vertical + 2 horizontal posters
+```
+
+Both scripts write SVG masters into `docs/assets/` and render PNGs through
+`qlmanage` + `sips` (macOS built-ins, no extra dependencies).

package/docs/assets/poster-series-v3/agent-trellis-poster-v3-horizontal-en.svg

@@ -0,0 +1,51 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="1600" viewBox="0 0 1600 1600">
+  <rect width="1600" height="1600" fill="#fafaf8"/>
+  <g transform="translate(0 350)">
+    <g transform="translate(64 100) scale(0.58)" fill="none" stroke="#161c24" stroke-linecap="round">
+  <defs><clipPath id="v3-beam-64-100"><rect x="21" y="23" width="54" height="9" rx="4.5"/></clipPath></defs>
+  <rect x="16" y="18" width="64" height="18" rx="9" stroke-width="5.5"/>
+  <g stroke-width="2.6" clip-path="url(#v3-beam-64-100)"><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>
+    <text x="140" y="141" text-anchor="start" font-family="Helvetica Neue, PingFang SC, Arial, sans-serif" font-size="26" font-weight="700" letter-spacing="2.6" fill="#161c24">AGENT TRELLIS</text>
+    <text x="1536" y="140" text-anchor="end" font-family="Menlo, SFMono-Regular, monospace" font-size="15" font-weight="400" letter-spacing="1.7" fill="#69727d">OPEN SOURCE · LOCAL FIRST</text>
+    <path d="M64 192 H1536" stroke="#dfe4ea" stroke-width="1.5"/>
+    <rect x="64" y="189" width="46" height="3" fill="#3457d5"/>
+
+    <text x="108" y="262" text-anchor="start" font-family="Menlo, SFMono-Regular, monospace" font-size="17" font-weight="400" letter-spacing="2.2" fill="#3457d5">UNIFIED CODE AGENT RUNTIME</text>
+    <rect x="64" y="300" width="8" height="182" fill="#3457d5"/>
+    <text x="108" y="366" text-anchor="start" font-family="Helvetica Neue, PingFang SC, Arial, sans-serif" font-size="84" font-weight="800" letter-spacing="-2.2" fill="#161c24">One Runtime.</text><text x="108" y="464" text-anchor="start" font-family="Helvetica Neue, PingFang SC, Arial, sans-serif" font-size="84" font-weight="800" letter-spacing="-2.2" fill="#161c24">Every Code Agent.</text>
+    <text x="108" y="522" text-anchor="start" font-family="Helvetica Neue, PingFang SC, Arial, sans-serif" font-size="24" font-weight="450" letter-spacing="0" fill="#69727d">Skills, MCP, Memory and Instructions</text><text x="108" y="558" text-anchor="start" font-family="Helvetica Neue, PingFang SC, Arial, sans-serif" font-size="24" font-weight="450" letter-spacing="0" fill="#69727d">stay aligned from one canonical source.</text>
+
+    <text x="108" y="640" text-anchor="start" font-family="Menlo, SFMono-Regular, monospace" font-size="15" font-weight="400" letter-spacing="1.6" fill="#69727d">SKILLS · MCP · MEMORY · INSTRUCTIONS</text>
+    <circle cx="112" cy="700" r="5.5" fill="#3457d5"/>
+    <text x="140" y="709" text-anchor="start" font-family="Menlo, SFMono-Regular, monospace" font-size="24" font-weight="500" letter-spacing="0.2" fill="#161c24">$ npm i -g agent-trellis</text>
+
+    <g>
+  <rect x="1000" y="250" width="500" height="450" fill="none" stroke="#dfe4ea" stroke-width="1.5"/>
+  <path d="M991 250 H1009 M1000 241 V259" fill="none" stroke="#dfe4ea" stroke-width="2"/><path d="M1491 250 H1509 M1500 241 V259" fill="none" stroke="#dfe4ea" stroke-width="2"/><path d="M991 700 H1009 M1000 691 V709" fill="none" stroke="#dfe4ea" stroke-width="2"/><path d="M1491 700 H1509 M1500 691 V709" fill="none" stroke="#dfe4ea" stroke-width="2"/>
+  <rect x="1018" y="228" width="242" height="44" fill="#fafaf8"/>
+  <text x="1035" y="258" text-anchor="start" font-family="Menlo, SFMono-Regular, monospace" font-size="20" font-weight="400" letter-spacing="1.8" fill="#3457d5">FIG.00 — RUNTIME</text>
+</g>
+    <g>
+  <rect x="1039" y="319" width="22" height="22" rx="6" fill="none" stroke="#161c24" stroke-width="3"/><rect x="1039" y="464" width="22" height="22" rx="6" fill="none" stroke="#161c24" stroke-width="3"/><rect x="1039" y="609" width="22" height="22" rx="6" fill="none" stroke="#161c24" stroke-width="3"/>
+  <g fill="none">
+  <defs><clipPath id="d-horizontal"><rect x="1172" y="337" width="156" height="276" rx="12"/></clipPath></defs>
+  <rect x="1165" y="330" width="170" height="290" rx="18" stroke="#161c24" stroke-width="3.5"/>
+  <g clip-path="url(#d-horizontal)" stroke="#69727d" stroke-width="2" opacity="0.85"><path d="M710 613 L986 337"/><path d="M710 337 L986 613"/><path d="M731 613 L1007 337"/><path d="M731 337 L1007 613"/><path d="M752 613 L1028 337"/><path d="M752 337 L1028 613"/><path d="M773 613 L1049 337"/><path d="M773 337 L1049 613"/><path d="M794 613 L1070 337"/><path d="M794 337 L1070 613"/><path d="M815 613 L1091 337"/><path d="M815 337 L1091 613"/><path d="M836 613 L1112 337"/><path d="M836 337 L1112 613"/><path d="M857 613 L1133 337"/><path d="M857 337 L1133 613"/><path d="M878 613 L1154 337"/><path d="M878 337 L1154 613"/><path d="M899 613 L1175 337"/><path d="M899 337 L1175 613"/><path d="M920 613 L1196 337"/><path d="M920 337 L1196 613"/><path d="M941 613 L1217 337"/><path d="M941 337 L1217 613"/><path d="M962 613 L1238 337"/><path d="M962 337 L1238 613"/><path d="M983 613 L1259 337"/><path d="M983 337 L1259 613"/><path d="M1004 613 L1280 337"/><path d="M1004 337 L1280 613"/><path d="M1025 613 L1301 337"/><path d="M1025 337 L1301 613"/><path d="M1046 613 L1322 337"/><path d="M1046 337 L1322 613"/><path d="M1067 613 L1343 337"/><path d="M1067 337 L1343 613"/><path d="M1088 613 L1364 337"/><path d="M1088 337 L1364 613"/><path d="M1109 613 L1385 337"/><path d="M1109 337 L1385 613"/><path d="M1130 613 L1406 337"/><path d="M1130 337 L1406 613"/><path d="M1151 613 L1427 337"/><path d="M1151 337 L1427 613"/><path d="M1172 613 L1448 337"/><path d="M1172 337 L1448 613"/><path d="M1193 613 L1469 337"/><path d="M1193 337 L1469 613"/><path d="M1214 613 L1490 337"/><path d="M1214 337 L1490 613"/><path d="M1235 613 L1511 337"/><path d="M1235 337 L1511 613"/><path d="M1256 613 L1532 337"/><path d="M1256 337 L1532 613"/><path d="M1277 613 L1553 337"/><path d="M1277 337 L1553 613"/><path d="M1298 613 L1574 337"/><path d="M1298 337 L1574 613"/><path d="M1319 613 L1595 337"/><path d="M1319 337 L1595 613"/><path d="M1340 613 L1616 337"/><path d="M1340 337 L1616 613"/><path d="M1361 613 L1637 337"/><path d="M1361 337 L1637 613"/><path d="M1382 613 L1658 337"/><path d="M1382 337 L1658 613"/><path d="M1403 613 L1679 337"/><path d="M1403 337 L1679 613"/><path d="M1424 613 L1700 337"/><path d="M1424 337 L1700 613"/><path d="M1445 613 L1721 337"/><path d="M1445 337 L1721 613"/><path d="M1466 613 L1742 337"/><path d="M1466 337 L1742 613"/><path d="M1487 613 L1763 337"/><path d="M1487 337 L1763 613"/><path d="M1508 613 L1784 337"/><path d="M1508 337 L1784 613"/><path d="M1529 613 L1805 337"/><path d="M1529 337 L1805 613"/><path d="M1550 613 L1826 337"/><path d="M1550 337 L1826 613"/><path d="M1571 613 L1847 337"/><path d="M1571 337 L1847 613"/><path d="M1592 613 L1868 337"/><path d="M1592 337 L1868 613"/><path d="M1613 613 L1889 337"/><path d="M1613 337 L1889 613"/><path d="M1634 613 L1910 337"/><path d="M1634 337 L1910 613"/></g>
+</g>
+  <g fill="none" stroke="#161c24" stroke-width="3">
+    <path d="M1062 330 C 1120 330 1128 400 1165 400"/>
+    <path d="M1062 475 H1165"/>
+    <path d="M1062 620 C 1120 620 1128 550 1165 550"/>
+    <path d="M1335 400 H1450 M1335 475 H1450 M1335 550 H1450"/>
+  </g>
+  <g fill="#3457d5"><circle cx="1456" cy="400" r="6.5"/><circle cx="1456" cy="475" r="6.5"/><circle cx="1456" cy="550" r="6.5"/></g>
+</g>
+    <text x="1250" y="745" text-anchor="middle" font-family="Menlo, SFMono-Regular, monospace" font-size="14" font-weight="400" letter-spacing="2" fill="#3457d5">ONE RUNTIME · MANY AGENTS</text>
+
+    <path d="M64 784 H1536" stroke="#dfe4ea" stroke-width="1.5"/>
+    <text x="64" y="822" text-anchor="start" font-family="Menlo, SFMono-Regular, monospace" font-size="13.5" font-weight="400" letter-spacing="1.5" fill="#69727d">AGENT TRELLIS — UNIFIED CODE AGENT RUNTIME</text>
+    <text x="1536" y="822" text-anchor="end" font-family="Menlo, SFMono-Regular, monospace" font-size="13.5" font-weight="400" letter-spacing="1.5" fill="#69727d">agent-trellis.dev</text>
+  </g>
+</svg>