agent-trellis 0.7.0 → 0.8.2

package/docs/getting-started.md

@@ -15,8 +15,8 @@ npm install -g agent-trellis
 $ trellis onboard
 ```
 
-Runs `init`, detects which of Claude Code/Codex/Kiro/pi are on this machine,
-then resolves two interactive choices and two flag-only ones before running
+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
 hand, and no need to run `trellis doctor` separately to know whether it
@@ -39,27 +39,43 @@ that.
      prompt entirely. Which *categories* to bring in from that source
      (skills, instructions, mcp) is its own checkbox, shown only when the
      source has real content in two or more of them — with just one, that
-     one is migrated unprompted.
+     one is migrated unprompted. On a real terminal this uses a colored
+     selector; it shows aggregate counts, not every skill name.
 2. **Managed set** — zero or more agents to actually write to. Always an
    explicit choice: pass `--manage <ids>` (comma-separated, e.g. `--manage
    pi,codex`) or `--manage none`, or answer the interactive checkbox prompt
-   (Space to toggle, Enter to confirm — same numbered fallback as above).
+   (arrow keys to move, Space to toggle, Enter to confirm — same numbered
+   fallback as above when a raw TTY is unavailable).
    **The source is not included by default** — migrating from Claude Code
    doesn't mean Trellis starts managing Claude Code too, unless you say so.
    Selecting an agent that isn't installed yet is itself the authorization to
    install it (one confirmation, then a real `npm install -g <package>`);
    Kiro has no CLI package and is refused with its download URL instead.
-3. **MCP mode** — direct (the default), hub, or gateway. Flag-only, never
-   prompted: pass `--mcp-mode direct|hub|gateway` to change it (`--hub-url
-   <url>` is required with `hub`; `--gateway-agents <ids>` is optional with
-   `gateway`, omitted meaning every managed agent). Omitting `--mcp-mode`
+   Onboarding is intentionally additive: an agent already managed remains
+   managed if a later onboarding run omits it. Use the explicit `trellis
+   manage` lifecycle commands below when you intend to detach one.
+3. **MCP mode** — direct, gateway, or hub. In the interactive route picker,
+   **Gateway is recommended for local Trellis hosting**: Trellis runs the
+   local MCP entry and manages upstream connections for the Agent session;
+   no extra service is needed. Choose **Direct** when each Agent should
+   connect to MCP servers independently. Choose **Hub only when an external
+   MCP Hub is already running**: each Agent connects to one external HTTP
+   endpoint, and the Hub owns the upstream server list. Trellis does not
+   deploy the Hub. The non-interactive mode is flag-only: pass
+   `--mcp-mode direct|hub|gateway` to change it (`--hub-url <url>` is required
+   with `hub`; `--gateway-agents <ids>` is optional with `gateway`, omitted
+   meaning every managed agent). Omitting `--mcp-mode`
    entirely leaves whatever's already configured untouched — on a fresh
    machine that's direct, on one you've already switched that's whatever
    you last set — so a plain `trellis onboard` re-run never resets it. This
    is the only supported way to turn gateway or hub mode on or off; there's
    no reason to hand-edit `~/.trellis/mcp/servers.yaml`'s `hub`/`gateway`
    keys directly.
-4. **The shared memory server** — off by default. Pass `--memory on` to add
+4. **Existing memory migration** — independent from the shared backend. Pass
+   `--memory-migrate on` to import supported native Markdown memory, or
+   `--memory-migrate off` to skip it. Unsupported Kimi/pi session stores are
+   reported and left untouched.
+5. **The shared memory server** — off by default. Pass `--memory on` to add
    the default `@modelcontextprotocol/server-memory` definition (refused if
    a host on this machine already injects a connector named `memory` — see
    [`trellis memory sync`](#trellis-memory-sync) below) or
@@ -134,6 +150,14 @@ a re-plan against canonical can. If a write somehow didn't hold (a
 filesystem permission problem, a race), it surfaces in the verdict as its
 own `blocked` item, separate from whatever the write's own stage reported.
 
+Onboarding treats a mode change as a route transition, not a reset: canonical
+Skills, MCP definitions, memories, and secrets policy stay in place. When an
+interactive run changes mode, it shows the current mode, target mode, and
+affected managed Agents before asking for confirmation. A blocking failure in
+the transaction automatically restores canonical and native files together;
+the backup remains available in `~/.trellis/backups/` for inspection or a
+later explicit rollback.
+
 **The health scan is `trellis doctor` itself**, run at the end against
 every agent (not just the ones this run manages) — so a genuinely new
 problem this run happened to create or reveal shows up without a separate
@@ -151,6 +175,23 @@ happens. It never appears on stdout, so `trellis onboard > report.txt`
 still captures exactly the report and verdict, nothing else; it's silent
 entirely under `--json` or when stdout isn't a real terminal.
 
+Interactive choices use a compact colored prompt UI with clear success,
+warning, and blocking states. The prompt UI is written to stderr, while the
+report and JSON output stay on stdout.
+
+For repeatable item-level selection, pass a YAML/JSON file:
+
+```
+$ trellis onboard --agent kiro --manage codex \
+    --selection ./schema/capability-selection.example.yaml
+```
+
+The file can select individual `skills`, `mcp_servers`, and `memories`, plus
+per-agent `mcp_routes` with `direct`, `gateway`, or `hub` mode. It can also
+set `runtime_delivery` per agent to `native`, `mcp`, or `both`; omitted agents
+remain native. Existing
+`--mcp-mode` and category flags remain valid shortcuts.
+
 Add `--dry-run` to preview the entire chain — init/migrate/sync/mcp
 sync/memory sync, including what would be written to
 `~/.trellis/managed.yaml` and to `servers.yaml`'s mode/memory keys — with
@@ -174,9 +215,142 @@ The rest of this page is the same flow broken into its individual steps —
 useful if you want more control over any one part, or just want to
 understand what `onboard` did.
 
+## `trellis manage` — change the write boundary explicitly
+
+The managed set is Trellis's hard outer authorization boundary. Use the
+standalone lifecycle command when you need to inspect, replace, extend, or
+narrow it without running migration or sync:
+
+```
+trellis manage list
+trellis manage set claude-code,pi --dry-run
+trellis manage set claude-code,pi
+trellis manage add codex
+trellis manage remove kiro
+trellis manage set none
+```
+
+`set` is exact; `add` unions; `remove` subtracts. Every real change to
+`managed.yaml` is recorded under `~/.trellis/backups/` and can be reversed by
+`trellis rollback`. A dry run or no-op creates no backup.
+
+Detaching only prevents future Trellis writes. It never deletes or rewrites
+the detached agent's existing skills, instructions, MCP entries, extensions,
+or login state. Cleanup, if desired, is a separate explicit decision.
+
+This differs deliberately from `onboard --manage`: onboarding remains
+additive so an omitted checkbox cannot silently revoke management.
+
+## Kimi Code Runtime-first
+
+Kimi Code is supported as `kimi-code`. For Runtime-first delivery, configure
+the capability selection with `runtime_delivery: { kimi-code: mcp }`, then
+sync MCP and launch Kimi through Trellis:
+
+```
+trellis manage add kimi-code --dry-run
+trellis mcp sync --dry-run
+trellis kimi -p "search the Trellis skills for the onboarding workflow"
+```
+
+Runtime-only Kimi receives one `trellis` entry in
+`~/.kimi-code/mcp.json`. `trellis kimi` passes an empty `--skills-dir` for
+that mode, so Kimi does not also discover the shared `~/.agents/skills`
+directory. The canonical SkillProvider and RuntimeMemoryProvider remain the
+source of Skill/Memory content, while selected upstream MCP servers are
+mounted through the same Runtime/Gateway edge.
+
+Kimi's `deferred` MCP field is enabled on the owned Runtime entry to reduce
+initial tool-list context when Kimi's experimental tool-select capability is
+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
+the canonical source. It deliberately has two phases:
+
+### Phase 1: before takeover
+
+Use it as a checklist for the operator-assisted migration flow:
+
+1. Run `trellis doctor` and `trellis onboard --dry-run` to inspect the current
+   machine without changing Agent files.
+2. Choose one migration source with `--agent` and an explicit managed boundary
+   with `--manage`. Migrating from an Agent does not automatically authorize
+   Trellis to write back to that Agent.
+3. Review the selected Skills, MCP servers, Memory, per-Agent routes, and
+   delivery mode. Use `--selection` when the choice must be repeatable.
+4. Apply only after reviewing the dry-run. `onboard` performs migration,
+   native/runtime sync, Memory sync, secrets audit, and health verification in
+   one transaction.
+5. Resolve OAuth interactively with `trellis mcp auth <server>`. Never place a
+   token in this Skill, `servers.yaml`, tests, or demonstration configuration.
+6. If the verdict blocks, follow its remediation. Do not delete an unknown
+   file or bypass ownership protection; every real write has a backup and can
+   be inspected with `trellis rollback --list`.
+
+### Phase 2: after takeover
+
+The Agent consumes the same Skill regardless of its native adapter:
+
+| Delivery | How the Skill is consumed |
+| --- | --- |
+| `native` | A Trellis-owned symlink points the Agent's native Skill root at the canonical Skill. |
+| `mcp` | `SkillProvider` exposes the canonical Skill through the `trellis` Runtime; Kimi is launched with `trellis kimi` so its native Skill root does not duplicate the Runtime. |
+| `both` | Native discovery and the Runtime are both available when a deliberate compatibility transition requires it. |
+
+Once the Agent is running, start with the current Runtime status, then use
+progressive disclosure:
+
+1. `runtime_status` — Agent identity, delivery mode, provider readiness, and
+   counts.
+2. `skills_search` → `skills_read` — locate and read only the Skill needed for
+   the current task.
+3. `memory_search` → `memory_read` — consume shared canonical Memory.
+4. `instructions_read` — inspect canonical global instructions when context is
+   needed.
+5. `mcp_status` — diagnose missing, unauthorized, or unavailable MCP servers
+   and show the user the supported remediation.
+6. `agents_list` and `tasks_list`/`tasks_read` — inspect the managed boundary
+   and handoff work. Mutating tasks requires explicit confirmation.
+
+These are Trellis's portable names. A client may add a namespace such as
+`mcp__trellis__skills_search`; never hardcode that client-generated prefix in a
+Skill. The Runtime's built-in Skill and Memory providers are read-only. Shared
+Memory writes come from the configured Memory MCP backend, and importing graph
+content back into canonical Markdown remains an explicit
+`trellis memory extract` operation.
+
 ## Two starting points
 
-**You already use one or more of Claude Code, Codex, Kiro, or pi** 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).
 
@@ -204,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 four 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
@@ -225,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`, or `pi`. 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:
@@ -234,7 +408,7 @@ Add `--dry-run` to see the plan without writing anything:
 $ trellis migrate --from codex --dry-run
 ```
 
-Add `--only skills`, `--only instructions`, or `--only mcp` to migrate
+Add `--only skills`, `--only instructions`, `--only mcp`, or `--only memory` to migrate
 just one category — useful when you only want part of it brought in
 right now. Omit it to migrate all three, exactly as above:
 
@@ -251,7 +425,7 @@ $ trellis migrate --from codex --only instructions
 | `conflict` | Canonical already has *different* real content — **left untouched**, resolve by hand. |
 | `skip-symlink` | That agent's own copy is itself a symlink (already shared in from elsewhere) — nothing of that agent's own to import. |
 | `skip-case-broken` | Found as `skill.md` instead of `SKILL.md` — fix the case on the source agent first. |
-| `skip-unsupported` | MCP servers only — that agent's real definition can't be safely represented (see below); nothing was written for it. |
+| `skip-unsupported` | The source capability can't be safely represented (including native memory without a supported adapter); nothing was written for it. |
 
 Migrate never overwrites a genuine conflict, and never scopes a migrated
 skill (or MCP server) to just the source agent — once in canonical, it's
@@ -259,6 +433,31 @@ visible to every agent by default (see `sync`, below). If migrate reports
 a `conflict`, open the two files/entries it names and decide by hand
 which content should actually be canonical, then re-run.
 
+Memory migration is deliberately separate from enabling the shared Memory
+MCP:
+
+```text
+trellis onboard --memory-migrate on --memory off
+```
+
+The initial native-memory adapter supports Claude Code's exact current-
+workspace Markdown memory directory. Kimi Code and pi session logs are
+reported as unsupported and are not inspected. Imported files receive
+deterministic names and provenance headers under `~/.trellis/memories/`; a
+conflict is left untouched and the onboarding transaction can roll back the
+import.
+
+Codex is also supported when its documented local Memory directory contains
+Markdown files:
+
+```text
+trellis migrate --from codex --only memory --dry-run
+```
+
+Trellis resolves `CODEX_HOME` when set, otherwise `~/.codex`, and reads only
+the Memory directory. `AGENTS.md`, `session_index.jsonl`, sessions,
+credentials, and plugin state are never treated as memory.
+
 **MCP servers** (claude-code, kiro, codex — not pi, which has no static
 MCP config to read at all) migrate the same way, into
 `~/.trellis/mcp/servers.yaml`:
@@ -373,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
@@ -402,6 +604,16 @@ then auto-removes the now-stale symlink on every agent that had it (skills
 carry their own ownership marker — the symlink itself — so this
 propagates automatically, unlike MCP servers below).
 
+The package-owned Runtime Skill is refreshed explicitly with:
+
+```
+trellis skill update-builtin --dry-run
+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.
+
 ```
 $ trellis mcp list
 tanka (http) — codex, pi
@@ -417,16 +629,46 @@ removed MCP server "local-server" from canonical source.
 
 `mcp add` takes `--transport stdio|http|sse`; stdio requires `--command`
 (plus optional `--args a,b`, `--env NAME,...`, `--static-env k=v,...`),
-http/sse require `--url` (plus optional `--headers k=v,...`, values
+http/sse require `--url` (plus optional `--auth oauth`, `--headers k=v,...`, values
 expected as `${VAR}` references, never literal secrets). Both accept
 `--agents id,...` (scope) and `--enabled true|false`. Same no-overwrite
 conflict posture as `skill add` — there is no `--force`.
 
-`mcp remove` is **canonical-only** — it does not remove the server from
-any agent that already has it from an earlier `mcp sync` (the same
-no-automatic-removal gap `mcp sync` itself has — see
-[README's Known limitations](../README.md#status)); remove it by hand on
-each agent in the meantime.
+For a standard JSON export with a top-level `mcpServers` object, use the
+credential-aware importer instead of repeating `mcp add` by hand:
+
+```
+trellis mcp import ~/Desktop/mcp-servers.json --dry-run
+trellis mcp import ~/Desktop/mcp-servers.json
+```
+
+The source file is read-only. The importer de-duplicates semantically
+identical servers, preserves existing canonical definitions, reports same-name
+conflicts, and skips unavailable absolute paths. A recognized `mcp-remote`
+Basic Authorization export is converted to native HTTP MCP; other credentials
+embedded in command arguments, URLs, or headers are rejected. Credential-like values in an exported
+`env` map are moved to the ignored local file
+`~/.trellis/mcp/servers.local.env`; canonical stores only a prefixed variable
+reference through `env_aliases`:
+
+```yaml
+env_aliases:
+  SUPABASE_ACCESS_TOKEN: TRELLIS_SUPABASE_DB_SUPABASE_ACCESS_TOKEN
+```
+
+The actual value is never printed in the plan, JSON report, canonical YAML, or
+shell arguments. Re-importing is idempotent; an existing local secret with a
+different value is a conflict and is never overwritten. OAuth sessions are not
+imported — authorize the resulting remote MCP explicitly with
+`trellis mcp auth <name>`.
+
+Use `trellis mcp set <name> --auth oauth` to keep a known OAuth MCP direct
+when its Agent uses gateway mode; use `--auth none` to clear the marker.
+Trellis does not infer OAuth from a URL or an authentication failure.
+
+`mcp remove` changes canonical state only. The next `trellis mcp sync` removes
+the old native entry when the ownership ledger proves Trellis still owns it;
+hand-edited native entries are preserved and reported as conflicts.
 
 `mcp list` never resolves or prints a secret value: `env` names are shown
 as bare names (the actual value is never read from your shell), and
@@ -485,10 +727,9 @@ known-host-injected collision avoidance, hub mode, and gateway mode
 $ trellis mcp sync
 ```
 
