agent-trellis 0.1.0

package/docs/implementation-plan.md

@@ -0,0 +1,341 @@
+# Implementation plan
+
+Breaks `docs/roadmap.md`'s phases into concrete tasks. P0–P2 are specified at
+file/function level since they're next. P3–P4 are specified at
+module/decision level. P5–P7 stay at the roadmap's level of detail — planning
+them further now would be speculative, since their shape depends on what P0–P4
+actually reveal.
+
+Every task below ends in something that can fail. If a task can't fail, it
+isn't specified enough yet.
+
+---
+
+## P0 — `trellis doctor` (read-only scan, no canonical source required)
+
+> **Superseded by `openspec/changes/trellis-doctor-p0/`.** The section below
+> is kept as a historical note only — the authoritative proposal, design,
+> specs, and tasks for P0 live there now. Don't edit this section further.
+
+**Key simplification**: P0 does not require `.trellis/` to exist. It
+cross-compares the four agents' *own current state* against each other and
+flags drift/duplication directly — this is the exact manual process used
+throughout `docs/research.md`'s investigation (symlink-vs-realpath checks,
+MCP handshake probes, hash comparisons), now formalized into code instead of
+one-off shell commands.
+
+### 0.1 Shared probing library — `src/lib/`
+
+- `src/lib/mcpProbe.ts`
+  - `probeMcpServer(def: McpServerDef, env: NodeJS.ProcessEnv, timeoutMs = 10_000): Promise<McpProbeResult>`
+  - Spawns the server, sends a JSON-RPC `initialize`, resolves on the first
+    `id:1` response or process exit, whichever comes first. This is a direct
+    port of the probe script used repeatedly by hand in this project's
+    research — it needs to become a tested module, not stay a throwaway
+    `/tmp/mcp-probe.mjs`.
+  - Fails the task if: a known-good server (e.g. `@modelcontextprotocol/server-memory`)
+    does not return `serverInfo` within the timeout in CI.
+
+- `src/lib/fsIdentity.ts`
+  - `isSymlinkTo(path: string, target: string): boolean`
+  - `realpathDedupe(paths: string[]): Map<string /* realpath */, string[] /* original paths pointing there */>`
+  - This directly encodes the Codex finding from `docs/research.md`: dedup
+    must happen on realpath, not on path string or content hash alone
+    (two physical copies with identical content are *not* the same thing to
+    an agent's discovery logic — they show up as two entries).
+  - Fails the task if: given two physical copies of the same skill directory
+    (not symlinks), it correctly reports them as **not** deduplicated —
+    inverse of what `isSymlinkTo` would report for an actual symlink pair.
+
+- `src/lib/skillFile.ts`
+  - `findSkillFile(dir: string): { path: string; caseCorrect: boolean } | null`
+  - Case-sensitivity check is explicit and reported, not silently corrected —
+    this is the exact bug (`skill.md` vs `SKILL.md`) found and fixed by hand
+    in this project's own history.
+
+### 0.2 Per-agent probes — `src/probes/`
+
+Each file implements `probe(): Promise<AgentSnapshot>` where
+`AgentSnapshot` is a new type (add to `src/core/types.ts`):
+
+```ts
+interface AgentSnapshot {
+  agent: "claude-code" | "codex" | "kiro" | "pi";
+  present: boolean;
+  version?: string;
+  skillRoots: { path: string; isSymlink: boolean; target?: string; skillCount: number }[];
+  mcpServers: { name: string; source: "static-config" | "runtime-injected"; probe?: McpProbeResult }[];
+  instructionsFile?: { path: string; isSymlink: boolean; target?: string };
+  subagentsDir?: { path: string; isSymlink: boolean; count: number };
+}
+```
+
+- `src/probes/claude-code.ts` — reads `~/.claude.json` (`mcpServers` key),
+  `~/.claude/skills`, `~/.claude/agents`, `~/.claude/CLAUDE.md`. Best-understood
+  agent; build this one first to validate the `AgentSnapshot` shape before
+  committing to it for the other three.
+
+- `src/probes/codex.ts` — shells out to `codex mcp list` rather than
+  hand-parsing `config.toml` (TOML section patching in P2 will need real
+  parsing, but P0 is read-only and `codex` already exposes this). Skill root
+  is `~/.agents/skills` per Codex's own convention (confirmed in
+  `docs/research.md`) — the probe should also check whether `~/.codex/skills`
+  independently contains any *non-symlink* skill directories, since that's
+  exactly the duplication bug already found and fixed once in this
+  environment and is exactly the kind of regression `doctor` exists to catch.
+
+- `src/probes/kiro.ts` — same shape as Claude Code:
+  `~/.kiro/settings/mcp.json`, `~/.kiro/skills`, `~/.kiro/steering/CLAUDE.md`.
+
+- `src/probes/pi.ts` — **has an open unknown, resolve it first**: pi's skill
+  discovery path was never pinned down by direct observation in this
+  project's research (only confirmed pi *reads* `SKILL.md`-format files and
+  `AGENTS.md`/`CLAUDE.md`; the actual discovery directory wasn't isolated
+  from the minified bundle). Before writing this probe:
+  1. Run `pi --skill <path>` against a known skill dir and confirm it loads
+     (`pi -p "what skills do you have"` or similar, non-interactively).
+  2. Check `pi config` (interactive TUI) for any skill-path setting, and
+     check `~/.pi/agent/settings.json` again after that interaction — the
+     settings file only had four keys when checked during research; a skill
+     path may be set here that wasn't visible before because nothing had
+     configured one yet.
+  3. If no fixed discovery directory exists (i.e. skills are strictly
+     `--skill`-flag-only, per-invocation), document that as a real
+     constraint — the pi adapter in P4 would then need to inject the flag
+     via a wrapper rather than write to a filesystem location, which changes
+     P4's design meaningfully. **This determination gates P4's design, not
+     just P0's probe — do it early.**
+
+### 0.3 Command — `src/commands/doctor.ts`
+
+- `runDoctor(opts: { json?: boolean }): Promise<{ exitCode: number }>`
+- Calls all four probes in parallel (`Promise.allSettled` — one agent being
+  absent or erroring must not blank out the other three's results).
+- Cross-compares snapshots pairwise for:
+  - Same skill name present with different realpaths across agents (drift)
+  - Any skill root containing a non-symlinked physical copy where a symlink
+    pattern is otherwise established for that agent (duplication risk)
+  - MCP server names present in one agent's static config that also appear
+    in `known_host_injected` for another — surfaces the exact class of bug
+    documented in `docs/research.md` (Codex + mirasim same-name collision)
+    *before* it causes a startup failure, not after.
+- Human-readable output matches the table style already used throughout this
+  project's manual investigations (✅/⚠️/❌ per row) — this isn't cosmetic,
+  it's continuity with how these findings were actually communicated and
+  understood during research.
+- `--json` emits `AgentSnapshot[]` for P5's SDK and any future GUI to
+  consume without re-parsing terminal output.
+- Exit code is non-zero if any ⚠️/❌ finding exists. `doctor` is meant to be
+  runnable in CI/pre-commit, not just read by a human.
+
+### P0 acceptance
+
+Run against *this* machine (which has known, already-diagnosed issues
+documented in `docs/research.md`) and confirm `doctor` independently
+rediscovers at least these three already-known findings without being told
+where to look:
+1. The Codex `openspec-*` skill duplication (already fixed — confirm it now
+   reports clean).
+2. Any current MCP server name collision against `known_host_injected`.
+3. Any skill file with incorrect case (currently none — confirm it reports
+   clean, and separately unit-test the detector against a synthetic
+   `skill.md`).
+
+If `doctor` can't independently reproduce findings that were previously only
+found by hand, it isn't done — restating `docs/research.md`'s conclusions as
+hardcoded checks doesn't count.
+
+---
+
+## P1 — `trellis sync skills` / `trellis sync instructions`
+
+> **Done and archived** (`openspec/changes/archive/2026-09-12-trellis-sync-p1/`).
+> Section kept as a historical note only — see `docs/roadmap.md` for the
+> actual outcome and the two real bugs the acceptance pass caught. Don't
+> edit this section further.
+
+Depends on P0's `AgentSnapshot` to decide *what* needs syncing; this phase
+adds the *write* path.
+
+- `.trellis/` canonical source becomes real for the first time here — not
+  before. `src/core/canonical.ts`: `loadCanonicalSource(): CanonicalSource`
+  reads `~/.trellis/skills/*/SKILL.md`, `~/.trellis/agents/*.md`,
+  `~/.trellis/agents.md`, `~/.trellis/scope.yaml`. **Global only** — see
+  `docs/architecture.md` "Global vs. workspace scope". No `root` parameter,
+  no workspace merge; don't build toward the `.agents Protocol` draft's
+  global+workspace precedence model until that's an explicit decision, not
+  a default carried over from the draft.
+- `src/adapters/claude-code.ts`, `src/adapters/codex.ts`, `src/adapters/kiro.ts`,
+  `src/adapters/pi.ts` each implement `TrellisAdapter` (`src/core/adapter.ts`)
+  for skills + instructions only — MCP is P2/P4, deliberately kept out of
+  this phase's scope. Pi's adapter is the same symlink shape as the other
+  three (`~/.pi/agent/skills`, `~/.pi/agent/AGENTS.md` — confirmed real,
+  persistent paths per design.md D5 in the archived P0 change; see
+  docs/architecture.md's corrected pi adapter notes) — P4 is only pi's MCP
+  bridge, not its skills/instructions, which need nothing more than what
+  every other agent here needs.
+  `plan()` filters skills/subagent profiles through `isInScope` before
+  producing any plan item — a skill scoped away from that adapter's `id`
+  must produce zero plan items for it, not a plan item that apply() later
+  skips. `apply()` handles three cases, not just creation:
+  - **create/repair**: no symlink, or a symlink pointing at the wrong
+    target — safe to (re)write.
+  - **remove**: an agent's skill directory has a Trellis-managed symlink
+    (its realpath resolves inside the canonical `skills/` root) whose
+    corresponding skill either no longer exists in canonical or was just
+    scoped away from this agent — this is the "delete" half of "add once,
+    remove once, reaches every agent," and it's easy to build only the
+    create path and quietly never finish this half.
+  - **refuse**: the path exists as a *real* directory, not a symlink at
+    all — this is not Trellis's to touch. Surface it as a conflict and
+    stop; never delete something that might be a user's own content just
+    because its name matches a skill Trellis also knows about.
+
+  The realpath check in the remove case is not optional: it's what makes
+  removal safe. Only ever delete a symlink Trellis can prove it created
+  (points inside the canonical source), never a same-named real directory.
+- `verify()` re-runs the relevant P0 probe and diffs against canonical —
+  this is why P0's probes are written as reusable functions, not
+  doctor-command-only logic.
+
+### P1 acceptance
+
+Point at a scratch `$HOME` (or a container) with none of the four agents'
+skill directories populated, run `trellis sync skills`, then run `trellis
+doctor` and confirm zero findings. Then manually corrupt one symlink
+(point it somewhere wrong) and confirm `doctor` catches it before re-running
+sync to confirm `apply()` repairs it idempotently. Separately: add one
+skill scoped to `[claude-code]` only in `scope.yaml`, run `trellis sync
+skills`, and confirm it appears only in Claude Code's skills directory —
+not Codex's, Kiro's, or pi's.
+
+---
+
+## P2 — `trellis mcp sync`
+
+> **Done and archived** (`openspec/changes/archive/2026-09-12-trellis-mcp-sync-p2/`).
+> Section kept as a historical note only — see `docs/roadmap.md` for the
+> actual outcome. Two corrections against this plan's own assumptions,
+> found before/while implementing: neither `@iarna/toml` nor `smol-toml`
+> survives a round-trip (both drop comments, reformat arrays) — Codex is
+> patched by a hand-rolled line-based section locator/splicer instead
+> (`src/lib/tomlSection.ts`), no library dependency at all; and automatic
+> MCP removal turned out to be unsafe without an ownership marker a bare
+> TOML/JSON key has no equivalent of (a symlink's realpath proves it for
+> skills) — deferred until a lock-file mechanism exists, `plan()` only
+> ever produces create/repair + conflict for MCP. Don't edit this section
+> further.
+
+The highest-risk phase — this is where `docs/research.md`'s hardest-won
+constraint applies directly: **Codex's adapter must patch a TOML section in
+place, never regenerate the whole file**, because Codex's own `config.toml`
+holds settings Trellis has no business touching (models, trust levels), and
+because mirasim writes to the same file independently.
+
+- `src/adapters/codex.ts` (extended): needs a real TOML parser that
+  preserves comments/formatting outside the touched section (`@iarna/toml`
+  or `smol-toml` — evaluate both for round-trip fidelity before picking one;
+  this is exactly the kind of "don't reinvent" call `docs/research.md`
+  already commits to). Patch strategy: locate `[mcp_servers.<name>]` by
+  section header, replace only that block, leave every byte outside it
+  untouched.
+- Collision check runs `known_host_injected` from `mcp/servers.yaml` against
+  every server name about to be written; refuses to write and exits non-zero
+  on collision, with the exact error class from `docs/research.md`
+  (`url is not supported for stdio`) quoted in the failure message so a user
+  hitting this via Trellis gets the real cause immediately instead of
+  rediscovering it as a mysterious Codex crash.
+- Every adapter's `plan()` filters servers through `isInScope` using each
+  server's inline `agents:` field (not `scope.yaml` — see
+  `docs/architecture.md` "Private / agent-specific capabilities" for why
+  MCP scoping is inline) before generating anything for that agent.
+- `src/adapters/claude-code.ts` / `kiro.ts` (extended): plain JSON deep-merge
+  under `mcpServers`, values always emitted as `${VAR}` — never a literal,
+  enforced by a check against `secrets.policy.yaml`'s `reject_patterns`
+  *before* the write happens, not just audited after (P3 audits adapter
+  *output*; this is a pre-write guard specific to the MCP adapter, cheaper
+  to catch here than after the fact).
+- **Hub mode branch** (`docs/architecture.md` "MCP hub mode"): every
+  adapter checks `canonical.mcp.hub` first. If set, skip the whole
+  N-server merge/patch logic above and instead ensure exactly one static
+  entry (name TBD, e.g. `trellis-hub`) pointing at `hub.url` exists —
+  Codex still patches in place, Claude/Kiro still JSON-merge, just one
+  entry instead of N. The collision check still runs, just against that
+  one name instead of every server name.
+
+### P2 acceptance
+
+Reproduce the exact Codex incident from `docs/research.md` in a sandboxed
+`config.toml` (a stdio server statically defined, then a same-name `url`
+server "injected" via `-c` the way mirasim does) and confirm Trellis's
+collision check refuses the write *before* attempting it, rather than
+letting Codex fail to start. Separately, with `hub.url` set in the fixture's
+`servers.yaml`, confirm each agent's generated config contains exactly one
+MCP entry regardless of how many servers are defined.
+
+---
+
+## P3 — `trellis secrets audit`
+
+> **Done and archived** (`openspec/changes/archive/2026-09-12-trellis-secrets-audit-p3/`).
+> Section kept as a historical note only — see `docs/roadmap.md` for the
+> actual outcome. Built as planned, with no dependency added: env-var-name
+> extraction turned out to need only real `JSON.parse` (Claude Code/Kiro)
+> and a five-line regex over one TOML line shape (Codex), not a general
+> parser or a reused write-path module. Don't edit this section further.
+
+- `src/commands/secretsAudit.ts`: reads every adapter's *actual output file*
+  (not the canonical source — the point is catching what actually landed on
+  disk) and runs `secrets.policy.yaml`'s `reject_patterns` against it.
+- Must catch, as regression tests, the two real incidents already on
+  record: a GitLab PAT stored under the wrong variable name (this is a
+  *naming* bug the pattern-match alone won't catch — audit also needs an
+  "unexpected variable name" check against `allowed_vars`, not just a
+  literal-value regex) and a literal token value embedded directly in a
+  generated config (the regex case).
+
+## P4 — pi MCP bridge extension
+
+> **Done and archived** (`openspec/changes/archive/2026-09-12-trellis-pi-mcp-bridge-p4/`).
+> Section kept as a historical note only — see `docs/roadmap.md` for the
+> actual outcome. Built largely as sketched (a symlinked extension, no
+> settings.json write, `registerTool` per MCP tool), but the delivered
+> file had to become a fully bundled, dependency-free build output
+> (`dist/pi-bridge/bundle.js` via `esbuild`) rather than raw TypeScript
+> source — a real sandbox run against the actual `pi` binary showed a
+> symlinked file's own imports resolve relative to the symlink's path,
+> not its target, so an unbundled file could never resolve its
+> dependencies once placed in a real user's home directory. Don't edit
+> this section further.
+
+**MCP only** — pi's skills/instructions adapter is P1's `src/adapters/pi.ts`
+(same symlink shape as every other agent, see P1 above); P4 is exclusively
+the MCP bridge, since pi has no native MCP client at all (docs/research.md).
+
+§0.2's investigation resolved during P0 (design.md D5 in the archived
+`trellis-doctor-p0` change): pi has a real discovery directory
+(`~/.pi/agent/skills`), settling which of the two candidate shapes below
+applies — the first one:
+
+- A pi extension package, installed once, that on startup reads
+  `.trellis/mcp/servers.yaml`. If `mcp.hub` is unset, it opens an
+  `@modelcontextprotocol/sdk` `StdioClientTransport` per server and calls
+  pi's `registerTool` for each tool the server reports; if `mcp.hub.url` is
+  set, it instead opens a single `StreamableHTTPClientTransport` to that
+  URL — one connection instead of N processes to keep alive, see
+  `docs/architecture.md` "MCP hub mode".
+
+This is the one adapter that is genuine runtime code, not a config
+generator — budget real testing time against a live pi session, not just
+unit tests of the bridging logic in isolation.
+
+---
+
+## Sequencing note
+
+Build order: **Claude Code → Codex → Kiro → pi**, in that order, for every
+phase through P4. Claude Code and Codex are already the best-understood
+(most of `docs/research.md`'s hard-won findings are about them); Kiro is
+structurally identical to Claude Code and should be fast once that shape is
+validated; pi is last because it has the one open unknown (§0.2) and the one
+genuinely novel engineering problem (§P4).

package/docs/research.md

@@ -0,0 +1,175 @@
+# Research: what already exists
+
+Surveyed 2026-09-11. This is why Trellis is a thin orchestration layer, not a
+from-scratch rebuild of anything below.
+
+## Rules / skills sync (crowded — don't rebuild)
+
+| Project | Covers | Kiro | pi | MCP | Memory | Secrets |
+|---|---|---|---|---|---|---|
+| [block/ai-rules](https://github.com/block/ai-rules) (Rust, Apache-2.0, Block/Square) | 11 agents (AMP, Claude Code, Cline, Codex, Copilot, Cursor, Firebender, Gemini, Goose, Kilocode, Roo) | ❌ | ❌ | config generation only | ❌ | ❌ |
+| [lbb00/ai-rules-sync](https://github.com/lbb00/ai-rules-sync) | Cursor/Claude/Copilot/OpenCode/Trae/Codex/Gemini/Warp | ❌ | ❌ | ❌ | ❌ | ❌ |
+| [shanliuling/skills-link](https://github.com/shanliuling/skills-link) | 41+ agents, pure symlink | unlisted | unlisted | ❌ | ❌ | ❌ |
+| [runkids/skillshare](https://github.com/runkids/skillshare), [qufei1993/skills-hub](https://github.com/qufei1993/skills-hub) | Codex/Claude/OpenClaw etc. | ❌ | ❌ | ❌ | ❌ | ❌ |
+| [PanisHandsome/ai-rules-sync](https://github.com/PanisHandsome/ai-rules-sync) | AGENTS.md/CLAUDE.md/.cursorrules/Copilot/Windsurf/Cline/Aider/Gemini | ❌ | ❌ | ❌ | ❌ | ❌ |
+| [yelmuratoff/agent_sync](https://github.com/yelmuratoff/agent_sync) | Claude/Cursor/Copilot/Gemini + 10 more | ❌ | ❌ | ❌ | ❌ | ❌ |
+
+**No existing tool covers Kiro or pi.** None combine rules+skills with MCP,
+memory, and secret hygiene as one system. That's the actual gap.
+
+## The `.agents Protocol` draft
+
+[dotagentsprotocol.com](https://dotagentsprotocol.com) (status: DRAFT,
+2026-02-24, community-maintained, no vendor backing yet) proposes exactly the
+directory shape this problem needs:
+
+```
+.agents/
+├── agents.md            # instructions (compatible with the AGENTS.md standard)
+├── mcp.json              # MCP servers
+├── skills/*/skill.md     # skill definitions
+├── agents/*/agent.md     # subagent profiles
+├── tasks/*/task.md       # recurring tasks
+└── memories/*.md         # persistent memory entries
+```
+
+It explicitly has **no reference implementation** yet. Trellis targets
+alignment with this draft rather than inventing a competing schema — being
+the first working implementation is more leverage than being a sixth
+standard. See [`schema/`](../schema) for where Trellis's schema matches the
+draft and where it deliberately extends it (Kiro/pi adapters, secret
+references, MCP env passthrough semantics — none of which the draft
+specifies).
+
+## MCP aggregation (reuse, don't rebuild)
+
+| Project | Stars | Model | Notes |
+|---|---|---|---|
+| [MetaMCP](https://github.com/metatool-ai/metamcp) | 2.6k, MIT | Docker + Postgres, namespaces, OAuth | Heaviest, most complete; remote-only endpoints need a local stdio bridge for desktop clients |
+| [mcp-hub](https://github.com/ravitemer/mcp-hub) | 516★, 227 commits, MIT | Plain Node process, no Docker, single HTTP endpoint (`/mcp`), JSON config with `command`/`args`/`env` (stdio) or `url`/`headers` (remote) — matches Trellis's own `servers.yaml` fields almost 1:1 | Dynamic add/remove without client restart — SSE-pushes `servers_updated`/`tool_list_changed` to already-connected agents |
+| [mcp-router](https://github.com/mcp-router/mcp-router) | — | Desktop app + CLI, Sustainable Use License | Already deployed in this environment; token-based, has a GUI. **First-hand incident**: its `MCPR_TOKEN` existed in three different values across `secrets.env`/`config.toml`/`kiro/mcp.json` simultaneously, one silently invalid — see below |
+
+Decision: Trellis still does not implement aggregation/routing logic
+itself. It generates native MCP config for each agent directly — that's
+what actually needed solving, since none of the above touch Kiro/pi/Codex's
+TOML format. But it now natively *supports* routing every agent through a
+single external endpoint instead of N direct definitions ("hub mode," see
+`docs/architecture.md`) — not a product integration, just an optional
+`hub.url` field every adapter checks. What runs behind that URL (mcp-hub,
+mcp-router, anything else) is the user's choice, not Trellis's; the type
+(`HubConfig`) deliberately has no engine/product field to keep in sync.
+
+The mcp-router incident above is the concrete argument for preferring a
+self-hosted hub whose config Trellis generates from the same
+`servers.yaml` over one managed through an external dashboard: the latter
+becomes a second place "what servers exist" is defined, outside `.trellis/`
+entirely, and this project hit real drift from exactly that shape of setup
+before hub mode existed as a documented option.
+
+## Shared memory (reuse)
+
+Checked directly against this real machine before writing this section,
+rather than trusting an earlier draft's claim at face value — the result
+is more nuanced than either "confirmed" or "wrong":
+
+- `src/commands/doctor.ts`'s `DEFAULT_KNOWN_HOST_INJECTED` already lists
+  `"memory"`, documented there as "mirasim's actual known connectors on
+  this project's own machine" (P0's own empirical finding, not a guess).
+  Runtime-injected connectors are, by design, invisible in any agent's
+  *static* config — that's the entire reason `known_host_injected` exists
+  as a concept distinct from what a config file shows. So this likely
+  *is* real: mirasim probably does inject a `server-memory`-class
+  connector named `memory` at runtime for every session on this machine,
+  and no amount of reading `.claude.json`/`config.toml`/`mcp.json` could
+  confirm or deny that either way.
+- What static config *does* show, independent of whatever mirasim
+  injects: Kiro alone has an *additional* memory server explicitly
+  configured — [`totalrecallai`](https://github.com/Auriti-Labs/kiro-memory)
+  (npm `totalrecallai`) — SQLite-backed (`better-sqlite3`) with a local
+  embedding model for semantic/vector search (`fastembed` + `onnxruntime`),
+  a bundled React web viewer, AGPL-3.0 licensed, its own repo literally
+  named `kiro-memory` (purpose-built for Kiro, later marketed as
+  MCP-client-agnostic). Claude Code and Codex have no additional static
+  memory server at all. Whatever mirasim injects at runtime is presumably
+  uniform across all three; this static difference is real, additional,
+  and Kiro-specific — the single-source fragmentation problem Trellis
+  exists to solve, found in the wild rather than assumed on paper.
+
+The official reference server
+[`@modelcontextprotocol/server-memory`](https://github.com/modelcontextprotocol/servers/tree/main/src/memory)
+is zero-dependency, local JSON knowledge graph, MIT-licensed, maintained
+as part of the official `modelcontextprotocol/servers` repo. Trellis
+documents this as the default (`schema/servers.example.yaml`'s `memory`
+entry) — the safe, unopinionated choice for a default any `.trellis/`
+setup can adopt without pulling in native bindings or a copyleft license
+obligation. It's very likely already what a mirasim-hosted session gets
+via runtime injection (see `known_host_injected` above) — on a host like
+that, declaring it again in `mcp/servers.yaml` collides with the
+already-injected connector, exactly the class of incident
+`known_host_injected` exists to refuse (see the schema example's own
+comment for how to tell which situation applies). On a host with no such
+injection, declaring it is what actually wires the default. Either way,
+`totalrecallai`'s semantic-search/SQLite/viewer feature set belongs in
+the same *opt-in upgrade* category as mem0/OpenMemory below, not silently
+adopted as the default just because it happened to already be configured
+on one agent, on one machine.
+
+[mem0 / OpenMemory MCP](https://github.com/mem0ai/mem0) — "private,
+local-first memory layer with a built-in UI, compatible with all MCP
+clients." Mature, but needs Docker + an LLM key. Documented as the
+upgrade path for cross-machine or richer semantic memory, alongside
+`totalrecallai` as a second real option in that same category.
+
+## Secrets (formalize existing practice, don't build new infra)
+
+The 2026 consensus across 1Password, Vault, Infisical writeups is uniform:
+**configs hold references, real values resolve only at process-spawn time,
+never persisted twice.** This is exactly what this environment was already
+doing by hand (`${VAR}` in Claude Code's `mcpServers`, `env_vars` passthrough
+in Codex's `config.toml`) before Trellis existed — confirmed working via two
+real incidents during development (a GitLab PAT stored under the wrong
+variable name, and three divergent values of the same router token, one of
+which was silently invalid). Trellis's contribution here is `trellis secrets
+audit` — a linter that fails a build if any adapter output contains a raw
+credential — not a new secret store.
+
+## pi coding agent — the one place we write real code, not config generation
+
+Reverse-engineered directly from the installed binary
+(`@earendil-works/pi-coding-agent`, confirmed via `strings` on
+`dist/bundle/chunks/*.js`, not from documentation):
+
+- pi **natively discovers** `AGENTS.override.md`, `AGENTS.md`, `CLAUDE.md`
+  (in that priority order) — instructions and `SKILL.md`-format skills need
+  no adapter work at all.
+- pi has **no native MCP client**. The only `mcpServers` string in its bundle
+  belongs to the Google Gen AI SDK's Vertex tool-schema translator, which
+  explicitly throws `"mcpServers parameter is not supported"` — unrelated to
+  MCP proper.
+- pi's capability surface is **extensions**: JS modules loaded via
+  `--extension`/discovery, with a real API (`createExtension`,
+  `registerTool`). Giving pi access to the same MCP servers every other agent
+  uses means writing a bridge extension that spins up
+  `@modelcontextprotocol/sdk` stdio clients from `mcp.json` and registers
+  their tools through this API. This is the one adapter in Trellis that is
+  genuine code, not config templating — see
+  [`src/adapters/pi/`](../src/adapters/pi).
+
+## Codex — three hard constraints learned by breaking them
+
+All three below came from real incidents, not upfront design, and any Codex
+adapter must respect them:
+
+1. **Skill discovery dedups by realpath, not by content.** Two physical
+   copies of an identical skill directory both get listed (duplicate tool
+   entries); a symlink to the same target is correctly merged into one. Never
+   copy a skill into `~/.codex/skills` — always symlink.
+2. **`SKILL.md` must match byte-for-byte**, including case. A file saved as
+   `skill.md` is silently dropped from discovery — no warning, no error.
+3. **Same-name MCP server across a static config and a `-c` runtime override
+   is not "last write wins" — it's a field-level merge.** If Codex's own
+   `config.toml` defines a server as stdio (`command`) and something injects
+   a `url` under the same name at runtime, the *entire* `codex` process fails
+   to start (`url is not supported for stdio`), not just that one server.
+   Trellis must never let a locally-defined server name collide with a name
+   a host environment (like mirasim) is known to inject.