agent-trellis 0.8.0 → 0.9.0

package/docs/assets/poster-series-v3/agent-trellis-poster-v3-unified-zh.svg

@@ -0,0 +1,51 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1440" height="1440" viewBox="0 0 1440 1440">
+  <rect width="1440" height="1440" fill="#fafaf8"/>
+  <g transform="translate(180 0)">
+    <g transform="translate(64 48) scale(0.56)" fill="none" stroke="#161c24" stroke-linecap="round">
+  <defs><clipPath id="v3-beam-64-48"><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-48)"><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="132" y="87" text-anchor="start" font-family="Helvetica Neue, PingFang SC, Arial, sans-serif" font-size="30" font-weight="700" letter-spacing="2.2" fill="#161c24">AGENT TRELLIS</text>
+    <text x="1016" y="87" text-anchor="end" font-family="Menlo, SFMono-Regular, monospace" font-size="19" font-weight="400" letter-spacing="1.7" fill="#69727d">RUNTIME / 01</text>
+    <path d="M64 142 H1016" stroke="#dfe4ea" stroke-width="1.5"/>
+    <rect x="64" y="138.5" width="52" height="3.5" fill="#3457d5"/>
+
+    <text x="96" y="232" text-anchor="start" font-family="Menlo, SFMono-Regular, monospace" font-size="22" font-weight="400" letter-spacing="2.2" fill="#3457d5">UNIFIED CODE AGENT RUNTIME</text>
+    <rect x="64" y="298" width="7" height="178" fill="#3457d5"/>
+    <text x="96" y="360" text-anchor="start" font-family="Helvetica Neue, PingFang SC, Arial, sans-serif" font-size="80" font-weight="800" letter-spacing="-1" fill="#161c24">一个 Runtime，</text><text x="96" y="458" text-anchor="start" font-family="Helvetica Neue, PingFang SC, Arial, sans-serif" font-size="80" font-weight="800" letter-spacing="-1" fill="#161c24">统一所有 Code Agent。</text>
+    <text x="96" y="524" text-anchor="start" font-family="Helvetica Neue, PingFang SC, Arial, sans-serif" font-size="35" font-weight="450" letter-spacing="0" fill="#69727d">从一个 canonical source 统一管理</text><text x="96" y="570" text-anchor="start" font-family="Helvetica Neue, PingFang SC, Arial, sans-serif" font-size="35" font-weight="450" letter-spacing="0" fill="#69727d">Skill、MCP、Memory 与共享指令。</text>
+
+    <g>
+  <rect x="64" y="650" width="952" height="480" fill="none" stroke="#dfe4ea" stroke-width="1.5"/>
+  <path d="M55 650 H73 M64 641 V659" fill="none" stroke="#dfe4ea" stroke-width="2"/><path d="M1007 650 H1025 M1016 641 V659" fill="none" stroke="#dfe4ea" stroke-width="2"/><path d="M55 1130 H73 M64 1121 V1139" fill="none" stroke="#dfe4ea" stroke-width="2"/><path d="M1007 1130 H1025 M1016 1121 V1139" fill="none" stroke="#dfe4ea" stroke-width="2"/>
+  <rect x="82" y="628" width="294" height="44" fill="#fafaf8"/>
+  <text x="99" y="658" text-anchor="start" font-family="Menlo, SFMono-Regular, monospace" font-size="20" font-weight="400" letter-spacing="1.8" fill="#3457d5">FIG.01 — AGENT PATHS</text>
+</g>
+    <g transform="translate(0 50)"><g>
+  <rect x="148" y="689" width="22" height="22" rx="6" fill="none" stroke="#161c24" stroke-width="3.5"/><rect x="148" y="799" width="22" height="22" rx="6" fill="none" stroke="#161c24" stroke-width="3.5"/><rect x="148" y="909" width="22" height="22" rx="6" fill="none" stroke="#161c24" stroke-width="3.5"/>
+  <text x="159" y="742" text-anchor="middle" font-family="Menlo, SFMono-Regular, monospace" font-size="17" font-weight="400" letter-spacing="1" fill="#69727d">CLAUDE</text><text x="159" y="852" text-anchor="middle" font-family="Menlo, SFMono-Regular, monospace" font-size="17" font-weight="400" letter-spacing="1" fill="#69727d">CODEX</text><text x="159" y="962" text-anchor="middle" font-family="Menlo, SFMono-Regular, monospace" font-size="17" font-weight="400" letter-spacing="1" fill="#69727d">KIMI</text>
+  <g fill="none">
+  <defs><clipPath id="d-unified"><rect x="447" y="707" width="186" height="206" rx="14"/></clipPath></defs>
+  <rect x="440" y="700" width="200" height="220" rx="20" stroke="#161c24" stroke-width="4"/>
+  <g clip-path="url(#d-unified)" stroke="#69727d" stroke-width="2" opacity="0.85"><path d="M27 913 L233 707"/><path d="M27 707 L233 913"/><path d="M48 913 L254 707"/><path d="M48 707 L254 913"/><path d="M69 913 L275 707"/><path d="M69 707 L275 913"/><path d="M90 913 L296 707"/><path d="M90 707 L296 913"/><path d="M111 913 L317 707"/><path d="M111 707 L317 913"/><path d="M132 913 L338 707"/><path d="M132 707 L338 913"/><path d="M153 913 L359 707"/><path d="M153 707 L359 913"/><path d="M174 913 L380 707"/><path d="M174 707 L380 913"/><path d="M195 913 L401 707"/><path d="M195 707 L401 913"/><path d="M216 913 L422 707"/><path d="M216 707 L422 913"/><path d="M237 913 L443 707"/><path d="M237 707 L443 913"/><path d="M258 913 L464 707"/><path d="M258 707 L464 913"/><path d="M279 913 L485 707"/><path d="M279 707 L485 913"/><path d="M300 913 L506 707"/><path d="M300 707 L506 913"/><path d="M321 913 L527 707"/><path d="M321 707 L527 913"/><path d="M342 913 L548 707"/><path d="M342 707 L548 913"/><path d="M363 913 L569 707"/><path d="M363 707 L569 913"/><path d="M384 913 L590 707"/><path d="M384 707 L590 913"/><path d="M405 913 L611 707"/><path d="M405 707 L611 913"/><path d="M426 913 L632 707"/><path d="M426 707 L632 913"/><path d="M447 913 L653 707"/><path d="M447 707 L653 913"/><path d="M468 913 L674 707"/><path d="M468 707 L674 913"/><path d="M489 913 L695 707"/><path d="M489 707 L695 913"/><path d="M510 913 L716 707"/><path d="M510 707 L716 913"/><path d="M531 913 L737 707"/><path d="M531 707 L737 913"/><path d="M552 913 L758 707"/><path d="M552 707 L758 913"/><path d="M573 913 L779 707"/><path d="M573 707 L779 913"/><path d="M594 913 L800 707"/><path d="M594 707 L800 913"/><path d="M615 913 L821 707"/><path d="M615 707 L821 913"/><path d="M636 913 L842 707"/><path d="M636 707 L842 913"/><path d="M657 913 L863 707"/><path d="M657 707 L863 913"/><path d="M678 913 L884 707"/><path d="M678 707 L884 913"/><path d="M699 913 L905 707"/><path d="M699 707 L905 913"/><path d="M720 913 L926 707"/><path d="M720 707 L926 913"/><path d="M741 913 L947 707"/><path d="M741 707 L947 913"/><path d="M762 913 L968 707"/><path d="M762 707 L968 913"/><path d="M783 913 L989 707"/><path d="M783 707 L989 913"/><path d="M804 913 L1010 707"/><path d="M804 707 L1010 913"/><path d="M825 913 L1031 707"/><path d="M825 707 L1031 913"/><path d="M846 913 L1052 707"/><path d="M846 707 L1052 913"/><path d="M867 913 L1073 707"/><path d="M867 707 L1073 913"/></g>
+</g>
+  <g fill="none" stroke="#161c24" stroke-width="3.5">
+    <path d="M171 700 C 290 700 320 762 440 762"/>
+    <path d="M171 810 H440"/>
+    <path d="M171 920 C 290 920 320 858 440 858"/>
+    <path d="M640 762 H920 M640 810 H920 M640 858 H920"/>
+  </g>
+  <g fill="#3457d5"><circle cx="926" cy="762" r="8"/><circle cx="926" cy="810" r="8"/><circle cx="926" cy="858" r="8"/></g>
+</g></g>
+    <text x="540" y="1088" text-anchor="middle" font-family="Menlo, SFMono-Regular, monospace" font-size="22" font-weight="400" letter-spacing="2" fill="#3457d5">ONE RUNTIME · MANY AGENTS</text>
+
+    <text x="64" y="1198" text-anchor="start" font-family="Menlo, SFMono-Regular, monospace" font-size="19" font-weight="400" letter-spacing="1.6" fill="#69727d">SKILLS · MCP · MEMORY · INSTRUCTIONS</text>
+    <text x="1016" y="1198" text-anchor="end" font-family="Menlo, SFMono-Regular, monospace" font-size="19" font-weight="400" letter-spacing="1.6" fill="#69727d">agent-trellis.dev</text>
+    <path d="M64 1232 H1016" stroke="#161c24" stroke-width="3.5"/>
+    <circle cx="77" cy="1294" r="7" fill="#3457d5"/>
+    <text x="108" y="1304" text-anchor="start" font-family="Menlo, SFMono-Regular, monospace" font-size="32" font-weight="500" letter-spacing="0.2" fill="#161c24">$ npm i -g agent-trellis</text>
+    <text x="1016" y="1304" text-anchor="end" font-family="Menlo, SFMono-Regular, monospace" font-size="18" font-weight="400" letter-spacing="1.5" fill="#69727d">OPEN SOURCE / LOCAL FIRST</text>
+  </g>
+</svg>

