agent-trellis 0.6.3 → 0.8.0

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 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,117 @@ 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.
+
+## 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, or Kimi Code** and have
 real skills/instructions in them today. Go to
 [Migrating from an existing agent](#migrating-from-an-existing-agent).
 
@@ -204,7 +353,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 five 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 +374,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`, or `kimi-code`. 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 +383,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 +400,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 +408,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`:
@@ -288,6 +462,81 @@ Two known fidelity limits, named rather than silently worked around:
   server was hand-authored with some other shape, it migrates whatever
   is actually there, same as any other field.
 
+**A real credential value found in a source agent's config is extracted,
+not just refused.** If a source agent stores a real credential as a
+literal (not a `${VAR}` reference) under a server's `staticEnv`-shaped
+field — the exact real case this project hit: kiro's own `mcp-router`
+entry had its token hardcoded — `migrate` moves the real value to
+`~/.trellis/mcp/servers.local.env` (a sibling of `servers.yaml`,
+automatically `.gitignore`d — never something you need to protect by
+hand), references it from canonical as `${THE_NAME}` instead of the
+literal, and adds the name to `secrets.policy.yaml`'s `allowed_vars`. If
+`secrets.policy.yaml` already has its own `env_file` configured, the
+value goes there instead, respecting your existing setup rather than
+creating a second file.
+
+```
+$ trellis migrate --from kiro --only mcp
+migrate --from kiro
+  [extract-secret] mcp server "mcp-router" — will extract "MCPR_TOKEN" to
+  ~/.trellis/mcp/servers.local.env as "TRELLIS_MCP_ROUTER_MCPR_TOKEN",
+  referencing it from servers.yaml instead of holding the literal value
+```
+
+The name it's extracted under is `TRELLIS_<SERVER>_<KEY>`, never the
+bare source key alone — a project-wide prefix rules out colliding with
+anything already in your own environment, and the server-name segment
+rules out two Trellis-managed servers colliding with each other over
+the same key. A server extracted before this naming scheme existed
+keeps working under its original name — recognized by the value it
+resolves to, not by re-deriving today's name and expecting an exact
+match, so it's never silently re-extracted under a second name.
+
+**The source agent's own file is never touched** — kiro's real
+`~/.kiro/settings/mcp.json` keeps its literal value exactly as it was,
+forever; `trellis secrets audit` will keep flagging that file on every
+future run, which is correct and expected — cleaning it up by hand is
+your call, not something this command does for you.
+
+**A credential found anywhere *other* than `staticEnv`** (a server's
+`command`, `url`, `args`, or `headers`) **is accepted as ordinary
+literal config, not refused and not extracted.** Neither a natural
+variable name (staticEnv's own dict key provides one; these fields
+don't) nor a proven `${VAR}` resolution mechanism exists for these
+fields across every consumer (pi-bridge, claude-code, codex, kiro) —
+faking a reference would produce a config that looks safe but silently
+fails to connect for at least some of them, worse than the literal it
+replaced. `trellis secrets audit` also scans canonical's own
+`mcp/servers.yaml` for this case (`agent: "canonical"` in its findings),
+so accepting the literal is never silent either.
+
+**The `${VAR}` reference `mcp sync` writes into an agent's native config
+only works once that name is actually in the environment that agent's
+own process reads from** — extraction alone doesn't get you there, it
+just gets the real value out of canonical. So `migrate` also ensures
+your shell rc (`~/.zshrc`/`~/.bash_profile`/`~/.profile`, picked from
+`$SHELL`) sources `servers.local.env`, appending one generic,
+idempotent block — never a literal secret line:
+
+```
+# >>> trellis mcp secrets >>>
+if [ -f "~/.trellis/mcp/servers.local.env" ]; then
+  set -a
+  source "~/.trellis/mcp/servers.local.env"
+  set +a
+fi
+# <<< trellis mcp secrets <<<
+```
+
+Adding another secret later only ever means editing
+`servers.local.env` — the rc file never needs a second edit. This runs
+on every real `migrate` invocation whenever `secrets.policy.yaml` has an
+`env_file`, not just the run that performed the extraction, so a machine
+that already extracted a secret before this existed gets wired the next
+time `migrate` runs at all. A new shell (or restarting the agent
+process) is what actually picks up the newly-exported variable — this
+only ensures the rc file is ready to hand it over.
+
 ## Starting from nothing
 
 Skip migrate. Edit `~/.trellis/agents.md` and add skills under
@@ -327,6 +576,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
@@ -342,16 +601,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
@@ -410,10 +699,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
@@ -472,8 +760,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
@@ -482,12 +776,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
@@ -499,15 +795,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
@@ -515,6 +818,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
@@ -576,6 +890,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
@@ -607,7 +939,7 @@ periodically regardless.
 $ trellis doctor
 ```
 
-Read-only. Scans all four agents' current state and reports drift —
+Read-only. Scans all five 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.
@@ -616,6 +948,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