-Create/repair only — if you remove a server from `servers.yaml`, `mcp sync`
-does not remove it from any agent's native config yet (see
-[README's Known limitations](../README.md#status)). Remove it by hand on
-each agent in the meantime.
+`mcp sync` also removes an entry deleted from canonical when the ownership
+ledger proves the current native definition is exactly what Trellis last
+wrote. Hand-edited entries are left untouched and reported as conflicts.
 
 Every native-config file this rewrites in place is snapshotted first,
 automatically — see
@@ -547,8 +788,14 @@ agent spawns it like any other stdio MCP server; it connects out to your
 servers, and exits when the session ends. There is nothing to start,
 stop, or monitor.
 
-Your servers' tools appear to the agent as `<server>__<tool>` — the
-`gitlab` server's `search` becomes `gitlab__search`.
+Long unambiguous upstream tools stay compact. Generic short names such as
+`search` receive source context even when unique; if both GitHub and GitLab
+expose `search`, they become `github__search` and `gitlab__search`. A tool that
+already contains its source prefix is not repeated. Agent-facing names are
+normalized to `[A-Za-z0-9_-]` and
+bounded to 64 characters; long names receive a deterministic hash suffix.
+Extremely rare normalized-name collisions receive a deterministic suffix
+rather than being dropped, while calls still route to the original MCP name.
 
 Add `agents: [claude-code, codex]` under `gateway:` to narrow it, leaving
 the rest in direct mode. Gateway mode and `hub` are independent; both can
@@ -557,12 +804,14 @@ be set, and gateway wins for any agent it covers.
 Two things stop being problems in gateway mode. Codex can normally only
 express a single `Authorization: Bearer ${VAR}` header, so a server
 needing more than one was refused for Codex — in gateway mode Codex never
-sees any server's headers, so it just works. And remote servers requiring
-real OAuth become reachable from every agent, including pi.
+sees any ordinary server's headers, so it just works. OAuth-marked servers
+stay direct while ordinary remote servers remain shared through the gateway.
 
 ### `trellis mcp auth <server-name>`
 
-For a remote (`http`/`sse`) server that uses OAuth, authorize it once:
+For a remote (`http`/`sse`) server marked `auth: oauth`, native Agents should
+use their own login command. Pi's direct bridge path can be authorized once
+through Trellis:
 
 ```
 $ trellis mcp auth notion-remote
@@ -574,15 +823,22 @@ This opens your browser, completes the flow, and stores the result 0600
 under `~/.trellis/mcp/oauth/` — never in `servers.yaml`, so canonical
 stays safe to read, diff, and commit.
 
-Run it once per server. After that the gateway refreshes the token
-silently whenever it expires; it never opens a browser and never prompts,
-because it is spawned by an agent with no terminal attached. Re-running
+Run it once per server when Pi's direct bridge owns the OAuth connection.
+After that the bridge refreshes the token silently whenever it expires; it
+never opens a browser and never prompts, because it is spawned by an agent
+with no terminal attached. Re-running
 this command when the stored token is still valid does nothing (`--force`
 overrides); when it has expired but is renewable, it refreshes without a
 browser.
 
-If a server has no stored credential, the gateway skips that one server
-and keeps serving every other — it does not fail to start.
+If a Pi direct OAuth server has no stored credential, the bridge skips that
+one server and keeps serving every other — it does not fail to start. Native
+Agents report the same direct entry as requiring their own authorization.
+
+An Agent can call the read-only `trellis.mcp.status` Runtime tool to explain
+this partial state to the user. It reports unavailable or authorization-
+required servers and gives the next safe action, such as `trellis mcp auth
+figma`, without exposing tokens or opening a browser from the Agent process.
 
 This command only applies to `http`/`sse` servers. stdio servers get
 their credentials from `env`/`env_aliases` as described above; running
@@ -590,6 +846,17 @@ their credentials from `env`/`env_aliases` as described above; running
 
 ## `trellis memory sync`
 
+Canonical memories can also be consumed directly through the Trellis MCP
+Runtime when an agent's runtime delivery is `mcp` or `both`. Runtime exposes
+read-only `trellis.memory.search` and `trellis.memory.read` tools plus
+`trellis://memories/<name>.md` resources. Results are filtered through the
+memory's `scope.yaml` entry and the managed-agent boundary on every request.
+
+This Runtime path reads `~/.trellis/memories/*.md` directly. It does not need
+the separate `memory` MCP server below, and it does not expose write/delete
+tools. `memory sync` remains the bridge from canonical Markdown into the
+mutable shared graph used by `@modelcontextprotocol/server-memory`.
+
 Ingests `~/.trellis/memories/*.md` into the actual on-disk file
 `@modelcontextprotocol/server-memory` reads at its own startup — closing
 the gap between "memory entries exist in canonical" and "the running
@@ -651,6 +918,24 @@ entities' names would slug to the same filename. Not wired into
 deliberate, occasional action you run, the same posture `migrate` already
 has.
 
+For a shared Kimi Code + pi setup, enable the backend through onboarding
+instead of editing either Agent's config by hand:
+
+```text
+trellis onboard --memory on --mcp-mode gateway --manage pi,kimi-code
+```
+
+This writes one canonical `memory` server, syncs the Gateway route to both
+Agents, and runs `memory sync` in the same transaction. Runtime status reports
+`backendConfigured`, `graphReady`, `canonicalCount`, write authority, and the
+managed Agents receiving the shared route. It distinguishes an unconfigured
+backend from an empty but writable graph.
+
+Agent-created graph content is external Memory context. It is not imported
+back into canonical automatically; run `trellis memory extract` explicitly
+when you want durable, reviewable Markdown. Native/private Agent memory
+stores are not scraped or guessed.
+
 **Note:** this is unrelated to any project-level "auto memory" feature an
 agent may have of its own (e.g. Claude Code's own per-project memory
 files) — those are a different, agent-specific mechanism entirely, not
@@ -682,7 +967,7 @@ periodically regardless.
 $ trellis doctor
 ```
 
-Read-only. Scans all four 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.
@@ -691,6 +976,42 @@ Safe to run any time; nothing here writes anything.
 stdio MCP server (some reaching real external services) — not something a
 "just check my config" command should do by default.
 
+## 在 Linux sandbox 中验证真实 agent
+
+Trellis 提供一个独立的 agent image，用于安装真实的 Codex、Claude Code、
+Kiro CLI 和 pi，而不是只使用 fake CLI。它使用 `runtime-home` 作为只读
+fixture，并把内容复制到容器内的隔离 `$HOME`；不会挂载宿主机的 agent
+目录或登录态：
+
+```
+scripts/agent-sandbox.sh
+```
+
+未登录时，Codex 和 Claude Code 可以验证自己是否识别 Trellis 写入的
+`trellis` MCP entry；Kiro CLI 会在 `mcp list` 前要求登录，这
+是 Kiro 的真实授权边界。
+
+如需实际授权，使用单独的 Docker volume 保存 sandbox 登录态：
+
+```
+scripts/agent-sandbox.sh --login codex
+scripts/agent-sandbox.sh --login claude
+scripts/agent-sandbox.sh --login kiro
+```
+
+登录过程在终端中显示设备授权或浏览器流程。登录完成后，可以检查：
+
+```
+scripts/agent-sandbox.sh --status codex
+scripts/agent-sandbox.sh --status claude
+scripts/agent-sandbox.sh --status kiro
+```
+
+默认 volume 名称为 `trellis-agent-auth-home`，可通过
+`TRELLIS_AGENT_AUTH_VOLUME` 覆盖。它只保存在 OrbStack/Docker 中，不进
+Git，也不会自动读取或删除宿主机凭据。清理时请明确执行
+`docker volume rm <volume-name>`。
+
 ## `trellis rollback` — undoing a `sync`/`mcp sync`/`onboard` run
 
 Every real write those three commands perform is recorded, before it
@@ -735,6 +1056,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
@@ -745,6 +1187,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.