package/docs/getting-started.md

@@ -15,7 +15,7 @@ npm install -g agent-trellis
 $ trellis onboard
 ```
 
-Runs `init`, detects which of Claude Code/Codex/Kiro/pi/Kimi Code are on this machine,
+Runs `init`, detects which of Claude Code/Codex/Kiro/pi/Kimi Code/ZCode are on this machine,
 then resolves two styled interactive choices and two flag-only ones before running
 `migrate`, `sync`, `mcp sync`, `memory sync`, `secrets audit`, and a final
 health scan — the whole onboarding path, no follow-up commands to type by
@@ -266,6 +266,31 @@ enabled. Runtime correctness does not depend on that optimization. Native
 Kimi delivery remains available with `native` or `both`; those modes do not
 use the empty Skill-root launcher.
 
+## ZCode Runtime-first
+
+ZCode is supported as `zcode`. Trellis selects one native profile before it
+writes anything: the official CLI/Desktop profile uses
+`~/.zcode/cli/config.json`; the locally installed `zcode-app-cli` profile
+uses `~/.zcode/cli/setting.json`. Both store servers under `mcp.servers`.
+
+Selecting ZCode during `trellis onboard` defaults it to Runtime delivery.
+`trellis sync` links shared instructions at `~/.zcode/AGENTS.md` and disables
+native ZCode Skill discovery while Runtime-only delivery is active. This keeps
+ZCode's automatic `~/.agents/skills` scan from bypassing canonical Skill
+scope. `trellis mcp sync` writes the single owned `trellis` stdio entry;
+Skill, Memory, and eligible upstream MCP servers are then served through
+`trellis mcp-runtime --agent zcode`.
+
+Native or `both` delivery remains available through a capability-selection
+file. When leaving Runtime-only mode, Trellis restores ZCode's previous native
+Skill settings only when they still equal the values it wrote. User edits and
+unrelated ZCode MCP entries remain untouched.
+
+For chat or Agent delegation, Trellis uses only a public `zcode` executable
+that advertises `--prompt`, `--resume`, and `--output-format`. A desktop-only
+profile can still receive managed configuration; Trellis never launches the
+desktop application's private helper or bundled runtime path.
+
 ## Trellis Runtime Skill
 
 `trellis-runtime` is the built-in operating guide that Trellis installs into
@@ -325,7 +350,7 @@ content back into canonical Markdown remains an explicit
 
 ## Two starting points
 
-**You already use one or more of Claude Code, Codex, Kiro, pi, or Kimi Code** and have
+**You already use one or more of Claude Code, Codex, Kiro, pi, Kimi Code, or ZCode** and have
 real skills/instructions in them today. Go to
 [Migrating from an existing agent](#migrating-from-an-existing-agent).
 
@@ -353,7 +378,7 @@ Creates `~/.trellis/` with:
 `~/.trellis/` that already exists just fills in whatever's still missing —
 safe to run again any time, including after you've hand-edited things.
 
-It then prints which of the five supported agents it found on this machine.
+It then prints which of the six supported agents it found on this machine.
 For each one **not** found, it prints that agent's real install command or
 download link — `trellis init` never runs an installer itself; a global
 package install or an IDE download is your call to make, not a silent side
@@ -374,7 +399,7 @@ migrate --from claude-code
   [conflict] instructions — canonical agents.md already has different real content — resolve by hand
 ```
 
