agent-trellis 0.8.0 → 0.8.2

package/README.md

@@ -1,237 +1,73 @@
 # Trellis
 
 <p align="center">
-  <img src="docs/assets/trellis-mark.svg" width="88" alt="Trellis logo" />
+  <img src="docs/assets/brand-v3/trellis-mark-v3-a.svg" width="88" alt="Trellis logo" />
 </p>
 
 <p align="center"><strong>Unified Code Agent Runtime</strong></p>
 
-Trellis gives Claude Code, Codex, Kiro, pi, and Kimi Code one Runtime for
-Skills, MCP, Memory, and shared instructions.
+One canonical source for Skills, MCP, Memory, and shared instructions —
+projected safely into Claude Code, Codex, Kiro, pi, Kimi Code, and ZCode.
 
-> 中文：Trellis 是统一的 Code Agent Runtime，为多个 Code Agent 提供一致的
-> Skill、MCP、Memory 与共享指令能力。
+> 中文：一个 canonical source 统一管理多个 Code Agent 的 Skill、MCP、Memory
+> 与共享指令，支持预览、备份与回滚。
 
-Trellis does not replace an Agent's native runtime. It manages one canonical
-source and generates verified native or Runtime projections from it.
+![Agent Trellis — One Runtime. Every Code Agent.](docs/assets/poster-series-v3/agent-trellis-poster-v3-horizontal-en.png)
 
-[Read the product overview →](docs/overview.md)
-
-![Agent Trellis architecture](docs/assets/agent-trellis-architecture-horizontal.svg)
-
-## Install
+## Quick start
 
 ```bash
 npm install -g agent-trellis
-```
-
-## Quick start
 
-```bash
-trellis onboard --dry-run
-trellis onboard
-trellis doctor
+trellis onboard --dry-run   # preview: migration source, managed agents, MCP, memory
+trellis onboard             # apply — every write is backed up automatically
+trellis doctor              # verify state, any time
 ```
 
