agent-trellis 0.7.0 → 0.8.2

package/docs/overview.md

@@ -0,0 +1,134 @@
+# Trellis
+
+[English](overview.md) · [简体中文](overview.zh-CN.md)
+
+## One-line description
+
+> 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 和 ZCode 统一管理 Skill、MCP、Memory 与共享指令。
+
+## Quick start
+
+### Install
+
+```bash
+npm install -g agent-trellis
+```
+
+### Onboard an existing machine
+
+Preview first:
+
+```bash
+trellis onboard --dry-run
+```
+
+Apply after reviewing the source Agent, managed Agents, MCP mode, and Memory choice:
+
+```bash
+trellis onboard
+```
+
+### Inspect and verify
+
+```bash
+trellis doctor
+trellis secrets audit
+trellis sync --dry-run
+trellis mcp sync --dry-run
+```
+
+### Import an MCP Router export
+
+```bash
+trellis mcp import ~/Desktop/mcp-servers.json --dry-run
+trellis mcp import ~/Desktop/mcp-servers.json
+```
+
+The importer de-duplicates existing servers, extracts environment credentials into the ignored local secret file, converts supported `mcp-remote` Basic Auth entries to native HTTP MCP, and skips unavailable legacy paths.
+
+## Architecture
+
+![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"]
+    Sources --> Skills["Skills\nSKILL.md"]
+    Sources --> MCP["MCP\nservers.yaml"]
+    Sources --> Memory["Memory\nMarkdown / optional graph"]
+    Sources --> Instructions["Instructions\nagents.md"]
+
+    Skills --> Runtime["Trellis Runtime\nprovider registry + policy"]
+    MCP --> Runtime
+    Memory --> Runtime
+    Instructions --> Runtime
+
+    Runtime --> Native["Native adapters\nsymlink / JSON / TOML / bridge"]
+    Runtime --> Edge["MCP Runtime / Gateway\none Agent-facing edge"]
+
+    Native --> Claude["Claude Code"]
+    Native --> Codex["Codex"]
+    Native --> Kiro["Kiro"]
+    Native --> Pi["pi"]
+    Edge --> Kimi["Kimi Code"]
+    Edge --> ZCode["ZCode"]
+    Edge --> Claude
+    Edge --> Pi
+```
+
+### Ownership boundary
+
+- `~/.trellis/` is the canonical source and policy boundary.
+- Native Agent directories are projections, not independent sources of truth.
+- Gateway/Runtime owns connection routing and provider exposure, not Agent private sessions.
+- Secrets remain outside canonical YAML and are resolved at runtime.
+- Runtime providers treat Memory, MCP output, and task records as untrusted context.
+
+## Delivery modes
+
+| Mode | Meaning | Typical use |
+|---|---|---|
+| `native` | Project capabilities into the Agent's native configuration | Maximum native compatibility |
+| `mcp` | Consume Trellis capabilities through the Runtime MCP edge | Runtime-first Agents such as Kimi Code |
+| `both` | Keep native and Runtime delivery during a transition | Compatibility migration |
+
+## Similar products
+
+Trellis is intentionally a composition layer, not a replacement for every adjacent product.
+
+| Product/category | Primary focus | What Trellis adds or differs |
+|---|---|---|
+| Rules/Skills sync tools | Share instruction files or Skills across Agents | Adds MCP, Memory, secrets policy, Agent lifecycle, Runtime providers, and verification |
+| [MCP Router](https://github.com/mcp-router/mcp-router) | Desktop MCP server management, workspaces, provider toggles, and logs | Trellis makes canonical MCP state the source of truth and adapts it to multiple Agents; MCP Router can remain an import source or upstream |
+| [MetaMCP](https://github.com/metatool-ai/metamcp) / [mcp-hub](https://github.com/ravitemer/mcp-hub) | Aggregate many MCP servers behind one endpoint | Trellis combines aggregation with native Agent adapters, ownership-safe sync, OAuth routing, and built-in providers |
+| [OpenViking](https://github.com/volcengine/OpenViking) / context databases | Store and retrieve Memory, resources, and Skills through a navigable context space | Trellis defines the Agent-facing control plane and can later mount OpenViking behind the Memory/Context provider contract |
+| Agent orchestration platforms | Launch workers, schedule tasks, and coordinate execution | Trellis currently provides durable task handoff records and leases without implicit remote Agent execution; execution is a deliberate future layer |
+
+## Language and terminology
+
+Documentation uses stable English identifiers for commands, files, types, and protocol names. Explanations can be translated without changing these identifiers:
+
+- Code Agent Runtime / Agent Runtime
+- canonical source
+- native adapter
+- Runtime delivery
+- Skill / MCP / Memory / Instructions
+- gateway / hub / direct
+- managed Agent / unmanaged Agent
+
+Use the language switch in the documentation entrypoints when translations are added. Keep command examples and configuration keys unchanged across languages.
+
+## Learn more
+
+- [Getting started](getting-started.md) — complete onboarding and migration guide
+- [Architecture](architecture.md) — implementation layers and adapter contracts
+- [Research](research.md) — ecosystem comparison and design rationale
+- [Roadmap](roadmap.md) — verified milestones and remaining work

package/docs/overview.zh-CN.md

@@ -0,0 +1,102 @@
+# Trellis
+
+[English](overview.md) · [简体中文](overview.zh-CN.md)
+
+## 一句话介绍
+
+> Trellis 是统一的 Code Agent Runtime，为 Claude Code、Codex、Kiro、pi、Kimi Code 和 ZCode 统一管理 Skill、MCP、Memory 与共享指令。
+
+## 快速开始
+
+### 安装
+
+```bash
+npm install -g agent-trellis
+```
+
+### 接管已有环境
+
+先预览：
+
+```bash
+trellis onboard --dry-run
+```
+
+确认迁移源、托管 Agent、MCP 模式和 Memory 选项后执行：
+
+```bash
+trellis onboard
+```
+
+### 检查状态
+
+```bash
+trellis doctor
+trellis secrets audit
+trellis sync --dry-run
+trellis mcp sync --dry-run
+```
+
+### 导入 MCP Router 配置
+
+```bash
+trellis mcp import ~/Desktop/mcp-servers.json --dry-run
+trellis mcp import ~/Desktop/mcp-servers.json
+```
+
+导入器会自动去重、提取凭证、转换支持的 `mcp-remote` Basic Auth，并跳过本机不存在的历史路径。
+
+## 架构
+
+![Agent Trellis — 一个 Runtime，统一所有 Code Agent。](assets/poster-series-v3/agent-trellis-poster-v3-horizontal-zh.png)
+
+Trellis 以 `~/.trellis/` 为 canonical source，在中心统一管理四类能力：
+
+- Skill：可复用的 Agent 工作方法；
+- MCP：工具、数据源和外部服务；
+- Memory：canonical Markdown 以及可选的共享图数据库；
+- Instructions：跨 Agent 生效的全局指令。
+
+这些能力通过 native adapter 或 Runtime/Gateway 投递给不同的 Code Agent。
+
+品牌与社媒海报资源见 [`docs/assets/poster-series-v3/`](assets/poster-series-v3/README.md)，包含竖版（手机端）与横版（桌面端）海报的中英文版本。
+
+```text
+~/.trellis/ canonical source
+        │
+        ▼
+Trellis Runtime / Gateway
+        │
+        ├── Native adapters ── Claude Code / Codex / Kiro / pi
+        └── MCP Runtime ────── Kimi Code / ZCode / 其他 Runtime-first Agent
+```
+
+## 与相似产品的关系
+
+| 产品/类别 | 主要解决的问题 | Trellis 的区别 |
+|---|---|---|
+| Rules / Skills 同步工具 | 共享规则和 Skill 文件 | 进一步统一 MCP、Memory、凭证策略、托管边界和验证 |
+| [MCP Router](https://github.com/mcp-router/mcp-router) | 桌面 MCP 管理、Workspace、Provider 和日志 | 可作为 Trellis 的导入源或上游；Trellis 自己维护 canonical MCP 状态 |
+| [MetaMCP](https://github.com/metatool-ai/metamcp) / [mcp-hub](https://github.com/ravitemer/mcp-hub) | MCP 聚合和统一入口 | Trellis 额外负责不同 Agent 的 native 适配、生命周期和安全同步 |
+| [OpenViking](https://github.com/volcengine/OpenViking) | Memory、资源和 Skill 的上下文数据库 | Trellis 可将其接入 Memory/Context Provider，作为底层上下文服务 |
+
+## 术语约定
+
+命令、配置键、文件名和协议名称统一保留英文，解释文字可以翻译：
+
+- Code Agent Runtime / Agent Runtime
+- canonical source
+- native adapter
+- Runtime delivery
+- Skill / MCP / Memory / Instructions
+- gateway / hub / direct
+- managed Agent / unmanaged Agent
+
+这样不同语言的文档可以共享同一组命令和配置示例，避免翻译造成操作差异。
+
+## 深入阅读
+
+- [完整上手指南](getting-started.md)
+- [架构说明](architecture.md)
+- [技术调研](research.md)
+- [路线图](roadmap.md)

package/docs/research.md

@@ -66,6 +66,65 @@ becomes a second place "what servers exist" is defined, outside `.trellis/`
 entirely, and this project hit real drift from exactly that shape of setup
 before hub mode existed as a documented option.
 
+### MCP Runtime / built-in capability direction — confirmed architecture
+
+The next abstraction is broader than a skill-only MCP server. MCP defines
+tools, resources, and prompts with different control models, so a Trellis
+runtime should host a registry of providers rather than make every new
+capability its own stdio process:
+
+```text
+TrellisMcpRuntime
+  ├─ BuiltinRegistry: skills, memory, status, future capabilities
+  └─ UpstreamProvider: existing GatewayBackend / RemoteBackend
+```
+
+The first provider candidate is a read-only canonical skill provider. A future
+memory provider can expose local graph or OpenViking-backed memory through the
+same runtime edge. The existing gateway's connection/OAuth/timeout code stays
+behind the upstream provider seam. This preserves one agent-facing MCP entry
+while allowing more Trellis-native capabilities without duplicating transport,
+scope, or lifecycle logic.
+
+The security boundary is explicit: every provider receives the requesting
+agent identity and re-checks scope; skill providers read bounded content only;
+model-visible tools never mutate canonical configuration or execute skill
+scripts by default.
+
+### Local Claude Code / pi dogfood — 2026-09-18
+
+After an external, credential-minimized host snapshot, the managed set was
+narrowed from all four agents to Claude Code and pi through `trellis manage
+set`. Hashes of Codex and Kiro's relevant native state were identical before
+and after detaching them. All 36 pre-existing Claude skill directories were
+byte-identical to canonical, moved intact into the snapshot directory, and
+replaced by Trellis-managed symlinks; pi received the same 36 skills,
+`AGENTS.md`, and the packaged MCP bridge. Subsequent `sync` and `mcp sync`
+dry-runs were empty, `doctor` had zero findings, and `secrets audit` was clean.
+
+Real startup exposed runtime issues that structural tests correctly cannot
+predict:
+
+- Claude connected `chrome-devtools`, `mcp-router`, `tanka`, and
+  `harness-solo`; Figma and Sentry require their native OAuth flows.
+- A real Claude model session waited for `chrome-devtools` and emitted an
+  actual `list_pages` tool call, proving model-to-MCP registration. The direct
+  six-server catalog—dominated by Tanka's large tool surface—drove roughly
+  167k input tokens and hit the verification budget before the tool result was
+  returned. Fine-grained MCP routes are therefore operationally necessary,
+  not merely a UI convenience.
+- pi loaded the Trellis bridge and attempted every canonical upstream. It
+  reported `tanka-mcp` missing from pi's process PATH, plus missing Figma and
+  Sentry authorization. Its `openai-codex` OAuth check was ready, but a real
+  model turn failed before streaming began with WebSocket/SSE `fetch failed`;
+  no tool call occurred. That is a pi-provider transport issue, separate from
+  bridge discovery and tool registration.
+
+The next local pilot should route only a small healthy MCP subset to Claude
+and pi before enabling Runtime delivery. Repeating real model calls against
+the full catalog would spend quota without testing the abstraction we care
+about.
+
 ## Shared memory (reuse)
 
 Checked directly against this real machine before writing this section,

package/docs/roadmap.md

@@ -44,11 +44,10 @@ tests of the pieces — see docs/architecture.md's testing philosophy.
 
 **P2 is done and archived** (`openspec/changes/archive/2026-09-12-trellis-mcp-sync-p2/`;
 living spec at `openspec/specs/mcp-server-sync/`). `trellis mcp sync`
-covers create/repair only — automatic removal is deliberately deferred: a
-symlink's realpath proves Trellis ownership for skills, but a bare TOML/
-JSON key has no equivalent marker, so "gone from canonical" and "the user
-configured this directly" are indistinguishable without a `trellis.lock.json`
-ownership-tracking mechanism that doesn't exist yet. Two write mechanisms
+covers create/repair and, after the ownership-ledger parity follow-up,
+ownership-safe removal: a bare TOML/JSON key is removable only when the
+ledger proves Trellis still owns the exact rendered entry. A hand-edited entry
+is preserved. Two write mechanisms
 were chosen only after empirically ruling out the obvious ones first: both
 `@iarna/toml` and `smol-toml` silently drop comments and reformat arrays on
 a bare parse→stringify round-trip (so Codex's `config.toml` is patched by a
@@ -940,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 |
@@ -956,6 +955,12 @@ tests passing.
 | P23 | ✅ Onboard MCP mode + memory toggle: closes the last hand-editing gap — turning on gateway or hub mode, or the shared memory server, meant directly editing `~/.trellis/mcp/servers.yaml`'s top-level `hub`/`gateway` keys or its commented-out `memory:` example, since no command wrote them (`trellis mcp add`'s flags are all per-server). New `writeMcpModeYaml` in `src/core/canonical.ts` (`Document`-based, mirrors `upsertServerYaml`'s comment-preserving edit) plus `trellis onboard --mcp-mode direct\|hub\|gateway` (`--hub-url`, `--gateway-agents`) and `--memory on\|off` close it. Both follow onboard's existing managed-set idempotency shape rather than a new one: read current state first, omitting the flag always preserves it untouched with zero prompting — identical on a first run (nothing configured) and a later one (something already is), which is the actual point: one command for both, not a setup path and a separate reconfigure path. Deliberately flag-only, never an interactive picker (a mode change reroutes every managed agent's MCP transport at once — too wide a blast radius for Enter-mashing through a prompt sequence to trigger by accident); a one-line, non-prompting status line on a real terminal keeps the flags discoverable anyway. `--memory on` refuses outright if `"memory"` is already in `known_host_injected`, rather than writing a definition the very next `mcp sync` would refuse to propagate to any agent. Because mode/memory resolution runs before onboard's existing `mcp sync`/`memory sync` stages in the same chain, `trellis onboard --memory on` enables the server, syncs it to every managed agent, and populates it from canonical `memories/*.md` — all in one run | P17, P21, P22 |
 | P24 | ✅ Migrate static-env secret extraction: found via real-machine dogfooding — kiro's own real `mcp-router` server had its token hardcoded as a literal (not a `${VAR}` reference), which the existing literal-secret guard correctly refused to import, but the only path forward was three manual hand-edits across two files. A `staticEnv` match specifically (its own dict key is already a natural variable name) is now extracted automatically instead of refused: the real value moves to `~/.trellis/mcp/servers.local.env` (a sibling of `servers.yaml`, or an already-configured `secrets.policy.yaml` `env_file` if one exists — respecting a prior explicit choice rather than repointing it), canonical gets a `${NAME}` reference, `secrets.policy.yaml` gains the name in `allowed_vars`, and `~/.trellis/.gitignore` is ensured to protect the new file, all ensured lazily at the moment of the first real write, never as unconditional `init` bootstrap. `migrate` still never writes to the source agent's own file — kiro's real config keeps its literal forever, and `secrets audit` correctly keeps flagging it; extraction normalizes to a `warning` in onboard's verdict, not `blocked`, with a remediation naming that the source was left untouched. A literal found anywhere other than `staticEnv` (`command`/`url`/`args`/`headers` — no natural name to extract to) still refuses exactly as before. `findLiteralSecret` (`src/adapters/mcpPlan.ts`) now reports which field and dict key a match came from, closing a previously-undocumented spec gap for the unaffected refusal path in the same change. Also found via the same dogfooding, one commit later: extraction alone doesn't make the `${VAR}` reference `mcp sync` writes into an agent's native config actually resolve — that only happens once the name is in the environment that agent's own runtime reads from, which `servers.local.env` alone never reaches. `ensureShellEnvSource` (mirrors `ensureGitignoreEntry`'s idempotent marker-block shape) now appends one generic `set -a; source ...; set +a` pointer block to the user's shell rc (`~/.zshrc`/`~/.bash_profile`/`~/.profile` by `$SHELL`) — never a literal secret line — every real `migrate` run whenever `env_file` is set, retroactively wiring a machine that extracted before this existed. Separately, fixed a real incident this surfaced: no subcommand branch in `src/cli.ts` recognized `--help`/`-h`, so a stray `--help` silently ran the real command instead of printing usage — now short-circuits to usage text before any parsing, for every command. One more round: real-machine research (`mcpConnect.ts`, `jsonMcp.ts`, `tomlSection.ts`) found no `${VAR}` resolution mechanism proven across every consumer for `command`/`url`/`args`, and `headers` unverified for claude-code/kiro specifically — so `command`/`url`/`args`/`headers` literals are now *accepted* into canonical as ordinary config (both at `migrate`'s import boundary and `resolveMcpPlan`'s sync-out boundary), never refused and never faked into an unresolvable reference; `secrets audit` now also scans canonical's own `servers.yaml` for this (`agent: "canonical"`) so it's never silent. `staticEnv` extractions are now named `TRELLIS_<SERVER>_<KEY>` rather than the bare source key, to rule out cross-server or ambient-environment collisions — an already-extracted server (this project's own real `mcp-router`) is recognized as already-migrated by the *value* an existing reference resolves to, not by re-deriving today's naming scheme, so it keeps working under its original bare name without being renamed or re-extracted | P16, P18 |
 
+| P25 | ✅ Onboard prompt TUI: replaces Trellis's hand-written raw-mode picker and ANSI redraw logic with `@clack/prompts`, preserving non-TTY fallbacks, `--json`, stream-injected tests, stderr-only interactive chrome, and compact agent summaries that show counts instead of enumerating skills. Full-screen TUI runtimes remain out of scope; onboarding stays visible in terminal scrollback | P22 |
+| 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-
 machine / cloud sharing" section): keeping `~/.trellis` consistent across

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 秒

package/docs/video/build/segments/01-opening.txt

@@ -0,0 +1,3 @@
+file '/Users/pengzai/www/Trellis/docs/video/build/frames/01-opening-0.png'
+duration 11.053
+file '/Users/pengzai/www/Trellis/docs/video/build/frames/01-opening-0.png'

package/docs/video/build/segments/02-pain.txt

@@ -0,0 +1,5 @@
+file '/Users/pengzai/www/Trellis/docs/video/build/frames/02-pain-1.png'
+duration 2.172
+file '/Users/pengzai/www/Trellis/docs/video/build/frames/02-pain-2.png'
+duration 5.068
+file '/Users/pengzai/www/Trellis/docs/video/build/frames/02-pain-2.png'

package/docs/video/build/segments/03-solution.txt

@@ -0,0 +1,3 @@
+file '/Users/pengzai/www/Trellis/docs/video/build/frames/03-solution-3.png'
+duration 6.482
+file '/Users/pengzai/www/Trellis/docs/video/build/frames/03-solution-3.png'

package/docs/video/build/segments/04-install.txt

@@ -0,0 +1,3 @@
+file '/Users/pengzai/www/Trellis/docs/video/build/frames/04-install-4.png'
+duration 2.407
+file '/Users/pengzai/www/Trellis/docs/video/build/frames/04-install-4.png'