-`--from` accepts `claude-code`, `codex`, `kiro`, `pi`, or `kimi-code`. Run it once per
+`--from` accepts `claude-code`, `codex`, `kiro`, `pi`, `kimi-code`, or `zcode`. Run it once per
 agent you actually use — it's independent per agent, order doesn't matter.
 
 Add `--dry-run` to see the plan without writing anything:
@@ -547,15 +572,18 @@ to set up before moving on to `sync`.
 The same applies to MCP servers — `~/.trellis/mcp/servers.yaml` can be
 hand-authored the same way (see
 [`schema/servers.example.yaml`](../schema/servers.example.yaml) for the
-full shape), or use `trellis mcp add` (below). Either way, move on to
-[`trellis mcp sync`](#trellis-mcp-sync) once you've added what you want.
+full shape), or use `trellis mcp add` (below) — the CLI command syncs
+for you; hand-authored edits still need a following
+[`trellis mcp sync`](#trellis-mcp-sync) of their own.
 
 ## `trellis skill` / `trellis mcp` — canonical CRUD via the CLI
 
 An alternative to hand-editing canonical files directly — useful for
 scripting, or when you'd rather not open a text editor for a one-line
-change. Both commands are canonical-side only: they never touch any
-agent's native config (that stays `sync`/`mcp sync`'s job).
+change. `add`/`remove`/`import` mutate the canonical source and then run the
+same sync `sync`/`mcp sync` performs, so one command both edits the list and
+maps it onto the managed agents; `--dry-run` previews the whole thing,
+including the sync plan, with zero writes. `list` is read-only.
 
 ```
 $ trellis skill list
@@ -586,6 +614,74 @@ trellis skill update-builtin
 The update is backed up and updates the canonical file in place; native Agent
 symlinks and Runtime providers then consume the same refreshed content.
 
+### Importing a GitHub Skill with Trellis ownership
+
+If you would normally run `npx skills add`, use Trellis's top-level `add`
+command instead. It is a remote-source importer, while `trellis skill add`
+remains the command for a local directory:
+
+```sh
+# Review exact-case SKILL.md candidates before selecting one.
+npx trellis add mattpocock/skills --list
+
+# Fetch and inspect the exact plan without writing canonical or Agent files.
+npx trellis add mattpocock/skills --skill loop-me --dry-run
+
+# Import to the user-level canonical store, then sync to every managed Agent.
+npx trellis add mattpocock/skills --skill loop-me --yes
+```
+
+The source may be `owner/repository` or a credential-free HTTPS
+`github.com` repository URL. Trellis fetches the selected ref into a system
+temporary directory, discovers a directory containing an exact-case
+`SKILL.md`, and copies that directory into
+`~/.trellis/skills/<name>/`. It does not run repository scripts, install
+dependencies, or write into `.agents/skills`, `~/.agents/skills`, or any
+Agent-specific Skill directory during import. Review the imported
+`SKILL.md` before relying on it in an Agent session.
+
+By default the imported Skill is unscoped, which means every Agent currently
+listed in `~/.trellis/managed.yaml` receives it on sync. Restrict delivery to
+managed Agents with `--agent`; comma-separated values and repeated flags are
+accepted. `--agent '*'` writes the current managed set as an explicit scope.
+An Agent that is installed but unmanaged is refused before any canonical or
+native write. Add it to Trellis's managed boundary first:
+
+```sh
+trellis manage add zcode
+npx trellis add mattpocock/skills --skill loop-me --agent zcode --yes
+```
+
+`--branch <ref>` selects a Git branch, tag, or ref. Without it, Trellis asks
+Git for the repository's default branch. `--global` is accepted for
+`skills`-CLI compatibility and still means Trellis's existing user-level
+canonical store; `--copy` and project-local modes are refused because they
+would create another Skill source outside Trellis.
+
+Each successful remote import writes
+`~/.trellis/skills.lock.json` in the same backup session as its canonical
+Skill directory. The lock records the normalized GitHub URL, requested ref,
+resolved immutable commit, source subdirectory, and deterministic content
+digest. It never records credentials or a temporary path. `trellis skill
+list` marks remote Skills with their source and short locked commit; JSON
+output includes the complete credential-free provenance record.
+
+Refresh tracked Skills with:
+
+```sh
+trellis update loop-me --dry-run
+trellis update loop-me
+trellis update                 # check every tracked remote Skill
+```
+
+Before replacement, `trellis update` compares the current canonical directory
+to its locked digest. A local canonical edit is a conflict and is never
+overwritten. A successful update preserves the Skill's scope, replaces its
+directory and provenance record in one backup session, and then runs Skill
+sync. Use `trellis rollback --list` to find a `remote-skill-add` or
+`remote-skill-update` run; rolling it back restores the previous directory
+and matching lock record when neither has changed since the run.
+
 ```
 $ trellis mcp list
 tanka (http) — codex, pi
