agent-trellis 0.1.0 → 0.3.0

package/docs/getting-started.md

@@ -16,39 +16,62 @@ $ 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.
+then resolves two independent choices before running `migrate`, `sync`,
+`mcp sync`, and `secrets audit` — the whole onboarding path, no follow-up
+commands to type by hand:
+
+1. **Migration source** — read from, at most one, never written back to.
+   - **No agent has real content**: skipped — canonical starts from `init`'s
+     placeholder.
+   - **Exactly one agent has real content**: auto-selected, no prompt.
+   - **Two or more**: prompts you to choose (Up/Down or j/k, Enter to confirm,
+     on a real terminal that supports it — falls back to a numbered
+     type-a-digit prompt otherwise), or pass `--agent <id>` to skip the
+     prompt entirely.
+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).
+   **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.
 
 ```
-$ trellis onboard --agent claude-code
-Using claude-code as the migration base (--agent).
+$ trellis onboard --agent claude-code --manage pi
+Using claude-code as the migration source (--agent).
+Managed agents: pi
 
 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)
+  ✅ pi — 1 created, 0 removed, 0 conflict(s)
   ...
 
-Next: `trellis mcp sync` to distribute MCP servers, `trellis secrets audit` to check for leaked credentials.
+mcp sync
+  ✅ pi — already in sync
+
+secrets audit
+  ✅ no findings — every present agent's real config and every declared env var passed all checks
 ```
 
-Add `--dry-run` to preview the entire chain — init/migrate/sync — with zero
-writes anywhere.
+No agent named `claude-code` appears in the `sync`/`mcp sync` output above —
+it's present and was the migration source, but it isn't managed, so it's
+never even probed as a sync target, not just left with zero items.
 
-**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).
+Add `--dry-run` to preview the entire chain — init/migrate/sync/mcp
+sync, including what would be written to `~/.trellis/managed.yaml` — with
+zero writes anywhere (secrets audit is always read-only, with or without
+the flag).
+
+**A managed agent's own real content still isn't overwritten.** If you
+explicitly include the source in `--manage`, sync still never overwrites
+its real files — see the conflict table below. Merging differing content
+across multiple agents into one canonical 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
@@ -114,32 +137,140 @@ 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
+just one category — useful when you only want part of it brought in
+right now. Omit it to migrate all three, exactly as above:
+
+```
+$ trellis migrate --from codex --only instructions
+```
+
 **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). |
