agent-trellis 0.1.0

package/docs/architecture.md

@@ -0,0 +1,367 @@
+# Architecture
+
+This document is for contributors and anyone evaluating Trellis's internals
+— how adapters are built, why they're built the way they are, and the
+testing discipline behind that. If you just want to *use* Trellis, see
+[`docs/getting-started.md`](getting-started.md) instead; nothing below is
+required reading for that.
+
+## Layers and who owns each one
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Trellis canonical source  (~/.trellis — global only, see  │
+│  "Global vs. workspace scope" below)                        │
+│  instructions · skills · agents · mcp/servers.yaml ·      │
+│  memories · secrets policy                                 │
+└───────────────┬─────────────────────────────────────────┘
+                │  trellis sync / trellis doctor
+        ┌───────┼────────┬─────────────┬──────────────┐
+        ▼                ▼             ▼              ▼
+   Claude Code         Codex          Kiro            pi
+  (symlink adapter) (incremental   (symlink adapter) (bridge
+                     TOML writer)                    extension)
+```
+
+Trellis owns exactly one thing: **the canonical source, and the generators
+that turn it into each agent's native format.** It does not own MCP
+transport, memory storage, or secret storage — those are delegated (see
+[`research.md`](research.md)).
+
+## Canonical schema
+
+Aligned to the `.agents Protocol` draft, extended where the draft is silent:
+
+```
+.trellis/
+├── agents.md                # instructions, AGENTS.md-compatible
+├── skills/<name>/SKILL.md   # exact filename required — see research.md
+├── agents/<name>.md         # subagent profiles (Claude-format frontmatter
+│                             # today; this is the layer with no cross-agent
+│                             # equivalent yet — Codex has no persistent
+│                             # subagent concept, see research.md)
+├── mcp/servers.yaml          # single MCP source, values are var-name
+│                             # references only, never literals
+├── memories/*.md             # shared memory entries (server-memory backed)
+├── scope.yaml                 # exceptions to "shared with all agents" —
+│                             # see "Private / agent-specific capabilities"
+├── secrets.policy.yaml       # which var names are allowed, nothing else
+└── trellis.lock.json         # NOT YET BUILT — planned ownership-tracking
+                              # file for MCP removal (docs/roadmap.md's P2
+                              # note); nothing in src/ reads or writes this
+```
+
+## Global vs. workspace scope
+
+**Global only, for now.** Trellis manages `~/.trellis` — one canonical
+source per machine, applied to that machine's four agents. It does not yet
+read or merge a project-local `.trellis/` in a specific repo.
+
+The `.agents Protocol` draft (see `research.md`) describes a two-layer
+merge — global defaults, workspace overrides on top, closest wins. That
+model is a reasonable target eventually, but it's explicitly **out of
+scope until a later phase**: it adds real complexity (merge precedence,
+per-project drift, a second place secrets policy has to be checked) that
+isn't justified before the single-layer global case is solid. Don't build
+workspace resolution ahead of that decision — if you find yourself adding
+a `root?: string` parameter or precedence logic to `loadCanonicalSource`,
+that's scope creep against this section, not a natural extension.
+
+## Private / agent-specific capabilities
+
+Not everything belongs to all four agents. A skill built around Claude
+Code's Task-based subagent delegation has no equivalent to delegate to on
+Codex; an MCP server might only make sense for one agent's workflow. Every
+scopable item — skill, subagent profile, memory entry, MCP server —
+defaults to "shared with all four," and can be restricted with an explicit
+`scope` (skills/agents/memories) or inline `agents:` (MCP servers, see
+below). Restriction is the exception you declare, not something you
+configure for the common case.
+
+**Skills, subagent profiles, and memory entries declare scope in
+`.trellis/scope.yaml`, never inside the artifact file itself.** This
+isn't a style preference: Codex validates `SKILL.md` frontmatter against
+an allow-list of recognized keys and rejects files with unknown ones (see
+`research.md`) — a Trellis-only `scope:` field written into a skill's own
+frontmatter would break that skill specifically on Codex. Keeping scope
+declarations in a separate manifest means every artifact stays a clean,
+portable file exactly as its target agent's own spec expects; Trellis's
+own bookkeeping lives next to it, not inside it. See
+`schema/scope.example.yaml`.
+
+**MCP servers are the one exception** — `agents:` is declared inline per
+server in `mcp/servers.yaml` (see `schema/servers.example.yaml`), because
+that file is Trellis's own format and is never handed to an agent
+directly; every adapter translates it into that agent's native shape, so
+there's no risk of an agent choking on an unrecognized field the way Codex
+does with SKILL.md.
+
+Every `TrellisAdapter.plan()` implementation must filter the canonical
+source through scope before producing any plan item for it — an item
+scoped away from that adapter's agent must never appear in its plan at
+all. See `src/core/adapter.ts`'s `isInScope` helper and the obligation
+documented on `plan()` itself.
+
+## Adapter contract
+
+Every adapter must implement:
+
+- `probe()` — does this agent exist on this machine, what version
+- `plan(canonical)` — diffs canonical against this agent's current on-disk
+  state (read-only, but it does read — create/remove/no-op/conflict can't
+  be decided from canonical alone) and produces `AdapterPlanItem[]`, each
+  tagged `"create"`, `"remove"`, or `"conflict"`. **Must emit `"remove"`
+  items**, not just `"create"`: a Trellis-managed symlink (realpath
+  resolves inside the canonical source) whose entry was deleted from
+  canonical or scoped away from this agent is stale and belongs in the
+  plan — see `src/core/adapter.ts`'s `plan()` doc. A real, non-symlink path
+  occupying a spot Trellis would otherwise touch is a `"conflict"` item,
+  not a thrown error — it must show up in the same report as everything
+  else, not abort the whole run over one unrelated item.
+- `apply(plan)` — perform the diff; must be idempotent and re-runnable for
+  "create"/"remove", and must treat "conflict" as report-only (no I/O,
+  never throws) — see `src/core/adapter.ts`'s `apply()` doc for why this
+  responsibility sits with the caller (`trellis sync`), not per-item
+- `verify()` — re-read the agent's own state and confirm it matches
+  canonical; this is what `trellis doctor` calls
+
+No adapter is allowed to overwrite fields it doesn't own. Codex's adapter in
+particular must never rewrite `config.toml` wholesale — it must locate the
+target `[mcp_servers.<name>]` section and patch only that block, because
+Codex's own `config.toml` also holds mirasim-independent user settings
+(models, trust levels) that Trellis has no business touching.
+
+### Adapter-specific notes
+
+**Claude Code** — `~/.claude/skills`, `~/.claude/agents` become symlinks into
+the canonical source. `~/.claude.json`'s `mcpServers` is patched in place
+(JSON, so this is a simple merge). Values are always `${VAR}` references.
+When `mcp.hub` is set, this becomes one entry (the hub URL) instead of N.
+
+**Codex** — skills via `~/.agents/skills` symlink (Codex's own built-in
+convention, requires no Trellis-specific path). MCP via `codex mcp add`
+where possible; for env passthrough use `env_vars`, never `--env` with a
+literal secret value. Must check for name collisions against any host-
+injected servers (mirasim connectors) before writing — see research.md §3.
+When `mcp.hub` is set, only the single hub entry needs this check — there's
+nothing else defined locally for it to collide with.
+
+**Kiro** — same shape as Claude Code: `~/.kiro/skills` symlink,
+`~/.kiro/steering/CLAUDE.md` symlink, `~/.kiro/settings/mcp.json` patched
+like Claude's. Same hub-mode simplification applies.
+
+**pi** — same symlink shape as Claude Code/Kiro after all: `~/.pi/agent/skills`
+symlink, instructions symlinked to whichever of `AGENTS.override.md` /
+`AGENTS.md` / `CLAUDE.md` pi checks first (`~/.pi/agent/`, confirmed by
+direct source read — see `openspec/specs/agent-state-probing/spec.md`'s pi
+scenario). Pi *reads* these natively without any Trellis-specific parsing,
+but the files still have to physically exist at that path — nothing
+populates `~/.pi/agent/skills` on its own. (This corrects an earlier,
+pre-P0 assumption that pi needed "no adapter" for skills/instructions;
+that was written before pi's actual global discovery directory was
+confirmed, when it wasn't yet known whether canonical skills would ever
+reach it without one.) MCP is the one place pi is genuinely different: it
+needs a real bridge either way, but which shape depends on `mcp.hub`:
+without it, the bridge extension opens N `@modelcontextprotocol/sdk` stdio
+clients (one per server) and registers each one's tools through pi's
+`registerTool` API; with `mcp.hub` set, it opens exactly one HTTP client to
+the hub instead — meaningfully less code and one fewer class of failure
+(N processes to keep alive vs. one connection). This is the one piece of
+the project that is an agent runtime extension, not a config generator,
+regardless of hub mode.
+
+## MCP hub mode
+
+Every agent's MCP surface can be either N direct server definitions
+(default) or one static entry pointing at a single HTTP endpoint — set
+`mcp.hub.url` in `mcp/servers.yaml` to switch (see
+`schema/servers.example.yaml`). Nothing about *what* runs behind that URL
+is part of Trellis's design: a self-hosted
+[mcp-hub](https://github.com/ravitemer/mcp-hub) instance, a hosted
+mcp-router account, anything else speaking MCP over HTTP all look
+identical to every adapter — a URL. There is deliberately no "engine"
+switch in the type (`HubConfig` is just `{ url: string }`) or in adapter
+code — building one was tried and reverted as unneeded complexity for a
+distinction (self-hosted vs. hosted, generated-config vs.
+externally-managed) that only matters to the human choosing a hub, never
+to the code writing one entry that points at it.
+
+**What actually changes when `hub` is set:**
+- Every adapter writes ONE entry instead of N. This is most of the value:
+  adding a new backend server means editing wherever the hub's own config
+  lives (this project doesn't prescribe that either) and never touching
+  any of the four agents' configs or restarting them, if the hub supports
+  live reload (mcp-hub does, via SSE).
+- The collision check against `known_host_injected` (docs/research.md
+  §"Codex — three hard constraints") shrinks to checking one name instead
+  of N, since there's nothing else locally defined to collide with.
+- pi's bridge (P4) becomes one HTTP client instead of N stdio clients.
+
+**What doesn't change:** the boundary with mirasim (docs/research.md §3)
+is unaffected — `mcp.hub`, self-hosted or not, only ever carries the
+servers Trellis's own `servers.yaml` defines (local stdio, per that
+boundary); mirasim's remote-OAuth connectors are injected at the agent's
+own process level regardless of whether hub mode is on.
+
+**The trade-off, stated plainly:** self-hosting a hub (or paying for a
+hosted one) adds a moving part that direct mode doesn't have — if it's
+down, every agent loses MCP capability at once, not just one server. And
+if you point at a hub you manage outside Trellis (rather than one Trellis
+generates config for), that hub's own dashboard/config becomes a second
+place "what servers exist" is defined, outside `.trellis/` — this project
+hit that exact problem first-hand with a token going stale across three
+different values before `mcp.hub` existed as a concept (docs/research.md).
+Direct mode remains fully supported for anyone who'd rather not take that
+trade.
+
+## Static header auth vs. real OAuth for remote MCP servers
+
+A remote (`http`/`sse`-transport) MCP server needing a credential comes
+in two real shapes, and Trellis only ever builds for one of them.
+
+**Static header auth** (a bearer token or API key that doesn't expire on
+its own) is exactly like `env` for stdio servers: `McpServerDef.headers`
+holds `${VAR}` references, never a value, and each adapter renders it
+through its own real, verified schema — Claude Code and Kiro accept the
+identical plain `Record<string,string>` map; Codex has no generic
+headers concept at all, only a single purpose-built
+`bearer_token_env_var` field (confirmed by what `codex mcp add
+--bearer-token-env-var` itself generates) — a server needing more than
+one header simply can't reach Codex through Trellis, and is refused
+there (not silently dropped) while still reaching every other agent.
+
+**Real OAuth** (browser redirect, short-lived access token, refresh
+token) is not implemented anywhere in Trellis, on purpose. All three
+native-config agents already have their own real, working flow for it:
+
+- Claude Code: `claude mcp add --client-id/--client-secret/--callback-port`
+- Codex: a dedicated `codex mcp login`/`codex mcp logout` pair
+- Kiro: `oauth`/`oauthScopes` fields in its own real
+  `~/.kiro/settings/mcp.json` schema
+
+pi has none of this — its bridge is Trellis's own code, and the MCP
+SDK's `authProvider: OAuthClientProvider` option is a full
+redirect-and-refresh flow that doesn't fit a synchronously-loaded
+extension's lifecycle. A remote server that requires real OAuth simply
+isn't reachable through the pi bridge today — a real, stated limitation,
+not something papered over with a partial implementation.
+
+## What Trellis explicitly does not build
+
+- An MCP aggregator/gateway's actual routing/proxy logic (hub mode above
+  lets you point every agent at one, but Trellis doesn't implement one)
+- Real OAuth for remote MCP servers (browser redirect, token storage,
+  refresh) — every agent that has its own native flow keeps using it;
+  see "Static header auth vs. real OAuth" above
+- A memory backend (defaults to `@modelcontextprotocol/server-memory`,
+  documented in `schema/servers.example.yaml`; mem0/OpenMemory and
+  totalrecallai-class semantic-search servers documented as opt-in
+  upgrades — see docs/research.md "Shared memory")
+- A secret vault (reads `${VAR}` from whatever the environment already
+  provides — `~/.config/agent-env/secrets.env`, 1Password's `op run`,
+  anything that populates `process.env` before an adapter's generated
+  command runs)
+- A GUI (P5 in the roadmap evaluates embedding into an existing one —
+  mcp-router's or skills-hub's — before building a new one)
+
+## MCP handshake probing is opt-in, not default
+
+`trellis doctor`'s default run never spawns a configured MCP server — it
+only reads static config (name, transport, collision against
+`known_host_injected`). Live handshake probing (`src/lib/mcpProbe.ts`) is a
+real capability, unit-tested against a fixture server, but running it
+against every server configured on a real machine turned out not to be
+"read-only" in the sense that actually matters: some servers reach real
+external services with real credentials (OAuth-backed connectors,
+`chrome-devtools-mcp`'s `--autoConnect`), and doing this for a dozen-plus
+servers serially, once per agent, made a single default `trellis doctor`
+run take minutes and spawn processes with a meaningfully larger blast
+radius than "list what's configured." Pass `--probe-mcp` to opt in; the
+default stays fast, side-effect-free, and safe to run in a pre-commit hook
+or CI on every commit.
+
+## Testing philosophy: never verify against the developer's real environment
+
+**Hard rule, not a preference.** P0's probes are read-only, so they're safe
+to run against a real machine's real `~/.claude`, `~/.codex`, etc. — that's
+how `docs/research.md`'s findings were originally discovered, by hand,
+against a real machine, and P0 formalizes exactly that.
+
+Every phase from P1 onward writes: symlinks, in-place TOML/JSON patches,
+eventually credentials passing through a spawned process's env. **None of
+that is ever exercised against a developer's actual dotfiles, actual
+`~/.claude.json`, actual `~/.codex/config.toml`, or any other real
+configuration a person depends on for their day-to-day work** — not during
+development, not in CI, not for a "quick manual check." A bug in an adapter
+that patches TOML in place is exactly the kind of thing that corrupts a
+real config file if it's tested against one.
+
+**Exception: pi.** This rule protects real state a person depends on — the
+other three agents' adapters patch that state in place (symlinks over real
+directories, in-place TOML/JSON edits). pi's adapter never does: skills/
+instructions are the same symlink-or-noop regardless of machine, and the
+MCP bridge (P4) is a single already-symlinked extension file that reads a
+separate, Trellis-owned `servers.yaml` rather than writing into anything pi
+itself depends on. A temporary, narrowly-scoped `~/.trellis/mcp/servers.yaml`
+(deleted afterward) plus a real `pi -p` run therefore carries none of the
+corruption risk this section exists to prevent, and it's the only way to
+observe pi's actual extension-loading behavior on *this* installed pi/jiti
+version — `docker/pi-sandbox.Dockerfile` verifies the same jiti-tolerance in
+general (P4's own acceptance criteria), but doesn't stand in for a
+spot-check against a specific real installation. Real-machine verification
+of pi specifically is therefore permitted, not a hard-rule violation — the
+other three agents are not exempted.
+
+Verification happens against an isolated environment instead: a scratch
+`$HOME` (or a container with one mounted) populated with synthetic
+per-agent config that looks like the real thing but is expendable — created
+fresh, asserted against, thrown away. `docs/implementation-plan.md`'s P1
+acceptance criteria already describes this shape ("point at a scratch
+`$HOME`... run `trellis sync skills`... confirm zero findings"); this
+section exists to make it a project-wide rule that every later phase's
+acceptance criteria must follow, not a detail specific to P1.
+
+This is also why P0 needing to resolve pi's actual skill-discovery path
+(§D5 in `openspec/changes/trellis-doctor-p0/design.md`) is investigated
+directly against a real pi installation *as a read-only observation*, and
+that finding then gets encoded as a fixture for the isolated test
+environment — the real machine is where you learn the shape of the truth
+once; it is never where you repeatedly verify against it.
+
+### The actual mechanism: `scripts/sandbox.sh`
+
+```
+scripts/sandbox.sh                    # interactive shell in the sandbox
+scripts/sandbox.sh npm run dev doctor  # run a command in the sandbox
+```
+
+Backed by OrbStack (this machine's Docker context — a Mac-native,
+Apple-Virtualization-framework-backed runtime, not Docker Desktop; any
+Docker-compatible daemon works identically). `docker/sandbox.Dockerfile`
+builds a Node image containing the repo's `src/`; `docker/entrypoint.sh`
+copies `test/fixtures/home` (mounted **read-only**) into a container-local
+scratch `$HOME` before running anything, so no command executed inside the
+container can ever write back to the fixture files checked into git —
+verified directly: a write to the sandboxed `$HOME` during development
+left the host-side fixture byte-for-byte unchanged.
+
+`test/fixtures/home/` is a synthetic four-agent `$HOME` — fake
+`.claude.json`, `.codex/config.toml`, `.kiro/settings/mcp.json`,
+`.pi/agent/settings.json`, skill directories — built to exercise specific,
+known findings, not just to look plausible:
+
+- `.agents/skills/sample-skill/` vs. `.codex/skills/duplicate-skill/`:
+  byte-identical content at two different paths, deliberately, to exercise
+  `capability-drift-detection`'s duplication check against a real case
+  rather than an assertion with no failing fixture behind it.
+- `.codex/config.toml` defines an `mcp_servers.sentry` entry — a name that
+  also appears in `known_host_injected` (`schema/servers.example.yaml`) —
+  reproducing the exact collision class from `docs/research.md` (same-name
+  static + host-injected server) as a fixture, not just a comment
+  describing the risk.
+- `.kiro/skills/broken-case-skill/skill.md` — deliberately lowercase, to
+  exercise the case-sensitivity check.
+- `test/fixtures/sample-mcp-server.js` — a minimal real MCP server (reads
+  `initialize` over stdio, replies with fixed `serverInfo`) so
+  `probeMcpServer` has something deterministic to handshake against inside
+  the container without depending on a real npm package or network access.

package/docs/getting-started.md

@@ -0,0 +1,235 @@
+# Getting started
+
+This is the detailed walkthrough. For the short version see the
+[README Quick start](../README.md#quick-start).
+
+## Install
+
+```
+npm install -g agent-trellis
+```
+
+## `trellis onboard` — the one-command path
+
+```
+$ trellis onboard
+```
+
+Runs `init`, detects which of Claude Code/Codex/Kiro/pi are on this machine,
+picks one as the migration base, then runs `migrate` and `sync` against it.
+
+- **No agent detected**: prints each agent's real install command/URL and
+  stops. Never installs anything itself — that's your call.
+- **Exactly one agent detected**: auto-selected as the base, no prompt.
+- **Two or more detected**: prompts you to pick one (if you're at a real
+  terminal), or pass `--agent <id>` to skip the prompt — useful in scripts,
+  CI, or when running with `--json`, which never prompts.
+
+```
+$ trellis onboard --agent claude-code
+Using claude-code as the migration base (--agent).
+
+migrate --from claude-code
+  [create] skill "my-skill" — will copy from /Users/you/.claude/skills/my-skill
+  ...
+
+sync
+  ✅ codex — 1 created, 0 removed, 0 conflict(s)
+  ...
+
+Next: `trellis mcp sync` to distribute MCP servers, `trellis secrets audit` to check for leaked credentials.
+```
+
+Add `--dry-run` to preview the entire chain — init/migrate/sync — with zero
+writes anywhere.
+
+**Picking a base agent only picks one.** If you use two or more agents with
+genuinely different real content, onboard migrates from the one you (or it)
+chose; the others' own differing content is untouched, exactly as `migrate`
+would report it if run against them directly (see the conflict table
+below). Merging differing content across multiple agents into one result
+isn't built yet — see [README's Status](../README.md#status).
+
+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.
+
+## Two starting points
+
+**You already use one or more of Claude Code, Codex, Kiro, or pi** and have
+real skills/instructions in them today. Go to
+[Migrating from an existing agent](#migrating-from-an-existing-agent).
+
+**You're starting from nothing** — no agent configured yet, or you'd rather
+write canonical source by hand. Go to
+[Starting from nothing](#starting-from-nothing).
+
+Either way, run `trellis init` first.
+
+## `trellis init`
+
+```
+$ trellis init
+```
+
+Creates `~/.trellis/` with:
+
+- `agents.md` — shared instructions, starts as a placeholder
+- `mcp/servers.yaml` — starts as `servers: {}` (nothing defined yet)
+- `secrets.policy.yaml` — starts with the real `reject_patterns` this
+  project ships (credential-shape regexes), an empty `allowed_vars`
+- `skills/`, `agents/`, `memories/` — empty directories
+
+**Never overwrites a file you already have.** Re-running `trellis init` on a
+`~/.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.
+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
+effect of running this command.
+
+## Migrating from an existing agent
+
+For each agent you already use:
+
+```
+$ trellis migrate --from claude-code
+```
+
+```
+migrate --from claude-code
+  [create] skill "my-skill" — will copy from /Users/you/.claude/skills/my-skill
+  [already-migrated] skill "shared-skill" — canonical content is byte-identical
+  [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
+agent you actually use — it's independent per agent, order doesn't matter.
+
+Add `--dry-run` to see the plan without writing anything:
+
+```
+$ trellis migrate --from codex --dry-run
+```
+
+**What each action means:**
+
+| Action | Meaning |
+|---|---|
+| `create` | New to canonical source — copied in. |
+| `already-migrated` | Canonical already has byte-identical content (safe re-run, nothing happens). |
+| `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. |
+
+Migrate never overwrites a genuine conflict, and never scopes a migrated
+skill to just the source agent — once in canonical, it's visible to every
+agent by default (see `sync`, below). If migrate reports a `conflict`, open
+the two files it names and decide by hand which content should actually be
+canonical, then re-run.
+
+## Starting from nothing
+
+Skip migrate. Edit `~/.trellis/agents.md` and add skills under
+`~/.trellis/skills/<name>/SKILL.md` directly. There's nothing else to set up
+before moving on to `sync`.
+
+## `trellis sync`
+
+Distributes canonical skills and instructions to every agent present on this
+machine:
+
+```
+$ trellis sync
+```
+
+```
+✅ claude-code — 2 created, 0 removed, 0 conflict(s)
+✅ pi — 2 created, 0 removed, 0 conflict(s)
+⚠️  codex — 1 created, 0 removed, 1 conflict(s)
+   - [conflict] /Users/you/.agents/skills/my-skill exists and is not a Trellis-managed symlink — left untouched
+```
+
+Distribution is done with symlinks (skills, subagents) or a symlinked
+instructions file — never a copy, so canonical source stays the one place
+you edit. A `conflict` here means that agent already has its own real,
+non-symlinked content at that exact path; sync leaves it alone rather than
+guessing which one should win. If you meant to bring that content into
+canonical, that's what `migrate` is for.
+
+Run `trellis sync skills` or `trellis sync instructions` to distribute just
+one half. Add `--dry-run` (in any position — `trellis sync --dry-run` and
+`trellis sync skills --dry-run` both work) to preview the plan with zero
+writes.
+
+## `trellis mcp sync`
+
+Distributes `~/.trellis/mcp/servers.yaml` to every present agent's native
+MCP config. See [`schema/servers.example.yaml`](../schema/servers.example.yaml)
+for the full documented shape — server definitions, per-agent scoping,
+known-host-injected collision avoidance, and hub 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.
+
+`env:` in `servers.yaml` lists variable **names** only, never literal
+values — the real values come from wherever your shell/secret manager
+already populates them. See
+[`schema/secrets.policy.example.yaml`](../schema/secrets.policy.example.yaml)
+for exactly how that resolution works for each agent, including the one
+narrow exception (pi's bridge has to read a value into its own process).
+
+## `trellis secrets audit`
+
+```
+$ trellis secrets audit
+```
+
+Scans every present agent's **real, on-disk** config (never canonical) for:
+
+1. A literal value matching one of `secrets.policy.yaml`'s
+   `reject_patterns` (a credential-shaped string that should have been a
+   `${VAR}` reference instead).
+2. An environment variable **name** not in `allowed_vars` — this catches
+   the case a value-only scan can't: a secret stored under the wrong
+   variable name is still a well-formed reference, just an unexpected one.
+
+Fails non-zero on any hit. Run it after any MCP config change, and
+periodically regardless.
+
+## `trellis doctor`
+
+```
+$ trellis doctor
+```
+
+Read-only. Scans all four 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.
+
+`--probe-mcp` is opt-in because it spawns a real process per configured
+stdio MCP server (some reaching real external services) — not something a
+"just check my config" command should do by default.
+
+## Troubleshooting
+
+- **A `conflict` I don't understand**: `migrate` and `sync` both name the
+  exact file path in their output. Open it — it's real content that
+  differs from what Trellis expected, and resolving it is a decision only
+  you can make (which version is actually right).
+- **An agent I use isn't showing up as present**: `trellis doctor` probes
+  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.