@@ -939,7 +1035,7 @@ periodically regardless.
 $ trellis doctor
 ```
 
-Read-only. Scans all five agents' current state and reports drift —
+Read-only. Scans all six agents' current state and reports drift —
 mismatched skill content across agents, wrong-case skill files, and (with
 `--probe-mcp`) whether each configured MCP server actually handshakes.
 Safe to run any time; nothing here writes anything.
@@ -984,9 +1080,10 @@ scripts/agent-sandbox.sh --status kiro
 Git，也不会自动读取或删除宿主机凭据。清理时请明确执行
 `docker volume rm <volume-name>`。
 
-## `trellis rollback` — undoing a `sync`/`mcp sync`/`onboard` run
+## `trellis rollback` — undoing a managed write run
 
-Every real write those three commands perform is recorded, before it
+Every real `sync`, `mcp sync`, `onboard`, remote Skill import, and remote Skill
+update write is recorded, before it
 happens, to a structured run directory under `~/.trellis/backups/` — no
 flag needed, this is always on for any run that actually writes
 something. `--dry-run` never creates one, since nothing was written.
@@ -1028,6 +1125,127 @@ created file under `~/.trellis/skills/`.
 `~/.trellis/backups/` has no automatic pruning — delete old run
 directories by hand once you're done with them.
 
+## GUI: chat with a managed/CLI Agent (`@trellis/gui`)
+
+The desktop app (`packages/gui/`) has a "Chat" tab for a real multi-turn
+conversation with any CLI Agent you configure, streamed live with a
+typewriter effect and tool-call/tool-result bubbles when the target
+supports it. This is separate from `agent-bridge.yaml` (used for one-shot
+cross-Agent delegation via MCP tools): a chat target is identified by an
+arbitrary string, not one of the five fully-managed Agents, so you can
+point it at any non-interactive CLI without onboarding it as a full
+managed Agent.
+
+Configure targets in `~/.trellis/mcp/chat-agents.yaml` (absent by
+default — nothing is spawned until you write one):
+
+```yaml
+targets:
+  claude-code:
+    label: "Claude Code"
+    command: claude
+    args: ["-p", "{prompt}", "--output-format", "stream-json"]
+    outputFormat: stream-json
+  qoder:
+    label: "Qoder"
+    command: qoder
+    args: ["-p", "{prompt}", "--output-format", "stream-json"]
+    resumeArgs: ["-p", "{prompt}", "--output-format", "stream-json", "--session-id", "{sessionId}"]
+    outputFormat: stream-json
+    tags: ["domestic"]
+  kimi-code:
+    label: "Kimi Code"
+    command: kimi
+    args: ["-p", "{prompt}", "--output-format", "stream-json"]
+    resumeArgs: ["-p", "{prompt}", "--output-format", "stream-json", "-S", "{sessionId}"]
+    outputFormat: stream-json
+    tags: ["domestic"]
+  minimax-code:
+    label: "MiniMax Code"
+    command: mcode
+    args: ["exec", "{prompt}", "--output-format", "stream-json"]
+    resumeArgs: ["exec", "{prompt}", "--output-format", "stream-json", "--session", "{sessionId}"]
+    outputFormat: stream-json
+    tags: ["domestic"]
+  zcode:
+    label: "ZCode"
+    command: zcode
+    args: ["--prompt", "{prompt}", "--output-format", "stream-json"]
+    resumeArgs: ["--resume", "{sessionId}", "--prompt", "{prompt}", "--output-format", "stream-json"]
+    outputFormat: stream-json
+    streamProtocol: zcode
+    tags: ["z-ai"]
+```
+
+- `outputFormat: stream-json` gets structured tool-call/tool-result
+  bubbles, but only for Claude Code's documented shape (there's no
+  official schema for it — see upstream issue #24612 — so this is a
+  best-effort parse of the community-documented format; other CLIs using
+  the same flag name show their raw output instead of guessing at a
+  format that hasn't been verified against a real install).
+- Every message requires confirming a one-time-per-session banner showing
+  the exact command that will run — it spawns a real subprocess, possibly
+  a real billed API call.
+- Chat history is **never written to disk** — it may contain real code or
+  secrets. Closing the app loses it, on purpose.
+
+### Domestic CLI status (what's real, what isn't)
+
+- **Qoder**: installed for real (`npm install -g @qoder-ai/qodercli`) and
+  checked directly against `qoder --help` — `-p`/`--print`, `-o`/
+  `--output-format text|json|stream-json`, and `--session-id <id>` (resume)
+  all confirmed as real flags. Ran `qoder -p "test" -o stream-json` for
+  real, unauthenticated (`qoder status` → "Not logged in"), which failed
+  cleanly and immediately on the auth check (`total_cost_usd: 0`, zero
+  real spend) — and its `stream-json` output turned out to already match
+  Claude Code's documented shape line-for-line (`{"type":"system",
+  "subtype":"init",...}` → `{"type":"assistant","message":{"content":
+  [{"type":"text",...}]}}` → `{"type":"result","subtype":"success",...}`),
+  so this app's existing `tryParseClaudeStreamJsonLine` parser produces
+  real tool-call/tool-result bubbles for Qoder too, not just raw text —
+  confirmed for the `init`/text/`result` shapes; the `tool_use`/
+  `tool_result` shapes specifically weren't independently observed (the
+  call never got far enough to use a tool before failing on auth). The
+  `--session-id` resume combination itself (an actual resumed call) was
+  not exercised — that needs a real logged-in account.
+- **Kimi Code**: `-p`/`--prompt`, `--output-format text|stream-json`, and
+  `-S`/`--session [id]` are confirmed directly from a real, installed
+  `kimi --help` on the machine this was built on. The `-p` + `-S`
+  combination for resuming a session non-interactively is documented as
+  separate top-level flags but wasn't exercised against a real resumed
+  call (that would be a real, billed API call, and this install has a
+  live authenticated session — `kimi provider list` shows a real
+  `managed:kimi-code` OAuth provider) — verify once before relying on it
+  for anything important.
+- **MiniMax Code** (`mcode`): installed for real (`npm install -g
+  @minimax-ai/code`) and checked directly against `mcode exec --help`,
+  which — unlike what first-party prose docs implied — does document
+  both `--output-format text|json|stream-json` and a `--session <id>`
+  resume flag (distinct spelling from Qoder's `--session-id`) as real
+  `exec` options. Ran `mcode exec "test" --output-format stream-json` for
+  real, unauthenticated (no `~/.minimax-code` config exists on this
+  machine), which failed cleanly with a plain-text "Sign in to MiniMax…"
+  message before entering the agent loop — so unlike Qoder, no real
+  `stream-json` line was ever actually observed for MiniMax Code; if its
+  JSON shape turns out to differ from Claude Code's, lines simply
+  degrade to the raw-chunk fallback rather than breaking anything, but
+  treat the *existence* of the flags as confirmed and their *exact wire
+  shape* as still unconfirmed. The `--session` resume combination was
+  not exercised for the same reason as Qoder's.
+- **ZCode** (Z.ai / 智谱, `zcode`) is supported when its public CLI probe
+  confirms `--prompt`, `--resume`, and `--output-format`. Its stream result
+  uses `response` and `sessionId`, so configure `streamProtocol: zcode` as
+  shown above. The installed `zcode-app-cli` is a community distribution over
+  the ZCode runtime; it uses `~/.zcode/cli/setting.json`. The official
+  open-source CLI/Desktop profile uses `~/.zcode/cli/config.json`. A
+  desktop-only profile is configuration-manageable but is not offered as a
+  chat or delegation executor.
+- **Trae is not supported yet.** The commercial Trae IDE (trae.ai) has no
+  documented non-interactive CLI mode; the separate open-source
+  `bytedance/trae-agent` project's `trae-cli run` streaming output format
+  has not been verified against a real install. Neither is configured —
+  don't add a `trae` target expecting it to work.
+
 ## Troubleshooting
 
 - **A `conflict` I don't understand**: `migrate` and `sync` both name the
@@ -1038,6 +1256,18 @@ directories by hand once you're done with them.
   the same real config files/directories `init`/`migrate`/`sync` do; if an
   agent's config lives somewhere non-standard on your machine, that's worth
   filing an issue with the exact path.
-- Other known limitations are tracked honestly in
-  [README's Status section](../README.md#status) — read that before
-  assuming something is a bug rather than a documented gap.
+- Other known limitations, named honestly rather than discovered the hard way:
+  - `mcp sync`/`sync` never spawn or handshake-test MCP servers — they only
+    guarantee the *config* is written correctly. `trellis doctor --probe-mcp`
+    is the one command that actually connects, and it's opt-in.
+  - The pi bridge extension (`trellis-pi-mcp-bridge`) is verified to load and
+    register tools without erroring, not against a real LLM tool call in
+    production.
+  - Verification runs in isolated Docker containers with real agent installs,
+    not against a developer's daily-use dotfiles — if you hit something a
+    clean-room sandbox wouldn't catch, please open an issue.
+  - `onboard` picks one agent as the migration base when several are present;
+    merging differing content across multiple agents into one result is
+    future work, not built yet.
+  - `~/.trellis/backups/` has no automatic pruning — every write adds a run
+    directory; delete old ones by hand.

package/docs/overview.md

@@ -4,11 +4,11 @@
 
 ## One-line description
 
-> Trellis is a unified Code Agent Runtime for managing Skills, MCP, Memory, and shared instructions across Claude Code, Codex, Kiro, pi, and Kimi Code.
+> Trellis is a unified Code Agent Runtime for managing Skills, MCP, Memory, and shared instructions across Claude Code, Codex, Kiro, pi, Kimi Code, and ZCode.
 
 中文定位：
 
-> Trellis 是统一的 Code Agent Runtime，为 Claude Code、Codex、Kiro、pi 和 Kimi Code 统一管理 Skill、MCP、Memory 与共享指令。
+> Trellis 是统一的 Code Agent Runtime，为 Claude Code、Codex、Kiro、pi、Kimi Code 和 ZCode 统一管理 Skill、MCP、Memory 与共享指令。
 
 ## Quick start
 
@@ -52,10 +52,12 @@ The importer de-duplicates existing servers, extracts environment credentials in
 
 ## Architecture
 
-![Agent Trellis architecture](assets/agent-trellis-architecture-horizontal.svg)
+![Agent Trellis — One Runtime. Every Code Agent.](assets/poster-series-v3/agent-trellis-poster-v3-horizontal-en.png)
 
 The overview shows the product boundary: Trellis is the control plane in the center; Skills, MCP, Memory, and Instructions are managed capability sources; Agents consume the resulting native or Runtime views.
 
+Brand and social assets, including the poster series, live in [`docs/assets/poster-series-v3/`](assets/poster-series-v3/README.md).
+
 ```mermaid
 flowchart LR
     Sources["Trellis Canonical Source\n~/.trellis"]