+| `already-migrated` | Canonical already has byte-identical (or, for MCP servers, structurally 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. |
+| `skip-unsupported` | MCP servers only — that agent's real definition can't be safely represented (see below); nothing was written for it. |
 
 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.
+skill (or MCP server) 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/entries it names and decide by hand
+which content should actually be canonical, then re-run.
+
+**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`:
+
+```
+$ trellis migrate --from claude-code --only mcp
+migrate --from claude-code
+  [create] mcp server "gitlab" — will add to servers.yaml
+```
+
+Two known fidelity limits, named rather than silently worked around:
+
+- **Codex remote servers migrate when they only use `url` and
+  `bearer_token_env_var`** — the one shape this codebase has verified
+  against a real `codex` binary, and the only shape Trellis's own writer
+  ever produces for Codex. Codex's own config schema has no way to tell
+  `http` apart from `sse`, so a migrated remote server always comes back
+  as `http` — not a guess, that distinction was never stored in the
+  first place. A server using Codex's other header mechanisms
+  (`http_headers`/`env_http_headers`/`http_headers_helper` — real fields
+  this project has no verified shape for) is reported `skip-unsupported`
+  rather than guessed at; use `trellis mcp add` for that one server as a
+  workaround.
+- **`headers` recovery depends on that agent's own real on-disk shape.**
+  claude-code/kiro read `headers` from the exact same JSON field Trellis
+  itself writes (`schema/servers.example.yaml`'s `figma` example) — if a
+  server was hand-authored with some other shape, it migrates whatever
+  is actually there, same as any other field.
 
 ## 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/skills/<name>/SKILL.md` directly, or use
+`trellis skill add` (below) instead of hand-editing. There's nothing else
+to set up before moving on to `sync`.
+
+The same applies to MCP servers — `~/.trellis/mcp/servers.yaml` can be
+hand-authored the same way (see
+[`schema/servers.example.yaml`](../schema/servers.example.yaml) for the
+full shape), or use `trellis mcp add` (below). Either way, move on to
+[`trellis mcp sync`](#trellis-mcp-sync) once you've added what you want.
+
+## `trellis skill` / `trellis mcp` — canonical CRUD via the CLI
+
+An alternative to hand-editing canonical files directly — useful for
+scripting, or when you'd rather not open a text editor for a one-line
+change. Both commands are canonical-side only: they never touch any
+agent's native config (that stays `sync`/`mcp sync`'s job).
+
+```
+$ trellis skill list
+my-skill — claude-code, codex, pi
+
+$ trellis skill add my-other-skill --from ./some/local/dir
+skill add my-other-skill
+  [create] will copy from ./some/local/dir
+
+$ trellis skill remove my-other-skill
+removed skill "my-other-skill" from canonical source.
+```
+
+`skill add` refuses (no write) if the name already exists with different
+content — same conflict posture as `migrate`, never silently overwritten.
+`skill remove` deletes the canonical directory; the *next* `trellis sync`
+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).
+
+```
+$ trellis mcp list
+tanka (http) — codex, pi
+  env: TANKA_TOKEN (values never read/printed)
+
+$ trellis mcp add local-server --transport stdio --command node --args server.js --env API_KEY
+mcp add local-server
+  [create] will add to servers.yaml
+
+$ trellis mcp remove local-server
+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
+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.
+
+`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
+`static_env` values are shown in full since those were never secrets in
+the first place (see `mcp sync`'s own explanation of `env` vs.
+`static_env`, further below).
+
+All four of `skill add`/`skill remove`/`mcp add`/`mcp remove` support
+`--dry-run` and `--json`, same convention as every other command.
 
 ## `trellis sync`
 
-Distributes canonical skills and instructions to every agent present on this
-machine:
+Distributes canonical skills and instructions to every **managed** agent
+(`~/.trellis/managed.yaml` — empty by default; `trellis onboard` writes it,
+or edit it yourself). A present-but-unmanaged agent gets no report line at
+all, not just zero items:
 
 ```
 $ trellis sync
@@ -162,12 +293,18 @@ 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.
+writes (and, per the same rule, records nothing to back up — see
+`trellis rollback` below).
+
+Every create/repair/remove this actually performs is recorded first,
+automatically, so `trellis rollback` can undo the whole run later — see
+[`trellis rollback`](#trellis-rollback--undoing-a-syncmcp-synconboard-run)
+below.
 
 ## `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)
+Distributes `~/.trellis/mcp/servers.yaml` to every **managed** agent's
+native MCP config — same restriction as `sync`, see above. 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.
 
@@ -180,6 +317,11 @@ 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.
 
