agent-trellis 0.4.0 → 0.6.0

package/dist/pi-bridge/index.d.ts

@@ -12,7 +12,12 @@
  * this bridge actually uses are declared here.
  */
 import type { TSchema } from "typebox";
+import { withTimeout } from "../lib/mcpConnect.js";
 import { toPiContent } from "./schemaTranslate.js";
+/** Re-exported so `trellis-mcp-connect-timeout`'s existing test keeps
+ * importing it from the module it was written against — proving the
+ * extraction changed nothing it could observe. */
+export { withTimeout };
 interface PiToolResult {
     content: ReturnType<typeof toPiContent>;
     details: unknown;
@@ -28,14 +33,6 @@ interface PiExtensionAPI {
     registerTool(tool: PiToolDefinition): void;
     on?(event: "session_shutdown", handler: () => Promise<void> | void): void;
 }
-/**
- * A hanging server (process alive, protocol response never sent) leaves
- * `promise` permanently unsettled — indistinguishable from "still
- * starting up" without a bound. Racing against a timeout converts that
- * into an ordinary rejection, which every caller here already knows how
- * to isolate (design.md D1, trellis-mcp-connect-timeout).
- */
-export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, message: string): Promise<T>;
 /**
  * `homeDir`/`connectTimeoutMs` default to the real `~` / 10s — only
  * overridable for tests, same seam every other Trellis entry point
@@ -45,4 +42,3 @@ export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, m
  * `factory(pi)` — what pi actually does — works unchanged).
  */
 export default function trellisMcpBridge(pi: PiExtensionAPI, homeDir?: string, connectTimeoutMs?: number): Promise<void>;
-export {};

package/dist/pi-bridge/index.js

@@ -11,102 +11,17 @@
  * from Trellis's own install tree). Only the handful of fields/methods
  * this bridge actually uses are declared here.
  */
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StdioClientTransport, getDefaultEnvironment } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { homedir } from "node:os";
 import { loadCanonicalSource } from "../core/canonical.js";
 import { resolveMcpPlan } from "../adapters/mcpPlan.js";
-import { resolveSecretEnv } from "../lib/secretEnv.js";
-import { extractTemplateVarNames } from "../lib/envVarNames.js";
+import { connectServer, withTimeout, DEFAULT_CONNECT_TIMEOUT_MS } from "../lib/mcpConnect.js";
 import { ALL_AGENTS } from "../core/types.js";
 import { bridgedToolName, toParametersSchema, toPiContent } from "./schemaTranslate.js";
+/** Re-exported so `trellis-mcp-connect-timeout`'s existing test keeps
+ * importing it from the module it was written against — proving the
+ * extraction changed nothing it could observe. */
+export { withTimeout };
 const CLIENT_INFO = { name: "trellis-mcp-bridge", version: "0.0.0" };