@@ -77,6 +79,7 @@ flowchart LR
     Native --> Kiro["Kiro"]
     Native --> Pi["pi"]
     Edge --> Kimi["Kimi Code"]
+    Edge --> ZCode["ZCode"]
     Edge --> Claude
     Edge --> Pi
 ```

package/docs/overview.zh-CN.md

@@ -4,7 +4,7 @@
 
 ## 一句话介绍
 
-> Trellis 是统一的 Code Agent Runtime，为 Claude Code、Codex、Kiro、pi 和 Kimi Code 统一管理 Skill、MCP、Memory 与共享指令。
+> Trellis 是统一的 Code Agent Runtime，为 Claude Code、Codex、Kiro、pi、Kimi Code 和 ZCode 统一管理 Skill、MCP、Memory 与共享指令。
 
 ## 快速开始
 
@@ -48,7 +48,7 @@ trellis mcp import ~/Desktop/mcp-servers.json
 
 ## 架构
 
-![Agent Trellis 架构](assets/agent-trellis-architecture-vertical.svg)
+![Agent Trellis — 一个 Runtime，统一所有 Code Agent。](assets/poster-series-v3/agent-trellis-poster-v3-horizontal-zh.png)
 
 Trellis 以 `~/.trellis/` 为 canonical source，在中心统一管理四类能力：
 
@@ -59,6 +59,8 @@ Trellis 以 `~/.trellis/` 为 canonical source，在中心统一管理四类能
 
 这些能力通过 native adapter 或 Runtime/Gateway 投递给不同的 Code Agent。
 
+品牌与社媒海报资源见 [`docs/assets/poster-series-v3/`](assets/poster-series-v3/README.md)，包含竖版（手机端）与横版（桌面端）海报的中英文版本。
+
 ```text
 ~/.trellis/ canonical source
         │