+Every native-config file this rewrites in place is snapshotted first,
+automatically — see
+[`trellis rollback`](#trellis-rollback--undoing-a-syncmcp-synconboard-run)
+below to undo a run that turned out to be wrong.
+
 `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
@@ -187,13 +329,61 @@ already populates them. See
 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).
 
+Before writing any name-only `env` entry, `mcp sync` checks it actually
+resolves — a name with no value anywhere `secrets audit` would also
+check is refused as a conflict for that one server, not written and left
+to silently break that server once the agent tries to use it. Every
+other server, and every other agent, still syncs normally.
+
+For a value that isn't a secret at all — an email address, an
+environment tag — use `static_env` instead of `env`: written into the
+agent's config verbatim, never treated as a name to resolve (still
+scanned for an accidental real credential, same as every other literal
+field). `enabled: false` keeps a server's definition in canonical
+without writing it to any agent — for something you want configured but
+not currently active anywhere; remove the line (or set it `true`) to
+turn it back on everywhere at once. See
+[`schema/servers.example.yaml`](../schema/servers.example.yaml) for both.
+
+## `trellis memory sync`
+
+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
+memory server actually knows about them." Requires a `memory` server in
+`servers.yaml` with `static_env.MEMORY_FILE_PATH` set explicitly (see
+[`schema/servers.example.yaml`](../schema/servers.example.yaml)); without
+one, this is a no-op, not an error.
+
+```
+$ trellis memory sync
+memory sync — /Users/you/.trellis/memories/graph.jsonl
+  [create] "sprint-tasks" — will create a new entity
+```
+
+Every entry Trellis creates is tagged internally so a later sync can
+safely update or remove it; anything else already in that file — an
+entity or relation an agent added itself while actually using the memory
+server — is never touched. If a name collides with something already in
+the graph that Trellis didn't create, the command refuses that one entry
+(reported as a conflict) rather than overwriting it, same posture as
+every other conflict in this project.
+
+**Known limitation, named rather than silently worked around:** this only
+ingests canonical's *own* `memories/*.md` files into the shared store —
+it does not (yet) extract an agent's own already-accumulated memory
+content (e.g. Claude Code's own per-project memory feature) back into
+canonical. That extraction is a real, separate, still-open gap — see
+`docs/roadmap.md`'s P15 entry.
+
 ## `trellis secrets audit`
 
 ```
 $ trellis secrets audit
 ```
 
-Scans every present agent's **real, on-disk** config (never canonical) for:
+Scans every **managed** agent's **real, on-disk** config (never canonical)
+for — same restriction as `sync`, see above:
 
 1. A literal value matching one of `secrets.policy.yaml`'s
    `reject_patterns` (a credential-shaped string that should have been a
@@ -220,6 +410,50 @@ 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.
 
+## `trellis rollback` — undoing a `sync`/`mcp sync`/`onboard` run
+
+Every real write those three commands perform is recorded, before it
+happens, to a structured run directory under `~/.trellis/backups/` — no
+flag needed, this is always on for any run that actually writes
+something. `--dry-run` never creates one, since nothing was written.
+
+```
+$ trellis rollback
+```
+
+Omitting a run id targets the most recent run. Pass one explicitly to
+undo an older run — see `trellis rollback --list` for what's available:
+
+```
+$ trellis rollback --list
+2026-09-13T04-52-18-727Z-mcp-sync — mcp-sync, 3 operation(s), 2026-09-13T04:52:18.727Z
+2026-09-13T04-44-56-967Z-sync — sync, 1 operation(s), 2026-09-13T04:44:56.967Z
+```
+
+For each recorded operation, rollback checks whether that path's
+**current** state still matches what the run itself left behind:
+
+| Current state vs. recorded | Result |
+|---|---|
+| Unchanged since the run | `restore` — the file's exact prior bytes, or the symlink's exact prior target, or removed if the run created it |
+| Something else touched it since | `conflict` — reported, left untouched, never force-restored over |
+
+One path's `conflict` never blocks any other path in the same rollback
+from restoring. Exit code is non-zero if any `conflict` occurred. Add
+`--dry-run` to preview the restore/conflict plan with zero writes, or
+`--json` for machine-readable output.
+
+`onboard` shares one backup run across its whole chained `sync`/`mcp
+sync` stages — one `trellis rollback` undoes an entire `onboard`
+invocation, not just its last stage. `migrate` is not covered: it only
+ever creates a new canonical entry or refuses on conflict, never
+overwrites existing canonical content, so there's nothing a snapshot
+would add — undoing a migrate mistake is just deleting the newly
+created file under `~/.trellis/skills/`.
+
+`~/.trellis/backups/` has no automatic pruning — delete old run
+directories by hand once you're done with them.
+
 ## Troubleshooting
 
 - **A `conflict` I don't understand**: `migrate` and `sync` both name the