-const DEFAULT_CONNECT_TIMEOUT_MS = 10_000;
-/**
- * A hanging server (process alive, protocol response never sent) leaves
- * `promise` permanently unsettled — indistinguishable from "still
- * starting up" without a bound. Racing against a timeout converts that
- * into an ordinary rejection, which every caller here already knows how
- * to isolate (design.md D1, trellis-mcp-connect-timeout).
- */
-export function withTimeout(promise, timeoutMs, message) {
-    return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(new Error(message)), timeoutMs);
-        promise.then((value) => {
-            clearTimeout(timer);
-            resolve(value);
-        }, (err) => {
-            clearTimeout(timer);
-            reject(err);
-        });
-    });
-}
-/**
- * A timed-out (or otherwise failed) connect attempt must not leak the
- * transport's own resources — for `StdioClientTransport` specifically,
- * an unclosed transport means an orphaned child process that outlives
- * this failed attempt indefinitely (confirmed by a real leaked
- * subprocess during this change's own test run). `transport.close()` is
- * best-effort: a transport that never fully connected may itself error
- * on close, but the original connect failure is what the caller needs
- * to see, not a secondary cleanup error.
- */
-async function connectWithCleanup(client, transport, timeoutMs, message) {
-    try {
-        await withTimeout(client.connect(transport), timeoutMs, message);
-        return client;
-    }
-    catch (err) {
-        try {
-            await transport.close();
-        }
-        catch {
-            // best-effort; the original connect failure is what matters
-        }
-        throw err;
-    }
-}
-async function connectStdio(def, secretsPolicy, timeoutMs) {
-    const client = new Client(CLIENT_INFO, { capabilities: {} });
-    const resolved = resolveSecretEnv(def.env ?? [], secretsPolicy);
-    const namedEnv = Object.fromEntries((def.env ?? []).map((name) => [name, resolved[name] ?? ""]));
-    const transport = new StdioClientTransport({
-        command: def.command,
-        args: def.args,
-        // staticEnv merges last: a literal, intentionally-plain value (an
-        // email, an environment tag) always wins over an unresolved name-only
-        // entry's empty-string fallback for the same key — though in practice
-        // resolveMcpPlan's D6 refusal never lets an unresolved name reach
-        // this point at all (trellis-mcp-static-env-and-disabled-servers).
-        env: { ...getDefaultEnvironment(), ...namedEnv, ...(def.staticEnv ?? {}) },
-    });
-    return connectWithCleanup(client, transport, timeoutMs, `connect timed out after ${timeoutMs}ms`);
-}
-function resolveHeaders(def, secretsPolicy) {
-    if (!def.headers || Object.keys(def.headers).length === 0)
-        return undefined;
-    const names = Object.keys(def.headers).flatMap((key) => extractTemplateVarNames(def.headers[key]));
-    const resolved = resolveSecretEnv(names, secretsPolicy);
-    const result = {};
-    for (const [key, template] of Object.entries(def.headers)) {
-        result[key] = template.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match, name) => resolved[name] ?? "");
-    }
-    return result;
-}
-async function connectHttp(def, secretsPolicy, timeoutMs) {
-    const client = new Client(CLIENT_INFO, { capabilities: {} });
-    const headers = resolveHeaders(def, secretsPolicy);
-    const opts = headers ? { requestInit: { headers } } : undefined;
-    return connectWithCleanup(client, new StreamableHTTPClientTransport(new URL(def.url), opts), timeoutMs, `connect timed out after ${timeoutMs}ms`);
-}
-async function connectSse(def, secretsPolicy, timeoutMs) {
-    const client = new Client(CLIENT_INFO, { capabilities: {} });
-    const headers = resolveHeaders(def, secretsPolicy);
-    const opts = headers ? { requestInit: { headers } } : undefined;
-    return connectWithCleanup(client, new SSEClientTransport(new URL(def.url), opts), timeoutMs, `connect timed out after ${timeoutMs}ms`);
-}
 function registerServerTools(pi, serverName, client, timeoutMs) {
     return withTimeout(client.listTools(), timeoutMs, `listTools timed out after ${timeoutMs}ms`).then((result) => {
         for (const tool of result.tools) {
@@ -171,15 +86,7 @@ export default async function trellisMcpBridge(pi, homeDir = homedir(), connectT
     await Promise.all(desired.map(async ({ name, def }) => {
         let client;
         try {
-            if (def.transport === "http") {
-                client = await connectHttp(def, canonical.secretsPolicy, connectTimeoutMs);
-            }
-            else if (def.transport === "sse") {
-                client = await connectSse(def, canonical.secretsPolicy, connectTimeoutMs);
-            }
-            else {
-                client = await connectStdio(def, canonical.secretsPolicy, connectTimeoutMs);
-            }
+            client = await connectServer(def, canonical.secretsPolicy, connectTimeoutMs, CLIENT_INFO);
         }
         catch (err) {
             // One unreachable/misconfigured (including permanently hanging —

package/dist/pi-bridge/schemaTranslate.d.ts

@@ -51,5 +51,11 @@ export declare function toParametersSchema(inputSchema: unknown): TSchema;
  * (design.md D3). */
 export declare function toPiContent(items: McpContentItem[]): PiContent[];
 /** `${serverName}__${toolName}` — deterministic, collision-free across
- * servers sharing pi.registerTool()'s single flat namespace (design.md D5). */
-export declare function bridgedToolName(serverName: string, toolName: string): string;
+ * servers sharing pi.registerTool()'s single flat namespace (design.md D5).
+ *
+ * Now one implementation shared with the gateway's own aggregation rather
+ * than two identical ones: the naming convention is the contract between
+ * a prefixed name and the server it routes to, and two copies of it could
+ * drift into routing tools to the wrong upstream
+ * (trellis-mcp-gateway-hosting design.md D3). */
+export { prefixedToolName as bridgedToolName } from "../lib/mcpToolRegistry.js";

package/dist/pi-bridge/schemaTranslate.js

@@ -34,7 +34,11 @@ export function toPiContent(items) {
     });
 }
 /** `${serverName}__${toolName}` — deterministic, collision-free across
- * servers sharing pi.registerTool()'s single flat namespace (design.md D5). */
-export function bridgedToolName(serverName, toolName) {
-    return `${serverName}__${toolName}`;
-}
+ * servers sharing pi.registerTool()'s single flat namespace (design.md D5).
+ *
+ * Now one implementation shared with the gateway's own aggregation rather
+ * than two identical ones: the naming convention is the contract between
+ * a prefixed name and the server it routes to, and two copies of it could
+ * drift into routing tools to the wrong upstream
+ * (trellis-mcp-gateway-hosting design.md D3). */
+export { prefixedToolName as bridgedToolName } from "../lib/mcpToolRegistry.js";

package/docs/architecture.md

@@ -234,28 +234,97 @@ 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.
+token) was, for most of this project's life, deliberately not built:
+all three native-config agents already have their own working flow —
+Claude Code's `claude mcp add --client-id/--client-secret/--callback-port`,
+Codex's `codex mcp login`/`logout` pair, Kiro's `oauth`/`oauthScopes`
+fields — and pi, whose bridge is Trellis's own code, simply couldn't
+reach such a server at all.
+
+That changed with gateway mode (below), which made it unavoidable: in
+gateway mode the agent connects to Trellis, and Trellis connects to the
+remote server, so the agent's own OAuth flow is no longer on the path.
+Trellis now implements the client half itself — discovery (RFC 8414 /
+RFC 9728), dynamic client registration (RFC 7591), authorization code
+with PKCE S256 (RFC 7636), and the refresh grant — in `src/lib/oauth/`.
+
+Two rules shape it, both from the constraint that the gateway is spawned
+silently by an agent with no terminal attached:
+
+- **Only `trellis mcp auth <server>` ever opens a browser.** It is run by
+  a human, once. The gateway never initiates an interactive flow under
+  any circumstance; a server with no stored credential is skipped the
+  same way an unreachable one is.
+- **Refreshing is silent, and serialized by a lock.** A `refresh_token`
+  grant needs neither a browser nor a callback, so the gateway does it
+  at connect time. The lock (`~/.trellis/mcp/oauth/<name>.lock`) exists
+  because most authorization servers rotate the refresh token and
+  invalidate its predecessor — two concurrent refreshes would leave one
+  party holding a credential that is already dead.
+
+Tokens live one-file-per-server at `~/.trellis/mcp/oauth/<name>.json`,
+mode 0600, never in `servers.yaml` and never in the OS keychain (macOS's
+`security add-generic-password` fails with exit 152/154 in exactly the
+non-interactive, no-GUI-session context the gateway runs in — measured,
+not assumed).
+
+In direct mode nothing here applies: each agent keeps using its own
+native OAuth flow, exactly as before.
+
+## MCP gateway mode
+
+Gateway mode collapses an agent's MCP config to one entry, like hub mode
+— but what sits behind it is a local subprocess Trellis owns
+(`trellis mcp-gateway --agent <id>`), not a URL someone operates. Set
+`mcp.gateway.enabled` in `mcp/servers.yaml`; add `mcp.gateway.agents` to
+narrow it to specific agents, or omit it to cover every managed agent.
+`gateway` and `hub` are independent fields and may both be set — gateway
+wins for any agent it covers.
+
+**Lifecycle: there isn't one.** The agent spawns it like any other stdio
+MCP server and it exits when the session ends. No daemon, no
+start/stop/status command, nothing to monitor. Two things make that
+true rather than aspirational:
+
+- The gateway watches its own stdin for EOF and tears everything down.
+  The MCP SDK's `StdioServerTransport` binds only `'data'` and
+  `'error'`, so it never reports EOF, and POSIX re-parents orphans to
+  launchd rather than killing them — without explicit teardown every
+  session would leak a gateway plus its whole upstream set, forever.
+- Upstream failures are isolated. One server that is unreachable,
+  misconfigured, or permanently hanging is logged and skipped; every
+  other server's tools are still served.
+
+**What it does:** resolves the same in-scope server set direct mode
+would have written for that agent (same `resolveMcpPlan`, so per-server
+`agents:` scope, `enabled: false`, host-injected collisions,
+literal-secret refusals and unresolved `env` names all behave
+identically), connects each one, and exposes their tools as
+`<server>__<tool>`. Secrets resolve through `resolveSecretEnv` exactly as
+in direct mode — the gateway introduces no second path by which a value
+could reach disk.
+
+**What it changes for the agents:** Codex's single-`bearer_token_env_var`
+limitation stops applying, because Codex no longer receives any server's
+`headers` — the gateway holds them. Remote servers needing real OAuth
+become reachable from every agent, including pi, for the same reason.
+
+**The seam.** `src/commands/mcpGateway.ts` depends on a `GatewayBackend`
+interface and nothing below it — never a connection, transport, or
+server definition. Today the only implementation connects upstreams
+in-process, one gateway per agent session. The confirmed direction is a
+single shared service holding one connection set for all agents, with
+the per-session process becoming a thin client forwarding over a Unix
+socket, speaking MCP itself (so no second protocol to own). That is a
+substitution at one construction site: the entry written into each
+agent's config is identical either way, so converging later requires no
+re-sync and nothing the user notices.
 
 ## 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 resident MCP gateway daemon. Gateway mode above is a per-session
+  subprocess with no lifecycle; hub mode points at something you operate.
+  Neither is a service Trellis starts, supervises, or keeps running.
 - 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

package/docs/getting-started.md

@@ -17,8 +17,9 @@ $ trellis onboard
 
 Runs `init`, detects which of Claude Code/Codex/Kiro/pi are on this machine,
 then resolves two independent choices before running `migrate`, `sync`,
-`mcp sync`, `memory sync`, and `secrets audit` — the whole onboarding path,
-no follow-up commands to type by hand:
+`mcp sync`, `memory sync`, `secrets audit`, and a final health scan — the
+whole onboarding path, no follow-up commands to type by hand, and no need
+to run `trellis doctor` separately to know whether it actually worked.
 
 1. **Migration source** — read from, at most one, never written back to.
    "Real content" means skills, custom instructions, *or* real MCP servers
@@ -65,16 +66,72 @@ memory sync
 
 secrets audit
   ✅ no findings — every present agent's real config and every declared env var passed all checks
+
+health scan (trellis doctor)
+  ✅ no findings
+
+verdict
+✅ nothing needs attention — every stage completed cleanly and verified
+exit code: 0 — nothing blocked this run
 ```
 
 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.
 
+**The `verdict` block is always the last thing printed**, including on a
+run that had nothing wrong — the exit code and the last line on screen
+always agree, so a conflict earlier in the run can never be hidden behind
+a later stage's own unrelated success line. Every conflict from every
+stage is collected there, each with a concrete next action, not just a
+restatement of what went wrong:
+
+```
+verdict
+❌ 1 blocking issue(s):
+   - [sync/claude-code] ~/.claude/CLAUDE.md exists and is not a Trellis-managed symlink — left untouched
+     → back up ~/.claude/CLAUDE.md's real content if you need it, remove the file, then re-run sync
+exit code: 1 — at least one blocking issue above
+```
+
+**A real (non-`--dry-run`) run verifies its own writes**, immediately
+after making them — a dry-run re-plan of `sync`/`mcp sync` against exactly
+what was just written, checked for anything still outstanding. This is
+what actually answers "did this take effect," distinct from the health
+scan below it: `trellis doctor`'s own checks compare agents against each
+other and never read canonical, so they cannot prove a write held — only
+a re-plan against canonical can. If a write somehow didn't hold (a
+filesystem permission problem, a race), it surfaces in the verdict as its
+own `blocked` item, separate from whatever the write's own stage reported.
+
+**The health scan is `trellis doctor` itself**, run at the end against
+every agent (not just the ones this run manages) — so a genuinely new
+problem this run happened to create or reveal shows up without a separate
+`trellis doctor` invocation. It never spawns a configured MCP server to
+check it (`--probe-mcp` is never passed): the worst possible moment to
+start reaching real external services with real credentials is a user's
+first-ever run of this command. A finding about an agent this run doesn't
+manage is shown, labelled as such, and doesn't fail the run — onboard
+didn't touch that agent, so its drift isn't this run's problem to fix.
+
+On a real terminal, each stage prints a `[n/6] <stage>` progress line to
+stderr as it starts — `sync`/`mcp sync` spawn real processes and can take
+a few seconds, and this keeps the screen from going silent while that
+happens. It never appears on stdout, so `trellis onboard > report.txt`
+still captures exactly the report and verdict, nothing else; it's silent
+entirely under `--json` or when stdout isn't a real terminal.
+
 Add `--dry-run` to preview the entire chain — init/migrate/sync/mcp
 sync/memory 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).
+`~/.trellis/managed.yaml` — with zero writes anywhere (secrets audit and
+the health scan are always read-only, with or without the flag; the
+write-verification step above has nothing to check on a dry run and is
+skipped entirely). On a real terminal, a `--dry-run` ends by offering to
+apply the plan you just read — "No" is the highlighted default, so Enter
+declines; accepting re-plans against current state and applies for real,
+rather than replaying the exact preview you saw (state may have changed
+while you were reading it). `--json` and non-interactive runs are never
+offered anything.
 
 **A managed agent's own real content still isn't overwritten.** If you
 explicitly include the source in `--manage`, sync still never overwrites
@@ -315,7 +372,8 @@ below.
 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.
+known-host-injected collision avoidance, hub mode, and gateway mode
+(below).
 
 ```
 $ trellis mcp sync
@@ -354,6 +412,76 @@ 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.
 
+If a server's own env var name differs from the one it should resolve
+(a real example: Notion's MCP server wants `OPENAPI_MCP_HEADERS`, but
+your shell/secret manager holds it under `NOTION_OPENAPI_MCP_HEADERS`),
+use `env_aliases` instead of either `env` or `static_env` —
+`target_key: source_variable_name`. It resolves through the exact same
+mechanism as `env` (the same pre-write refusal check, the same agent
+`${VAR}` reference on every target), just delivered under a different
+key. Writing that kind of reference as `static_env` looks like it works
+(the placeholder text is still just a string) but ships the literal,
+unexpanded `${SOURCE_NAME}` text to any agent with no `${VAR}` runtime
+of its own — which is exactly what broke pi's Notion connection before
+this field existed.
+
+## Gateway mode — one entry per agent instead of N
+
+Add this to `servers.yaml` and every managed agent's config collapses to
+a single MCP entry:
+
+```yaml
+gateway:
+  enabled: true
+```
+
+Then re-run `trellis mcp sync`. Instead of one native entry per server,
+each agent gets one stdio entry pointing at `trellis mcp-gateway`. The
+agent spawns it like any other stdio MCP server; it connects out to your
+servers, and exits when the session ends. There is nothing to start,
+stop, or monitor.
+
+Your servers' tools appear to the agent as `<server>__<tool>` — the
+`gitlab` server's `search` becomes `gitlab__search`.
+
+Add `agents: [claude-code, codex]` under `gateway:` to narrow it, leaving
+the rest in direct mode. Gateway mode and `hub` are independent; both can
+be set, and gateway wins for any agent it covers.
+
+Two things stop being problems in gateway mode. Codex can normally only
+express a single `Authorization: Bearer ${VAR}` header, so a server
+needing more than one was refused for Codex — in gateway mode Codex never
+sees any server's headers, so it just works. And remote servers requiring
+real OAuth become reachable from every agent, including pi.
+
+### `trellis mcp auth <server-name>`
+
+For a remote (`http`/`sse`) server that uses OAuth, authorize it once:
+
+```
+$ trellis mcp auth notion-remote
+✅ notion-remote — authorized (expires 2026-09-16T11:24:03.000Z)
+   credentials: ~/.trellis/mcp/oauth/notion-remote.json
+```
+
+This opens your browser, completes the flow, and stores the result 0600
+under `~/.trellis/mcp/oauth/` — never in `servers.yaml`, so canonical
+stays safe to read, diff, and commit.
+
+Run it once per server. After that the gateway refreshes the token
+silently whenever it expires; it never opens a browser and never prompts,
+because it is spawned by an agent with no terminal attached. Re-running
+this command when the stored token is still valid does nothing (`--force`
+overrides); when it has expired but is renewable, it refreshes without a
+browser.
+
+If a server has no stored credential, the gateway skips that one server
+and keeps serving every other — it does not fail to start.
+
+This command only applies to `http`/`sse` servers. stdio servers get
+their credentials from `env`/`env_aliases` as described above; running
+`mcp auth` on one tells you so rather than opening a pointless browser.
+
 ## `trellis memory sync`
 
 Ingests `~/.trellis/memories/*.md` into the actual on-disk file
@@ -378,12 +506,47 @@ 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.
+This only ingests canonical's *own* `memories/*.md` files into the shared
+store — the reverse direction (an agent's own already-accumulated content
+in that same shared graph, not yet represented in canonical) is
+`trellis memory extract`, below.
+
+## `trellis memory extract`
+
+The other direction: reads the same graph file's real entities — not
+Trellis's own (anything an agent created directly, via its own MCP tool
+calls against the shared memory server, before or outside of canonical) —
+and writes each as a new canonical `memories/*.md` file. Requires the
+same `memory` server configuration `memory sync` does; refuses with the
+identical message when it's missing.
+
+```
+$ trellis memory extract
+memory extract — /Users/you/.trellis/memories/graph.jsonl
+  [create] "Sprint Tasks Q2" (sprint-tasks-q2.md) — will create a new canonical memory file
+```
+
+A rendered file is a readable markdown transcription — heading,
+observations as a list, relations as a short list when the entity has
+any — not a format meant to round-trip byte-for-byte back through
+`memory sync`: re-syncing an extracted file later turns it into a single,
+flat observation, the same as any other canonical memory file. This is a
+one-way trip from "richer, live graph" to "durable, reviewable,
+version-controllable prose," not a lossless mirror.
+
+Same conflict discipline as everywhere else: a target file that already
+exists with different content is reported as a conflict and left
+untouched, never silently overwritten — including when two different
+entities' names would slug to the same filename. Not wired into
+`trellis onboard`'s automatic chain (unlike `memory sync`) — this is a
+deliberate, occasional action you run, the same posture `migrate` already
+has.
+
+**Note:** this is unrelated to any project-level "auto memory" feature an
+agent may have of its own (e.g. Claude Code's own per-project memory
+files) — those are a different, agent-specific mechanism entirely, not
+the shared `@modelcontextprotocol/server-memory` server Trellis manages
+here.
 
 ## `trellis secrets audit`