@@ -66,7 +68,7 @@ Trellis 以 `~/.trellis/` 为 canonical source，在中心统一管理四类能
 Trellis Runtime / Gateway
         │
         ├── Native adapters ── Claude Code / Codex / Kiro / pi
-        └── MCP Runtime ────── Kimi Code / 其他 Runtime-first Agent
+        └── MCP Runtime ────── Kimi Code / ZCode / 其他 Runtime-first Agent
 ```
 
 ## 与相似产品的关系

package/docs/roadmap.md

@@ -939,7 +939,7 @@ tests passing.
 | P7 | ✅ Secrets/env management: shared `resolveSecretEnv` + `secrets.policy.yaml`'s `env_file`, pi bridge stops reading raw ambient env, `secrets audit` gains a `missing-env-value` check | P3, P4 |
 | P8 | ✅ Kiro `${VAR}` fix: adapter also manages `kiroAgent.mcpApprovedEnvVars`, without which Kiro silently never substitutes any env reference Trellis writes | P2 |
 | P9 | ✅ MCP transport/auth expansion: `headers` field for static bearer/API-key remote auth (Claude Code/Codex/Kiro/pi bridge, each via its own real schema), `sse` transport; real OAuth flows explicitly delegated to each agent's own native support, not reimplemented | P2, P4, P8 |
-| P10 | GUI: evaluate embedding into mcp-router's or skills-hub's existing interface before building anything new | P3–P9 |
+| P10 | ✅ GUI: decided against embedding into an existing dashboard — `@trellis/gui` (Tauri v2 + React, `openspec/changes/trellis-gui/`) is an independent read-write desktop app whose Node sidecar imports `agent-trellis`'s internal command modules directly (workspace-relative, not the read-only `@trellis/sdk` barrel) and reuses the exact same plan/confirm/backup mechanics the CLI already has. Sidecar core, all read/write endpoints (including the `mcp add`/`mcp remove`/`skill add`/`skill remove` backup-tracking gap this work found and fixed — see P5's own SDK note below, a `agent-trellis`-wide fix, not GUI-only), live file-watch + WebSocket updates, macOS binary packaging, Tauri `externalBin` spawning, the React read/write views, MCP import, the real brand mark, and a real ad-hoc-signed `.dmg` (`npx tauri build`, release) are all built and verified (real HTTP/WS integration tests throughout, plus real headless-DOM tests of the write-confirmation and import flows). Also added: a "Chat" tab for real multi-turn streaming conversation with any configured CLI Agent (typewriter effect, tool-call/tool-result bubbles for Claude Code's `stream-json` shape, one-time-per-session confirmation, in-memory-only history — never persisted, since it may carry secrets), built on `trellis-agent-bridge`'s delegated-call primitive upgraded to stream (`runDelegatedCallStreaming`). Domestic-CLI coverage researched and documented per-CLI rather than assumed uniform, then upgraded from doc-only to `--help`-confirmed once Qoder and MiniMax Code were actually installed (`npm install -g @qoder-ai/qodercli @minimax-ai/code`, both verified as the real official packages first): Qoder, Kimi Code, and MiniMax Code all ship verified starter configs with `stream-json` output and session-resume flags — Qoder's `stream-json` shape was confirmed byte-identical to Claude Code's by actually running it (zero cost: it failed cleanly on an unauthenticated status check before reaching a model), while MiniMax Code's flags are confirmed real but its exact `stream-json` line shapes are not (same zero-cost auth-failure situation, but the call never got as far as producing one). ZCode (Z.ai/智谱) and Trae are both explicitly **not** shipped — real products, but no documented non-interactive CLI mode was found for either's official binary after checking their own docs/`--help` (don't confuse ZCode with the similarly-named but unofficial and different `zcode-cli` forks, which do document prompt flags but aren't the product being asked about). Also added: a real demo sandbox (`/tmp/trellis-gui-sandbox`) populated with real MCP servers/Skills/Memory files, and English/Chinese UI support (hand-rolled `I18nProvider`/`useI18n()`, no new runtime dependency — every view's UI chrome is translated, real backend data like agent ids/paths/commands never is, language persisted to `localStorage`). Ships as an ad-hoc-signed `.dmg`, accepted as the final distribution state — full Apple Developer ID signature + notarization was assessed and explicitly deprioritized (not a code gap, and not worth the credential/process overhead for this release) | P3–P9 |
 | P11 | ✅ Migrate category selection: `--only skills\|instructions` on `migrate`, same interactive picker `onboard` already uses | P1 |
 | P12 | ✅ Canonical CRUD via CLI: `trellis skill add/remove/list`, `trellis mcp add/remove/list` | P1, P2 |
 | P13 | ✅ Sandbox verification against this machine's real, structurally-relevant state (not just fixtures); every agent verified as both migrate source and sync/mcp-sync target | P0–P2 |
@@ -959,6 +959,7 @@ tests passing.
 | P26 | ✅ Fine-grained capability selection: item-level skill/MCP/memory selection from a serializable selection file or searchable TUI, per-agent MCP route overrides with direct/gateway/hub precedence, selected-memory sync without implicit native-memory import, and explicit unsupported-reader diagnostics | P17, P21, P22, P25 |
 | P27 | 🚧 Trellis MCP Runtime phase 1 ✅: one provider registry and agent-facing MCP edge; SkillProvider and the read-only CanonicalMemoryProvider expose scoped progressive-disclosure tools/resources, runtime delivery supports native/mcp/both per agent, selected upstream tools mount through the existing GatewayBackend, and doctor checks runtime drift. Remaining: upstream resource/prompt backend, real pi/Kiro model smoke, and real Claude model smoke (Claude remains intentionally deferred) | P21, P25, P26 |
 | P28 | 🚧 Kimi Code Runtime-first adapter: Kimi is recognized as a managed Agent, receives one deferred `trellis` Runtime entry in `~/.kimi-code/mcp.json`, and `trellis kimi` isolates native Skill discovery for Runtime-only delivery. The Runtime Skill is available through SkillProvider; remaining: real Kimi model-session smoke and upstream resource/prompt consumption | P27 |
+| P29 | ✅ ZCode Runtime-first adapter: `zcode` is a managed Agent with profile-aware static configuration (`~/.zcode/cli/config.json` for official profiles and `setting.json` for the local community CLI), a single owned Runtime MCP entry, scoped-Skill isolation, safe instruction/MCP migration, doctor/onboarding coverage, and public-CLI chat/delegation parsing for ZCode's `response`/`sessionId` stream envelope. Desktop-private runtime paths are never process-host entry points. | P27, P28 |
 
 **Cross-machine / cloud sharing — confirmed future direction, not yet
 scoped as a phase.** Surveyed 2026-09-15 (`docs/research.md`'s "Cross-

package/docs/video/README.md

@@ -0,0 +1,76 @@
+# Trellis 分享视频 · 素材与录制清单
+
+> 本目录（`docs/video/`）在 `.gitignore` 中，所有内容只存在于本地，
+> 不会进入开源仓库。
+
+## 自动生成视频
+
+```bash
+node docs/video/generate-video.mjs   # 输出 docs/video/trellis-demo-video.mp4
+```
+
+一条命令完成：重置沙盒 → 真实跑一遍 CLI 并捕获输出 → 渲染终端帧与卡片
+（qlmanage）→ 系统 TTS 生成中文口播（Ting-Ting Enhanced）→ ffmpeg 合成
+1920×1080 mp4。改口播文案直接编辑脚本里的 `blocks[].narration`；终端帧
+内容来自真实命令输出，无需手改。依赖：ffmpeg（`brew install ffmpeg`）、
+macOS 自带的 qlmanage/sips/say/afinfo。
+
+## 演示沙盒（不碰真实配置）
+
+```bash
+bash scripts/video-demo-setup.sh        # 生成/重置演示环境到 /tmp/trellis-demo-home
+export HOME=/tmp/trellis-demo-home      # 之后所有 trellis 命令都在沙盒里运行
+```
+
+沙盒内容：Claude Code（1 份指令 + 2 个 Skill + 2 个 MCP 服务器）、
+Codex（config.toml + 1 个 MCP 服务器）。每次重录前重跑 setup 脚本即可
+回到初始状态。已验证全流程可跑通：`init → onboard --dry-run → onboard →
+doctor → rollback`。
+
+录制用命令（已跳过交互选择，流程不打断）：
+
+```bash
+trellis init
+trellis onboard --dry-run --agent claude-code --manage codex
+trellis onboard --agent claude-code --manage codex
+trellis doctor
+trellis rollback
+```
+
+## 终端与录屏设置
+
+| 项 | 建议 |
+|---|---|
+| 终端主题 | 浅色（手机端观看对比度更好） |
+| 字号 | 20–24pt，观众多用手机看 |
+| 提示符 | `export PS1='$ '`，干净无干扰 |
+| 窗口 | 1280×720 或 1440×810 逻辑分辨率 |
+| 录屏 | Kap / QuickTime；每条 take 前 `clear` |
+| 导出 | 横屏 1920×1080（B 站/YouTube）；竖屏 1080×1920（视频号/小红书）则后期裁切，注意命令别超出安全区 |
+
+## 分镜与素材对照
+
+| 场景 | 画面 | 素材 |
+|---|---|---|
+| 1 开场 | 终端/编辑器随意状态 | 现场录 |
+| 2 痛点 | `ls ~/.claude` `ls ~/.codex`（真实目录，只读） | 现场录 |
+| 3 方案 | 海报全屏 | [`../assets/poster-series-v3/agent-trellis-poster-v3-unified-zh.png`](../assets/poster-series-v3/agent-trellis-poster-v3-unified-zh.png) |
+| 4 演示 | 终端实录 | 沙盒命令（见上） |
+| 5 设计点 | README Design principles 滚动 | github.com/paul-leo/Trellis |
+| 6 收尾 | GitHub 仓库首页 + Star 按钮停留 2 秒 | 同上 |
+
+## 其他可用素材
+
+- 封面图/片尾卡：[`../assets/poster-series-v3/agent-trellis-poster-v3-horizontal-zh.png`](../assets/poster-series-v3/agent-trellis-poster-v3-horizontal-zh.png)
+- Logo 叠层（角标）：[`../assets/brand-v3/trellis-mark-v3-a.svg`](../assets/brand-v3/trellis-mark-v3-a.svg)
+- 口播逐字稿：[voiceover.zh-CN.md](voiceover.zh-CN.md)
+- 场景大纲：[outline.zh-CN.md](outline.zh-CN.md)
+- 60 秒极简版：见 [outline.zh-CN.md](outline.zh-CN.md) 末尾
+
+## 录制前 Checklist
+
+- [ ] 重跑 `bash scripts/video-demo-setup.sh` 重置沙盒
+- [ ] `export HOME=/tmp/trellis-demo-home && export PS1='$ ' && clear`
+- [ ] 终端字号调大，关闭通知（勿扰模式）
+- [ ] 预演一遍场景 4，确认输出与口播一致
+- [ ] 麦克风电平测试 5 秒