-Use the dry-run to review migration source, managed Agents, MCP mode, and
-Memory before applying. See [`docs/overview.md`](docs/overview.md) for the
-short product explanation and [`docs/getting-started.md`](docs/getting-started.md)
-for the complete workflow.
-
-## Why
-
-By late 2026 the "sync my AI agent rules across tools" space is crowded — at
-least seven open source projects do it (`block/ai-rules`, `ai-rules-sync`,
-`skillshare`, `skills-hub`, `skills-link`, `agent_sync`, and others). None of
-them cover **Kiro** or **pi**, and none of them go past rules/skills into MCP
-servers, shared memory, and secret hygiene as one coherent system. That's the
-gap Trellis fills — see [`docs/research.md`](docs/research.md) for the full
-landscape survey and [`docs/architecture.md`](docs/architecture.md) for what we
-build versus what we deliberately reuse.
-
-Trellis aligns with the emerging [`.agents Protocol`](https://dotagentsprotocol.com)
-draft rather than inventing a sixth competing standard, and is likely its first
-working implementation.
+Something went wrong? `trellis rollback` inverts the last run.
 
-See [`docs/getting-started.md`](docs/getting-started.md) for the detailed
-walkthrough — example output for each command, what each `migrate`/`sync`
-conflict action means, and troubleshooting.
+## How it compares
 
-**One command:**
+| | Skills / Rules | MCP | Memory | Secret hygiene | Agents covered |
+|---|---|---|---|---|---|
+| [ai-rules](https://github.com/block/ai-rules), [skills-link](https://github.com/shanliuling/skills-link), [agent_sync](https://github.com/yelmuratoff/agent_sync) | ✅ | ❌ | ❌ | ❌ | Many — but not Kiro or pi |
+| [skillshare](https://github.com/runkids/skillshare), [skills-hub](https://github.com/qufei1993/skills-hub) | ✅ skills only | ❌ | ❌ | ❌ | Codex, Claude, … |
+| [mcp-router](https://github.com/mcp-router/mcp-router) | ❌ | ✅ desktop router | ❌ | config in its own dashboard | — |
+| [MetaMCP](https://github.com/metatool-ai/metamcp), [mcp-hub](https://github.com/ravitemer/mcp-hub) | ❌ | ✅ aggregator | ❌ | ❌ | — |
+| [cli-agent-orchestrator](https://github.com/awslabs/cli-agent-orchestrator) | ❌ | ❌ | ❌ | ❌ | Runs agent fleets, doesn't unify config |
+| **Trellis** | ✅ | ✅ native config, Runtime, or hub mode | ✅ shared memory + handoffs | ✅ references only, `secrets audit` | Claude Code, Codex, Kiro, pi, Kimi Code, ZCode |
 
-```
-trellis onboard
-```
+Sync tools stop at rules and skills. MCP routers manage servers but hold their
+own config — a second source of truth (we hit real token drift with exactly
+that setup). Trellis is the only one treating Skills + MCP + Memory +
+instructions as **one** canonical system, and the only one covering Kiro and
+pi. Full landscape survey: [`docs/research.md`](docs/research.md).
 
-Creates canonical source, detects which of Claude Code/Codex/Kiro/pi/Kimi Code are on
-this machine, then resolves two independent choices: a **migration source**
-(read from — auto-selected if only one present agent has real content,
-prompted with a numbered choice if more than one, skippable if starting
-fresh; pass `--agent <id>` to skip the prompt) and a **managed set** (written
-to — zero or more agents, chosen explicitly; pass `--manage <ids>` or
-`--manage none` to skip the prompt). The source is **not** managed by
-default — importing from Claude Code doesn't mean Trellis starts writing to
-Claude Code too, unless you explicitly include it. Selecting an agent that
-isn't installed yet (e.g. pi) 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. Once resolved, it
-runs `migrate`, `sync`, `mcp sync`, and `secrets audit` against the managed
-set — the whole onboarding path in one command, no follow-up commands to
-type by hand. If no agent is detected, it prints each supported agent's
-real install command/URL and stops — it never installs anything on its own
-initiative. Add `--dry-run` to preview the whole thing with zero writes.
-
-Onboarding only adds to the existing managed set. To deliberately narrow or
-replace Trellis's future write boundary without touching an agent's current
-native state, use `trellis manage list|set|add|remove`; these mutations are
-dry-runnable and backed by `trellis rollback`.
+## Design principles
 
-```
-trellis onboard --agent claude-code --manage pi
-```
+1. **One canonical source, many adapters** — agent-native configs are
+   generated artifacts, never hand-edited.
+2. **No plaintext secrets, ever** — outputs hold variable references;
+   `trellis secrets audit` rejects raw values.
+3. **Verify, don't assume** — every adapter claim is backed by an executed
+   probe in isolated Docker sandboxes, never a developer's own dotfiles.
 
-## Trellis itself as a Skill
-
-Trellis ships one package-owned Skill, `trellis-runtime`, with two layers:
-
-| Layer | Who uses it | What it covers |
-| --- | --- | --- |
-| Takeover and migration | the operator, with Agent assistance | inspect, dry-run, choose a migration source, choose the managed boundary, select Skills/MCP/Memory, authorize OAuth, sync, audit, verify, and rollback |
-| Runtime consumption | every managed Agent | discover and read canonical Skills, inspect shared Memory and global instructions, diagnose MCP, see managed Agents, and inspect or explicitly confirm task handoffs |
-
-`trellis init` bootstraps this Skill into
-`~/.trellis/skills/trellis-runtime/SKILL.md`. After an Agent is managed,
-`trellis sync` delivers it in the Agent's native Skill location for native or
-`both` delivery. For Runtime-only delivery, `SkillProvider` exposes the same
-canonical Skill through the `trellis` MCP Runtime; Kimi Code uses
-`trellis kimi` to prevent a second native Skill discovery path. This is one
-canonical Skill, not a copied per-Agent variant.
-
-Before takeover, the Skill cannot be consumed from an Agent that has not been
-connected to Trellis yet; use the CLI and
-[`docs/getting-started.md`](docs/getting-started.md#trellis-runtime-skill)
-for the first-run path. After takeover, the Skill is the Agent's operating
-guide for Trellis-managed capabilities. The MCP client may display names such
-as `mcp__trellis__skills_search`; `mcp__` is client-generated, while Trellis's
-portable names are `skills_search`, `memory_search`, `runtime_status`, and so
-on.
-
-**Or step by step** (what `onboard` is actually doing under the hood, if you
-want to run any one stage on its own):
-
-For standard MCP Router/client exports, use `trellis mcp import <json-file>`.
-It reads `mcpServers` without changing the source, de-duplicates existing
-servers, extracts credential-like environment values into the ignored local
-secret file, converts supported `mcp-remote` Basic Auth entries to native HTTP,
-and reports unsupported inline credentials or unavailable paths.
-Always run it with `--dry-run` first; see the detailed importer rules in
-[`docs/getting-started.md`](docs/getting-started.md).
-
-After upgrading Trellis, refresh the package-owned Runtime Skill with
-`trellis skill update-builtin --dry-run` followed by
-`trellis skill update-builtin`; the operation is backed up and does not require
-editing Agent-native files.
-
-**Already using Claude Code, Codex, Kiro, or pi and want to migrate what you
-already have?**
-
-1. `trellis init` — creates `~/.trellis/` with a minimal skeleton (only what's
-   missing; never overwrites a file you already have) and tells you which of
-   the five supported agents it found on this machine.
-2. `trellis migrate --from <agent>` — once per agent you already use. Copies
-   that agent's real skills and instructions into canonical source. Never
-   overwrites: an already-identical skill is reported and skipped, a genuine
-   conflict is reported and left for you to resolve by hand. Add `--dry-run`
-   to preview first.
-3. `trellis sync` — distributes canonical skills/instructions to every
-   **managed** agent (`~/.trellis/managed.yaml` — empty by default; edit it
-   by hand or let `trellis onboard` write it). An agent that's merely present
-   but not managed is never touched. Add `--dry-run` to preview first.
-4. `trellis mcp sync` — distributes `~/.trellis/mcp/servers.yaml` (see
-   [`schema/servers.example.yaml`](schema/servers.example.yaml)) to every
-   managed agent's native MCP config, including ownership-safe removal.
-5. `trellis secrets audit` — fails non-zero if any managed agent's real
-   config holds a literal credential or an unexpected env var name.
-6. `trellis doctor` — read-only scan of every present agent's current state
-   (managed or not); run any time to check for drift.
-
-**Starting from nothing?** Skip step 2 — `trellis init`'s placeholder
-`agents.md` and empty `skills/` are a fine starting point; edit them by hand.
-
-**Every real write `sync`/`mcp sync`/`onboard` perform is backed up
-first, automatically — no flag to opt in.** Before creating, repairing,
-or removing anything, each is recorded to a structured, timestamped run
-under `~/.trellis/backups/`, with enough information to invert it exactly.
-`trellis rollback` undoes one recorded run — omit a run id for the most
-recent one:
+Trellis aligns with the emerging [`.agents Protocol`](https://dotagentsprotocol.com)
+draft rather than inventing another standard.
 
-```
-$ trellis rollback
-rollback 2026-09-13T04-52-18-727Z-mcp-sync
-✅ 3 restored, 0 conflict(s), 0 already reverted
-   - [restore] restore /Users/you/.claude.json to its content before this run (...)
-```
+## Docs
 
-If something else touched a path since the backed-up run, that one path
-is a `conflict` — reported, left untouched, never force-restored over —
-while every other path in the same rollback still restores. `--list`
-shows available runs without touching anything; `--dry-run` previews a
-restore with zero writes.
+- [Overview](docs/overview.md) ([中文](docs/overview.zh-CN.md)) — what it is and why
+- [Getting started](docs/getting-started.md) — every command, with example output
+- [Architecture](docs/architecture.md) — what we build vs. deliberately reuse
+- [Research](docs/research.md) — the full competitive landscape
 
 ## Status
 
-**Early, pre-1.0.** The CLI commands above are implemented, unit-tested, and
-verified against isolated Linux Docker scenarios (never a developer's own
-dotfiles during development — see
-[`docs/architecture.md`](docs/architecture.md)'s testing philosophy). The
-sandbox matrix covers migration, steady-state management, runtime routing,
-failure isolation, and expected conflicts. A separate agent image installs
-real Codex, Claude Code, Kiro CLI, and pi binaries to verify their isolated
-configuration behavior. `onboard` picks one agent as the migration base when
-more than one is present; merging differing content across multiple agents
-into one result is named future work, not built yet.
-
-**Known limitations, honestly stated rather than discovered the hard way:**
-- MCP servers are never spawned/handshake-tested by `trellis mcp sync` or
-  `trellis sync` — only that 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`) has been verified to
-  load and register tools without erroring, never against a real LLM tool
-  call in production.
-- Verification has run against real Docker containers and real isolated
-  Codex, Claude Code, Kiro CLI, and pi installs — not against a developer's
-  actual daily-use agent directories. If you hit something a clean-room
-  sandbox wouldn't have caught, please open an issue.
-- `~/.trellis/backups/` has no automatic pruning yet — every `sync`/
-  `mcp sync`/`onboard`/`mcp import` run that performs a real write adds one more run
-  directory, with no cap. Delete old ones by hand for now.
-
-A canonical MCP server can also declare `enabled: false` (kept defined,
-never written to any agent) and `static_env` (a value that was never a
-secret — an email, an environment tag — written verbatim instead of
-resolved by name; still scanned against `reject_patterns` like every
-other literal field). Before ever writing a name-only `env` entry,
-`mcp sync` now checks it actually resolves through the same source
-`secrets audit` and the pi bridge use — an unresolvable name is refused
-as a conflict, not silently written and left to break that server's
-connection once the agent starts it. Both found via real-machine
-dogfooding, not a synthetic fixture — see
-[`schema/servers.example.yaml`](schema/servers.example.yaml).
-
-## Design principles
-
-1. **One canonical source, many adapters.** Each agent's native config file is
-   a generated or symlinked artifact, never hand-edited.
-2. **Reuse before building.** MCP aggregation, memory, and secret-reference
-   patterns already have mature open source answers — Trellis wires to them
-   instead of reimplementing them. See [`docs/architecture.md`](docs/architecture.md).
-3. **No plaintext secrets, ever.** Every adapter output holds variable
-   references only; `trellis secrets audit` scans for and rejects raw values.
-4. **Verify, don't assume.** Every claim this project makes about an agent's
-   behavior (file format, discovery path, MCP support) is backed by an
-   executed probe, not documentation-reading. Adapters that can't be verified
-   this way don't ship.
+**Early, pre-1.0.** All CLI commands are implemented, unit-tested, and verified
+against real agents in isolated containers. Known limitations are listed in
+[Getting started](docs/getting-started.md); please open an issue for anything
+a clean-room sandbox wouldn't catch.
 
 ## License
 

package/dist/adapters/zcode.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Runtime-first ZCode adapter.
+ *
+ * ZCode's native `~/.agents/skills` scan prevents scope-safe native delivery,
+ * so Runtime-only delivery uses one MCP Runtime edge and turns off the two
+ * native Skill switches through a ledger-backed, reversible config change.
+ */
+import type { AdapterPlanItem, AdapterProbeResult, AdapterVerifyResult, TrellisAdapter } from "../core/adapter.js";
+import type { CanonicalSource } from "../core/types.js";
+import type { BackupSession } from "../lib/backup.js";
+export declare class ZcodeAdapter implements TrellisAdapter {
+    private readonly homeDir;
+    private readonly env;
+    readonly name = "ZCode";
+    readonly id: "zcode";
+    constructor(homeDir?: string, env?: NodeJS.ProcessEnv);
+    probe(): Promise<AdapterProbeResult>;
+    plan(canonical: CanonicalSource): Promise<AdapterPlanItem[]>;
+    apply(plan: AdapterPlanItem[], backup: BackupSession): Promise<void>;
+    verify(canonical: CanonicalSource): Promise<AdapterVerifyResult>;
+}

package/dist/adapters/zcode.js

@@ -0,0 +1,234 @@
+/**
+ * Runtime-first ZCode adapter.
+ *
+ * ZCode's native `~/.agents/skills` scan prevents scope-safe native delivery,
+ * so Runtime-only delivery uses one MCP Runtime edge and turns off the two
+ * native Skill switches through a ledger-backed, reversible config change.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { isInScope } from "../core/adapter.js";
+import { capabilityDeliveryForAgent, usesNativeCapabilityDelivery } from "../core/types.js";
+import { applySymlinkPlan, planSymlinks } from "./symlinkPlan.js";
+import { renderJsonServerEntry } from "./jsonMcp.js";
+import { LEGACY_GATEWAY_ENTRY_NAME, LEGACY_RUNTIME_ENTRY_NAME, resolveMcpPlan } from "./mcpPlan.js";
+import { deepEqual } from "../lib/deepEqual.js";
+import { forgetOwned, loadMcpOwnership, ownedByAgent, recordOwned, saveMcpOwnership } from "../lib/mcpOwnership.js";
+import { forgetZcodeSettingsOwnership, loadZcodeSettingsOwnership, saveZcodeSettingsOwnership } from "../lib/zcodeOwnership.js";
+import * as zcodeProbe from "../probes/zcode.js";
+function readConfig(path) {
+    if (!existsSync(path))
+        return undefined;
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function zcodeServers(parsed) {
+    return record(record(parsed?.mcp).servers);
+}
+function planZcodeMcp(opts) {
+    const { desired, conflicts } = resolveMcpPlan("zcode", opts.mcp, opts.managedAgents, opts.policy);
+    const existing = zcodeServers(opts.parsed);
+    const items = [];
+    for (const { name, def } of desired) {
+        const rendered = renderJsonServerEntry(def);
+        if (deepEqual(existing[name], rendered))
+            continue;
+        items.push({
+            action: "create",
+            kind: "mcp",
+            target: opts.configPath,
+            mcpWrite: { name, def },
+            description: `MCP server "${name}" ${existing[name] === undefined ? "created" : "updated"} in ${opts.configPath}`,
+        });
+    }
+    for (const conflict of conflicts) {
+        items.push({ action: "conflict", kind: "mcp", target: opts.configPath, description: conflict.message, ...(conflict.remediation ? { remediation: conflict.remediation } : {}) });
+    }
+    const desiredNames = new Set(desired.map((entry) => entry.name));
+    for (const [name, expected] of Object.entries(opts.ownership)) {
+        if (desiredNames.has(name))
+            continue;
+        if ((name === LEGACY_GATEWAY_ENTRY_NAME || name === LEGACY_RUNTIME_ENTRY_NAME) && desiredNames.has("trellis"))
+            continue;
+        if (existing[name] === undefined || !deepEqual(existing[name], expected))
+            continue;
+        items.push({
+            action: "remove",
+            kind: "mcp",
+            target: opts.configPath,
+            mcpRemove: { name },
+            description: `MCP server "${name}" removed from ${opts.configPath} — no longer in canonical`,
+        });
+    }
+    return items;
+}
+function applyZcodeMcp(parsed, items) {
+    const base = parsed ?? {};
+    const mcp = record(base.mcp);
+    const servers = { ...record(mcp.servers) };
+    for (const item of items) {
+        if (item.kind !== "mcp")
+            continue;
+        if (item.action === "create" && item.mcpWrite)
+            servers[item.mcpWrite.name] = renderJsonServerEntry(item.mcpWrite.def);
+        if (item.action === "remove" && item.mcpRemove)
+            delete servers[item.mcpRemove.name];
+    }
+    return { ...base, mcp: { ...mcp, servers } };
+}
+function currentSkillControls(parsed) {
+    const features = record(parsed?.features);
+    const skills = record(parsed?.skills);
+    return {
+        featuresSkill: typeof features.skill === "boolean" ? features.skill : null,
+        skillsEnabled: typeof skills.enabled === "boolean" ? skills.enabled : null,
+    };
+}
+function applySkillControls(parsed, controls) {
+    const features = { ...record(parsed.features) };
+    const skills = { ...record(parsed.skills) };
+    if (controls.featuresSkill === null)
+        delete features.skill;
+    else
+        features.skill = controls.featuresSkill;
+    if (controls.skillsEnabled === null)
+        delete skills.enabled;
+    else
+        skills.enabled = controls.skillsEnabled;
+    return { ...parsed, features, skills };
+}
+export class ZcodeAdapter {
+    homeDir;
+    env;
+    name = "ZCode";
+    id = "zcode";
+    constructor(homeDir = homedir(), env = process.env) {
+        this.homeDir = homeDir;
+        this.env = env;
+    }
+    async probe() {
+        const snapshot = await zcodeProbe.probe(this.homeDir, { env: this.env });
+        return { present: snapshot.present, version: snapshot.version, ...(snapshot.diagnostics.length ? { detail: snapshot.diagnostics.join("; ") } : {}) };
+    }
+    async plan(canonical) {
+        const profile = zcodeProbe.resolveZcodeProfile(this.homeDir, this.env);
+        if (!profile)
+            return [];
+        const parsed = readConfig(profile.configPath);
+        const canonicalRoot = dirname(canonical.instructionsFile);
+        const runtimeOnly = capabilityDeliveryForAgent(this.id, canonical.mcp) === "mcp";
+        const items = [];
+        items.push(...planSymlinks({
+            rootDir: join(this.homeDir, ".zcode", "skills"),
+            desired: usesNativeCapabilityDelivery(this.id, canonical.mcp)
+                ? canonical.skills.filter((skill) => isInScope(this.id, skill.scope, canonical.managedAgents)).map((skill) => ({ name: skill.name, target: skill.dir }))
+                : [],
+            canonicalRoot: join(canonicalRoot, "skills"),
+            kind: "skill",
+        }));
+        items.push(...planSymlinks({
+            rootDir: join(this.homeDir, ".zcode"),
+            desired: [{ name: "AGENTS.md", target: canonical.instructionsFile }],
+            canonicalRoot,
+            kind: "instructions",
+        }));
+        items.push(...planZcodeMcp({
+            configPath: profile.configPath,
+            parsed,
+            mcp: canonical.mcp,
+            managedAgents: canonical.managedAgents,
+            policy: canonical.secretsPolicy,
+            ownership: ownedByAgent(loadMcpOwnership(this.homeDir), this.id),
+        }));
+        const current = currentSkillControls(parsed);
+        const ownership = loadZcodeSettingsOwnership(this.homeDir);
+        if (runtimeOnly && (current.featuresSkill !== false || current.skillsEnabled !== false)) {
+            items.push({
+                action: "create",
+                kind: "zcode-skill-control",
+                target: profile.configPath,
+                zcodeSkillControls: { featuresSkill: false, skillsEnabled: false, previous: current },
+                description: `native ZCode Skill discovery disabled in ${profile.configPath} for Runtime-only delivery`,
+            });
+        }
+        else if (!runtimeOnly && ownership?.configPath === profile.configPath && current.featuresSkill === false && current.skillsEnabled === false) {
+            items.push({
+                action: "remove",
+                kind: "zcode-skill-control",
+                target: profile.configPath,
+                zcodeSkillControls: { ...ownership.previous },
+                description: `previous native ZCode Skill settings restored in ${profile.configPath}`,
+            });
+        }
+        return items;
+    }
+    async apply(plan, backup) {
+        await applySymlinkPlan(plan.filter((item) => item.kind === "skill" || item.kind === "instructions"), backup);
+        const configItems = plan.filter((item) => (item.kind === "mcp" || item.kind === "zcode-skill-control") && (item.action === "create" || item.action === "remove"));
+        if (configItems.length === 0)
+            return;
+        const configPath = configItems[0].target;
+        let merged = applyZcodeMcp(readConfig(configPath), configItems);
+        const control = configItems.find((item) => item.kind === "zcode-skill-control")?.zcodeSkillControls;
+        if (control)
+            merged = applySkillControls(merged, control);
+        backup.writeFile(configPath, `${JSON.stringify(merged, null, 2)}\n`);
+        let ownership = loadMcpOwnership(this.homeDir);
+        for (const item of configItems) {
+            if (item.kind !== "mcp")
+                continue;
+            if (item.action === "create" && item.mcpWrite)
+                ownership = recordOwned(ownership, this.id, item.mcpWrite.name, renderJsonServerEntry(item.mcpWrite.def));
+            if (item.action === "remove" && item.mcpRemove)
+                ownership = forgetOwned(ownership, this.id, item.mcpRemove.name);
+        }
+        saveMcpOwnership(this.homeDir, ownership);
+        const controlItem = configItems.find((item) => item.kind === "zcode-skill-control");
+        if (controlItem?.action === "create" && controlItem.zcodeSkillControls?.previous) {
+            saveZcodeSettingsOwnership(this.homeDir, {
+                configPath,
+                managed: { featuresSkill: false, skillsEnabled: false },
+                previous: controlItem.zcodeSkillControls.previous,
+            });
+        }
+        else if (controlItem?.action === "remove") {
+            forgetZcodeSettingsOwnership(this.homeDir);
+        }
+    }
+    async verify(canonical) {
+        const snapshot = await zcodeProbe.probe(this.homeDir, { env: this.env });
+        if (!snapshot.present)
+            return { ok: false, mismatches: ["zcode is not present on this machine"] };
+        const profile = zcodeProbe.resolveZcodeProfile(this.homeDir, this.env);
+        if (!profile)
+            return { ok: false, mismatches: ["zcode profile cannot be selected"] };
+        const mismatches = [];
+        const desiredNativeSkills = canonical.skills
+            .filter((skill) => usesNativeCapabilityDelivery(this.id, canonical.mcp) && isInScope(this.id, skill.scope, canonical.managedAgents))
+            .map((skill) => skill.name);
+        const actualNativeSkills = new Set(snapshot.skillRoots.filter((root) => root.path === join(this.homeDir, ".zcode", "skills")).flatMap((root) => root.skills.map((skill) => skill.name)));
+        for (const name of desiredNativeSkills)
+            if (!actualNativeSkills.has(name))
+                mismatches.push(`skill "${name}" is missing on ZCode`);
+        const expectedMcp = planZcodeMcp({
+            configPath: profile.configPath,
+            parsed: readConfig(profile.configPath),
+            mcp: canonical.mcp,
+            managedAgents: canonical.managedAgents,
+            policy: canonical.secretsPolicy,
+            ownership: ownedByAgent(loadMcpOwnership(this.homeDir), this.id),
+        }).filter((item) => item.action === "create" || item.action === "conflict");
+        mismatches.push(...expectedMcp.map((item) => item.description));
+        if (!snapshot.instructionsFile?.isSymlink || snapshot.instructionsFile.target !== canonical.instructionsFile)
+            mismatches.push("shared instructions are not linked into ~/.zcode/AGENTS.md");
+        if (capabilityDeliveryForAgent(this.id, canonical.mcp) === "mcp") {
+            const controls = currentSkillControls(readConfig(profile.configPath));
+            if (controls.featuresSkill !== false || controls.skillsEnabled !== false)
+                mismatches.push("native ZCode Skill discovery is still enabled during Runtime-only delivery");
+        }
+        return mismatches.length === 0 ? { ok: true } : { ok: false, mismatches };
+    }
+}

package/dist/cli.js

@@ -16,7 +16,7 @@ import { runMcpAuth } from "./commands/mcpAuth.js";
 import { runSecretsAudit } from "./commands/secretsAudit.js";
 import { runRollback } from "./commands/rollback.js";
 import { runSkillList, runSkillAdd, runSkillRemove, runSkillUpdateBuiltin } from "./commands/skill.js";
-import { runMemoryExtraction, runMemorySync } from "./commands/memory.js";
+import { collectMemoryList, runMemoryExtraction, runMemorySync } from "./commands/memory.js";
 import { parseManageArgs, runManage } from "./commands/manage.js";
 import { runKimi } from "./commands/kimi.js";
 import { TRELLIS_VERSION } from "./lib/cliMetadata.js";
@@ -130,8 +130,9 @@ Commands:
             upstream capabilities; existing mcp-gateway configs remain valid
             as a compatibility alias
   mcp remove <name>
-            Remove a canonical MCP server (canonical-side only — does
-              not touch any agent's already-synced native config)
+            Remove a canonical MCP server, then run the same sync as
+            mcp sync so every managed agent's Trellis-owned entry for
+            it is removed too
               --dry-run    preview the plan, write nothing
               --json       machine-readable output, no report text
   skill list
@@ -325,12 +326,12 @@ async function main(argv) {
         }
         if (subcommand === "add") {
             const [name] = mcpRest;
-            process.exitCode = runMcpAdd(name, parseMcpAddArgs(mcpRest), { json, dryRun }).exitCode;
+            process.exitCode = (await runMcpAdd(name, parseMcpAddArgs(mcpRest), { json, dryRun })).exitCode;
             return;
         }
         if (subcommand === "import") {
             const [file] = mcpRest;
-            process.exitCode = runMcpImport(file, { json, dryRun }).exitCode;
+            process.exitCode = (await runMcpImport(file, { json, dryRun })).exitCode;
             return;
         }
         if (subcommand === "set") {
@@ -347,7 +348,7 @@ async function main(argv) {
                 process.exitCode = 1;
                 return;
             }
-            process.exitCode = runMcpRemove(name, { json, dryRun }).exitCode;
+            process.exitCode = (await runMcpRemove(name, { json, dryRun })).exitCode;
             return;
         }
         if (subcommand === "auth") {
@@ -382,7 +383,7 @@ async function main(argv) {
                 process.exitCode = 1;
                 return;
             }
-            process.exitCode = runSkillAdd(name, from, { json, dryRun }).exitCode;
+            process.exitCode = (await runSkillAdd(name, from, { json, dryRun })).exitCode;
             return;
         }
         if (subcommand === "remove") {
@@ -392,7 +393,7 @@ async function main(argv) {
                 process.exitCode = 1;
                 return;
             }
-            process.exitCode = runSkillRemove(name, { json, dryRun }).exitCode;
+            process.exitCode = (await runSkillRemove(name, { json, dryRun })).exitCode;
             return;
         }
         if (subcommand === "update-builtin") {
@@ -407,6 +408,21 @@ async function main(argv) {
         const [subcommand, ...memoryRest] = rest;
         const json = memoryRest.includes("--json");
         const dryRun = memoryRest.includes("--dry-run");
+        if (subcommand === "list") {
+            const entries = collectMemoryList();
+            if (json) {
+                console.log(JSON.stringify(entries, null, 2));
+            }
+            else if (entries.length === 0) {
+                console.log("No memories in canonical source yet.");
+            }
+            else {
+                for (const { name, scope } of entries) {
+                    console.log(`${name} — ${scope.length > 0 ? scope.join(", ") : "(no managed agent reaches it)"}`);
+                }
+            }
+            return;
+        }
         if (subcommand === "sync") {
             process.exitCode = runMemorySync({ json, dryRun }).exitCode;
             return;
@@ -415,7 +431,7 @@ async function main(argv) {
             process.exitCode = runMemoryExtraction({ json, dryRun }).exitCode;
             return;
         }
-        console.error(`Unknown memory subcommand: ${subcommand ?? "(none)"}\nUsage: trellis memory sync|extract\n`);
+        console.error(`Unknown memory subcommand: ${subcommand ?? "(none)"}\nUsage: trellis memory list|sync|extract\n`);
         process.exitCode = 1;
         return;
     }

package/dist/commands/doctor.js

@@ -10,6 +10,7 @@ import * as codexProbe from "../probes/codex.js";
 import * as kiroProbe from "../probes/kiro.js";
 import * as piProbe from "../probes/pi.js";
 import * as kimiCodeProbe from "../probes/kimi-code.js";
+import * as zcodeProbe from "../probes/zcode.js";
 import { loadCanonicalSource } from "../core/canonical.js";
 import { GATEWAY_ENTRY_NAME, RUNTIME_ENTRY_NAME, resolveMcpPlan } from "../adapters/mcpPlan.js";
 import { ALL_AGENTS } from "../core/types.js";
@@ -76,6 +77,7 @@ export async function collectDoctorReport(homeDir = homedir(), knownHostInjected
         { agent: "kiro", run: () => kiroProbe.probe(homeDir, { probeMcp }) },
         { agent: "pi", run: () => piProbe.probe(homeDir) },
         { agent: "kimi-code", run: () => kimiCodeProbe.probe(homeDir, { probeMcp }) },
+        { agent: "zcode", run: () => zcodeProbe.probe(homeDir, { probeMcp }) },
     ];
     // One agent erroring must not blank the other three's results.
     const settled = await Promise.allSettled(probeList.map((p) => p.run()));

package/dist/commands/init.d.ts

@@ -29,7 +29,7 @@ export interface InitReport {
 /** Exported so `migrate` can byte-compare canonical `agents.md` against
  * this exact string (design.md D3, trellis-cli-migrate) rather than
  * retyping an equivalent one that could silently drift from this. */
-export declare const AGENTS_MD_TEMPLATE = "# Shared instructions\n\nWrite what every agent should know here \u2014 communication preferences,\nproject conventions, anything you'd otherwise repeat per agent.\n\nAlready using Claude Code, Codex, Kiro, pi, or Kimi Code? `trellis migrate --from\n<agent>` imports its real instructions and skills instead of starting\nfrom this placeholder.\n";
+export declare const AGENTS_MD_TEMPLATE = "# Shared instructions\n\nWrite what every agent should know here \u2014 communication preferences,\nproject conventions, anything you'd otherwise repeat per agent.\n\nAlready using Claude Code, Codex, Kiro, pi, Kimi Code, or ZCode? `trellis migrate --from\n<agent>` imports its real instructions and skills instead of starting\nfrom this placeholder.\n";
 /**
  * Trellis never spawns an installer itself (global package installs are
  * exactly the kind of irreversible, system-wide action that needs the