agent-trellis 0.9.1 → 0.11.0

package/dist/pi-bridge/bundle.js

@@ -15140,11 +15140,21 @@ import { homedir as homedir2 } from "node:os";
 
 // src/core/canonical.ts
 var import_yaml = __toESM(require_dist(), 1);
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, readdirSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
 
 // src/core/types.ts
+function isOAuthAuth(auth2) {
+  return auth2 === "oauth" || typeof auth2 === "object" && auth2 !== null && auth2.kind === "oauth";
+}
+function oauthClientMetadata(auth2) {
+  if (typeof auth2 !== "object" || auth2 === null) return {};
+  const meta2 = {};
+  if (auth2.clientId !== void 0) meta2.clientId = auth2.clientId;
+  if (auth2.clientSecretEnv !== void 0) meta2.clientSecretEnv = auth2.clientSecretEnv;
+  return meta2;
+}
 var ALL_AGENTS = [
   "claude-code",
   "codex",
@@ -15161,12 +15171,68 @@ function capabilityDeliveryForAgent(agentId, mcp) {
   return mcp.runtime?.delivery?.[agentId] ?? "native";
 }
 
+// src/lib/secretEnv.ts
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+var LINE_RE = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/;
+var VAR_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function isValidSecretVarName(name) {
+  return VAR_NAME_RE.test(name);
+}
+function parseDotenv(content) {
+  const result = {};
+  for (const rawLine of content.split("\n")) {
+    const line = rawLine.trim();
+    if (line === "" || line.startsWith("#")) continue;
+    const match = LINE_RE.exec(line);
+    if (match) result[match[1]] = match[2];
+  }
+  return result;
+}
+function loadEnvFile(path) {
+  return existsSync(path) ? parseDotenv(readFileSync(path, "utf-8")) : {};
+}
+function resolveSecretEnv(names, policy) {
+  const result = {};
+  if (policy.envFile) {
+    const map = loadEnvFile(policy.envFile);
+    for (const name of names) result[name] = map[name];
+  } else {
+    for (const name of names) result[name] = process.env[name];
+  }
+  return result;
+}
+
 // src/core/canonical.ts
-function fromServerDefYaml(def) {
-  const { static_env, env_aliases, ...rest } = def;
+function fromServerDefYaml(serverName, def) {
+  const { static_env, env_aliases, auth: auth2, ...rest } = def;
   const out = { ...rest };
   if (static_env) out.staticEnv = static_env;
   if (env_aliases) out.envAliases = env_aliases;
+  if (auth2 !== void 0) out.auth = fromAuthYaml(serverName, auth2);
+  return out;
+}
+function fromAuthYaml(serverName, auth2) {
+  if (auth2 === "oauth") return "oauth";
+  if (typeof auth2 !== "object" || auth2 === null) {
+    throw new Error(`mcp/servers.yaml: "${serverName}" auth must be the scalar "oauth" or { kind: oauth, client_id?, client_secret_env? }`);
+  }
+  const { kind, client_id, client_secret_env, ...extra } = auth2;
+  const unknownKey = Object.keys(extra)[0];
+  if (unknownKey !== void 0) {
+    throw new Error(`mcp/servers.yaml: "${serverName}" auth has unrecognized key "${unknownKey}" \u2014 expected kind, client_id, client_secret_env`);
+  }
+  if (kind !== "oauth") {
+    throw new Error(`mcp/servers.yaml: "${serverName}" auth.kind must be "oauth" \u2014 kind is the only recognized discriminator`);
+  }
+  if (client_id !== void 0 && typeof client_id !== "string") {
+    throw new Error(`mcp/servers.yaml: "${serverName}" auth.client_id must be a string`);
+  }
+  if (client_secret_env !== void 0 && (typeof client_secret_env !== "string" || !isValidSecretVarName(client_secret_env))) {
+    throw new Error(`mcp/servers.yaml: "${serverName}" auth.client_secret_env must be a variable NAME (e.g. FIGMA_CLIENT_SECRET), never a secret value`);
+  }
+  const out = { kind: "oauth" };
+  if (typeof client_id === "string") out.clientId = client_id;
+  if (typeof client_secret_env === "string") out.clientSecretEnv = client_secret_env;
   return out;
 }
 function trellisRoot(homeDir) {
@@ -15201,18 +15267,18 @@ function listSkillDirs(dir) {
   return skills;
 }
 function loadScopeYaml(path) {
-  if (!existsSync(path)) {
+  if (!existsSync2(path)) {
     return {};
   }
-  const parsed = (0, import_yaml.parse)(readFileSync(path, "utf-8"));
+  const parsed = (0, import_yaml.parse)(readFileSync2(path, "utf-8"));
   return parsed ?? {};
 }
 function loadServersYaml(path) {
-  if (!existsSync(path)) {
+  if (!existsSync2(path)) {
     return { servers: {}, knownHostInjected: [] };
   }
-  const parsed = (0, import_yaml.parse)(readFileSync(path, "utf-8")) ?? {};
-  const servers = Object.fromEntries(Object.entries(parsed.servers ?? {}).map(([name, def]) => [name, fromServerDefYaml(def)]));
+  const parsed = (0, import_yaml.parse)(readFileSync2(path, "utf-8")) ?? {};
+  const servers = Object.fromEntries(Object.entries(parsed.servers ?? {}).map(([name, def]) => [name, fromServerDefYaml(name, def)]));
   return {
     servers,
     knownHostInjected: parsed.known_host_injected ?? [],
@@ -15252,10 +15318,10 @@ function fromGatewayYaml(gateway) {
   return out;
 }
 function loadSecretsPolicyYaml(path, homeDir) {
-  if (!existsSync(path)) {
+  if (!existsSync2(path)) {
     return { allowedVars: [], rejectPatterns: [] };
   }
-  const parsed = (0, import_yaml.parse)(readFileSync(path, "utf-8")) ?? {};
+  const parsed = (0, import_yaml.parse)(readFileSync2(path, "utf-8")) ?? {};
   return {
     allowedVars: parsed.allowed_vars ?? [],
     rejectPatterns: (parsed.reject_patterns ?? []).map((pattern) => new RegExp(pattern)),
@@ -15263,10 +15329,10 @@ function loadSecretsPolicyYaml(path, homeDir) {
   };
 }
 function loadManagedYaml(path, diagnostics) {
-  if (!existsSync(path)) {
+  if (!existsSync2(path)) {
     return [];
   }
-  const parsed = (0, import_yaml.parse)(readFileSync(path, "utf-8")) ?? {};
+  const parsed = (0, import_yaml.parse)(readFileSync2(path, "utf-8")) ?? {};
   const raw = parsed.agents ?? [];
   const valid = [];
   for (const id of raw) {
@@ -15285,11 +15351,30 @@ function validAgentIds(scope) {
   if (!scope) return true;
   return scope.every((id) => ALL_AGENTS.includes(id));
 }
+function assertAuthMetadataClean(mcp, policy) {
+  for (const [name, def] of Object.entries(mcp.servers)) {
+    const meta2 = oauthClientMetadata(def.auth);
+    const fields = [
+      ["client_id", meta2.clientId],
+      ["client_secret_env", meta2.clientSecretEnv]
+    ];
+    for (const [field, value] of fields) {
+      if (value === void 0) continue;
+      for (const pattern of policy.rejectPatterns) {
+        if (pattern.test(value)) {
+          throw new Error(
+            `mcp/servers.yaml: "${name}" auth.${field} matches a secrets.policy.yaml reject pattern \u2014 client_id must be the provider-published id, client_secret_env a variable name; the offending value is intentionally not printed`
+          );
+        }
+      }
+    }
+  }
+}
 function loadCanonicalSource(homeDir = homedir()) {
   const root = trellisRoot(homeDir);
-  if (!existsSync(root)) {
+  if (!existsSync2(root)) {
     throw new Error(
-      `No canonical source at ${root}. Create it before running trellis sync \u2014 see docs/architecture.md's canonical schema.`
+      `No canonical source at ${root}. Run trellis init before trellis sync.`
     );
   }
   const diagnostics = [];
@@ -15326,17 +15411,17 @@ function loadCanonicalSource(homeDir = homedir()) {
       }
     }
   }
+  const mcp = loadServersYaml(join(root, "mcp", "servers.yaml"));
+  const secretsPolicy = loadSecretsPolicyYaml(join(root, "secrets.policy.yaml"), homeDir);
+  assertAuthMetadataClean(mcp, secretsPolicy);
   return {
     instructionsFile: join(root, "agents.md"),
     managedAgents,
     skills,
     agents,
     memories,
-    mcp: loadServersYaml(join(root, "mcp", "servers.yaml")),
-    // P2's pre-write guard (src/adapters/mcpPlan.ts) uses its own narrow,
-    // hardcoded floor instead of this field — see design.md D1 in
-    // trellis-secrets-audit-p3.
-    secretsPolicy: loadSecretsPolicyYaml(join(root, "secrets.policy.yaml"), homeDir),
+    mcp,
+    secretsPolicy,
     diagnostics
   };
 }
@@ -15358,33 +15443,6 @@ function codexBearerTokenEnvVar(def) {
   return BEARER_TOKEN_VALUE_RE.exec(value)?.[1];
 }
 
-// src/lib/secretEnv.ts
-import { appendFileSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2 } from "node:fs";
-var LINE_RE = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/;
-function parseDotenv(content) {
-  const result = {};
-  for (const rawLine of content.split("\n")) {
-    const line = rawLine.trim();
-    if (line === "" || line.startsWith("#")) continue;
-    const match = LINE_RE.exec(line);
-    if (match) result[match[1]] = match[2];
-  }
-  return result;
-}
-function loadEnvFile(path) {
-  return existsSync2(path) ? parseDotenv(readFileSync2(path, "utf-8")) : {};
-}
-function resolveSecretEnv(names, policy) {
-  const result = {};
-  if (policy.envFile) {
-    const map = loadEnvFile(policy.envFile);
-    for (const name of names) result[name] = map[name];
-  } else {
-    for (const name of names) result[name] = process.env[name];
-  }
-  return result;
-}
-
 // src/adapters/mcpPlan.ts
 var HUB_ENTRY_NAME = "trellis-hub";
 var GATEWAY_ENTRY_NAME = "trellis";
@@ -15392,7 +15450,7 @@ var RUNTIME_ENTRY_NAME = "trellis";
 var GATEWAY_COMMAND = "trellis";
 var RUNTIME_COMMAND = "trellis";
 function isOAuthMcpServer(def) {
-  return def.auth === "oauth";
+  return isOAuthAuth(def.auth);
 }
 function isGatewayAgent(agentId, mcp, managedAgents) {
   const route = mcp.routes?.[agentId];
@@ -32557,7 +32615,7 @@ async function trellisMcpBridge(pi, homeDir = homedir2(), connectTimeoutMs = DEF
     desired.map(async ({ name, def }) => {
       let client;
       try {
-        const effectiveDef = def.auth === "oauth" && def.url ? await withOAuthHeader(name, def, homeDir) : def;
+        const effectiveDef = isOAuthAuth(def.auth) && def.url ? await withOAuthHeader(name, def, homeDir) : def;
         client = await connectServer(effectiveDef, canonical.secretsPolicy, connectTimeoutMs, CLIENT_INFO);
       } catch (err) {
         console.error(`trellis-mcp-bridge: failed to connect to MCP server "${name}": ${err instanceof Error ? err.message : String(err)}`);

package/dist/pi-bridge/index.js

@@ -17,7 +17,7 @@ import { resolveMcpPlan } from "../adapters/mcpPlan.js";
 import { connectServer, withTimeout, DEFAULT_CONNECT_TIMEOUT_MS } from "../lib/mcpConnect.js";
 import { McpToolRegistry } from "../lib/mcpToolRegistry.js";
 import { withOAuthHeader } from "../lib/gatewayBackend.js";
-import { ALL_AGENTS } from "../core/types.js";
+import { ALL_AGENTS, isOAuthAuth } from "../core/types.js";
 import { 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
@@ -75,7 +75,7 @@ export default async function trellisMcpBridge(pi, homeDir = homedir(), connectT
     const discovered = await Promise.all(desired.map(async ({ name, def }) => {
         let client;
         try {
-            const effectiveDef = def.auth === "oauth" && def.url
+            const effectiveDef = isOAuthAuth(def.auth) && def.url
                 ? await withOAuthHeader(name, def, homeDir)
                 : def;
             client = await connectServer(effectiveDef, canonical.secretsPolicy, connectTimeoutMs, CLIENT_INFO);

package/docs/architecture.md

@@ -266,6 +266,25 @@ flow for Claude Code/Codex/Kiro; Pi's bridge is the client for its direct OAuth
 connection and may use Trellis's own OAuth store. Trellis never infers this
 classification from a URL or a transient 401.
 
+The classification optionally carries pre-registered client metadata, for
+providers that refuse Dynamic Client Registration and require an allowlisted
+client instead:
+
+```yaml
+auth:
+  kind: oauth
+  client_id: "<provider-published-id>"    # public by design, literal
+  client_secret_env: PROVIDER_CLIENT_SECRET  # a NAME, resolved via secrets.policy.yaml
+```
+
+`client_id` wins over DCR when present; DCR stays the fallback when it is
+absent. There is deliberately no literal secret field — a secret enters only
+as a variable name, the same `env`-style discipline everything else follows.
+See docs/mcp-oauth-matrix.md for which providers are open to registration and
+which are not, and for the distribution rule: examples, docs, and seed data
+ship placeholders only, and only provider-**published** identifiers may ever
+be pre-filled.
+
 Trellis still 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/`, but that

package/docs/mcp-oauth-matrix.md

@@ -0,0 +1,140 @@
+# Remote MCP providers — how OAuth identity works, and where Trellis can help
+
+`trellis mcp auth <name>` can only complete an authorization-code grant if it
+is allowed to *have* a client identity. Whether it may is entirely the
+provider's decision, and that decision splits remote MCP providers into two
+families. This page records which family each known provider is in, what
+evidence that rests on, and what Trellis does in each case.
+
+Read alongside docs/architecture.md §"Static header auth vs. real OAuth",
+which covers the *other* shape — a long-lived bearer token or API key in a
+`headers` field — and why Trellis builds for both.
+
+## The two families
+
+**DCR-open.** The provider implements RFC 7591 Dynamic Client Registration.
+Trellis POSTs its own metadata, receives a `client_id`, and holds its own
+identity per installation. Nothing a user has to supply; nothing Trellis has
+to distribute. This already works: it is what `trellis mcp auth` has done
+since `trellis-mcp-gateway-hosting`.
+
+**Allowlist.** The provider refuses registration — either by not advertising a
+`registration_endpoint`, or by answering it with `unauthorized_client` — and
+requires clients to be pre-registered with the provider. There is no
+self-service path: the user obtains a `client_id` out of band and supplies it.
+That is what the `auth.client_id` / `auth.client_secret_env` fields exist for
+(trellis-mcp-oauth-static-client design.md D1–D3).
+
+The 2026-07-28 MCP authorization spec moved in the allowlist direction,
+downgrading Dynamic Client Registration from a MUST to a MAY in favour of
+pre-registration. Expect the second family to grow; the mechanism, not the
+per-provider list, is what Trellis commits to.
+
+## Matrix
+
+| Provider | Family | What identifies the client | Evidence | Confidence |
+|---|---|---|---|---|
+| Sentry | DCR-open | `client_id` from DCR | Local successful grant against the real server; secondary sources describing its DCR endpoint | Medium — see the note below |
+| Supabase | DCR-open | `client_id` from DCR | Same | Medium |
+| Morphix | DCR-open | `client_id` from DCR | Same | Medium |
+| GitHub | DCR-open | `client_id` from DCR | Same | Medium |
+| Notion | DCR-open | `client_id` from DCR | Same | Medium |
+| Linear | DCR-open | `client_id` from DCR | Same | Medium |
+| Cloudflare | DCR-open | `client_id` from DCR | Same | Medium |
+| Figma | Allowlist | Provider-published `client_id`, supplied by the user | Registration refused with `unauthorized_client` — observed directly, and the reason this change exists | High |
+
+**On confidence.** "High" means the behavior was observed directly against the
+live provider and the failure (or success) is reproducible from this
+repository's own test fixtures. "Medium" means the status rests on a working
+local grant plus secondary sources rather than a first-party policy statement —
+the *observed* behavior is solid, but a provider is free to change its
+registration policy at any time, and none of these have published a
+contractual commitment either way. Sentry is explicitly in this bucket
+(trellis-mcp-oauth-static-client design.md D6): the local grant proves
+registration works today, not that it will next quarter.
+
+Treat the whole table as a snapshot of observed behavior, not as provider
+policy. `trellis mcp auth` reports the actual failure when a row goes stale —
+see "When a provider refuses" below.
+
+## What actually identifies a client
+
+There is no magic header and no provider-specific handshake. Any OAuth 2.0
+authorization server that speaks the MCP authorization profile identifies a
+client by a combination of:
+
+- **`client_id`** — the identity itself. Public by design for a public client:
+  it travels in the browser URL on every authorization (`?client_id=...`), so
+  it is visible to the user, their browser history, and any proxy in between.
+  Its security rests on the *other* factors here, never on its secrecy.
+- **Exact `redirect_uri` match** — registered with the client and required to
+  match byte-for-byte. This is why Trellis's loopback callback is what it is:
+  `http://127.0.0.1:<port>/callback`, with the port chosen by the OS at bind
+  time. A pre-registered client whose provider pins one specific port is the
+  one case where a fixed `callbackPort` is needed.
+- **PKCE (RFC 7636, `S256`)** — the proof that whoever redeems the code is
+  whoever started the flow. The verifier never travels through the browser;
+  only its SHA-256 challenge does. Trellis's fake Authorization Server in the
+  test suite *enforces* this rather than rubber-stamping it, so the tests
+  cannot pass for a client that gets PKCE wrong.
+- **`resource` parameter** — binds the grant to the MCP server it was issued
+  for, so a token minted for one server is not replayable against another.
+
+Nothing in that list is a secret for a public client, which is exactly why
+`client_id` is a plain literal in canonical YAML and `client_secret_env` — the
+one field that *is* a credential — is a variable NAME resolved through
+`secrets.policy.yaml` and never a value (design.md D2).
+
+## When a provider refuses
+
+`trellis mcp auth <name>` tries pre-registered metadata first, then DCR. When
+both are unavailable it fails with the remediation rather than a bare status
+code:
+
+```
+"figma": dynamic client registration was refused (unauthorized_client) —
+register a client with the provider and set auth.client_id (plus
+auth.client_secret_env if the provider requires a secret) under this server in
+~/.trellis/mcp/servers.yaml
+```
+
+The fix is then two commands:
+
+```sh
+trellis mcp set figma --auth oauth --client-id <provider-published-id>
+trellis mcp auth figma
+```
+
+The id comes from the provider. Trellis does not ship one, look one up for
+you, or read another client's stored credentials to borrow an identity —
+that last option is rejected structurally, not just by policy (design.md D5:
+borrowing a refresh token makes both clients fight over rotation, and reading
+another tool's credential store would mean decrypting files Trellis does not
+own).
+
+## Distribution boundary
+
+Trellis is open source. What it distributes is a mechanism — the schema field,
+the flow, the tests. It does not distribute an identity.
+
+A user who obtains a `client_id` and pastes it into their own
+`~/.trellis/mcp/servers.yaml` is making their own decision under the provider's
+terms, in the same position as anyone running `mcp-remote
+--static-oauth-client-info`. Trellis shipping that same id in
+`schema/servers.example.yaml`, in this page, or in seed data would instead make
+the project itself the distributor of a whitelist-bypass tool. So:
+
+- Examples and docs use placeholders only — see the commented block in
+  `schema/servers.example.yaml`.
+- Only provider-**published** identifiers may ever be pre-filled. None exist
+  today, so nothing is pre-filled.
+- A literal that matches `reject_patterns` is refused at load and at write, so
+  a pasted credential cannot quietly become part of the canonical source.
+
+## See also
+
+- docs/architecture.md §"Static header auth vs. real OAuth" — the other shape.
+- `schema/servers.example.yaml` — the object form, with placeholders.
+- trellis-mcp-oauth-static-client design.md — D1 (field shape), D2 (literal vs.
+  name), D3 (metadata wins over DCR), D4 (distribution boundary), D5 (no token
+  borrowing), D6 (this matrix's confidence notes).

package/docs/research.md

@@ -216,6 +216,17 @@ every agent's adapter renders it through the exact same reference mechanism
 `env` already uses, and the pi bridge resolves it through the exact same
 `resolveSecretEnv` call.
 
+The same reference-not-value rule is what shapes OAuth client metadata
+(trellis-mcp-oauth-static-client). A public client's `client_id` is published
+by design — it rides in the browser URL on every authorization — so it is a
+plain literal, comparable to how `mcp-remote --static-oauth-client-info` and
+`claude mcp add --client-id` already treat it. A `client_secret` is the
+opposite kind of thing, so it enters only as `client_secret_env`, a variable
+NAME resolved through this same machinery; there is deliberately no literal
+secret field. Which providers accept an unregistered client at all is a
+per-provider question — see docs/mcp-oauth-matrix.md, including its note that
+that matrix records observed behavior, not provider policy.
+
 ## pi coding agent — the one place we write real code, not config generation
 
 Reverse-engineered directly from the installed binary

package/docs/skills-over-mcp.md

@@ -0,0 +1,79 @@
+# Skills over MCP — what Trellis serves, and what it does not claim
+
+The MCP Skills extension (`io.modelcontextprotocol/skills`, SEP-2640, Final)
+defines how a server publishes Agent Skills through the Resources primitive.
+Trellis's runtime serves its canonical skills in that shape. This page records
+the exact behavior, including what is deliberately *not* done.
+
+## What is served
+
+For each canonical skill in the requesting agent's scope:
+
+- `skill://<name>/SKILL.md` and every supporting file at
+  `skill://<name>/<relative-path>`, through `resources/list` and
+  `resources/read`.
+- `skills/list` and `skills/get`, returning the specified entry: the skill's
+  `uri`, its frontmatter verbatim, and a complete manifest of
+  `{ uri, digest, size }` per file, with `resultType`, `ttlMs` and `cacheScope`.
+  `cacheScope` is `private` because the catalog differs per agent.
+
+The existing surface is unchanged: `trellis.skills.search|read|read_file` and
+`trellis://skills/<name>/SKILL.md` keep working exactly as before. The
+`skill://` view is a second, additive view of the same data.
+
+## The manifest is computed from the bytes served
+
+`digest` is `sha256:` plus 64 lowercase hex characters of the raw bytes;
+`size` is their length. The same reader produces the manifest and the
+`resources/read` response, so they cannot disagree. Invalid UTF-8 is returned as
+a base64 `blob` rather than lossy `text`, so the bytes a host verifies are the
+bytes that were hashed.
+
+A file the reader refuses — secret-shaped path, hidden file or directory,
+`node_modules`, anything resolving outside the skill root, oversized — is absent
+from the manifest and unreadable, both. A skill with more than 512 files or
+16 MiB is omitted whole and reported on stderr, never published with a partial
+manifest.
+
+A skill is served under `skill://` only when its directory name equals its
+frontmatter `name`, that name is a valid Agent Skills name (lowercase letters,
+digits, single hyphens), and it has a non-empty `description`. Otherwise it is
+omitted and the reason is reported once. It stays reachable through the existing
+tools.
+
+## A digest is consistency, not trust
+
+The extension is explicit that digests are unsigned and that an intermediary can
+rewrite entry and content together. A matching digest tells a host the bytes
+match the manifest; it says nothing about whether the content is safe. Nothing in
+Trellis treats a match as an authorization.
+
+## The extension is not declared yet
+
+The extension is declared through `server/discover`, introduced with protocol
+revision 2026-07-28. The MCP SDK Trellis uses speaks at most 2025-11-25 and has
+neither `server/discover` nor `skills/*`, and the specification defines no
+declaration for the `initialize` handshake. Declaring it in another field would
+invent a protocol, and a conforming client only issues `skills/list` after
+observing a declaration anyway.
+
+So on today's SDK the runtime declares nothing, answers `skills/list` and
+`skills/get` through the SDK's fallback for unregistered methods, and serves
+`skill://` as ordinary resources — which the specification expressly allows. Once
+the SDK exposes `server/discover`, the declaration is a one-place change. Any other
+unknown method still gets JSON-RPC `-32601`.
+
+## Relaying skills from upstream servers is not implemented
+
+Today an upstream server's skills are not relayed — the gateway backend
+aggregates tools only. When a change adds that, it must:
+
+- identify a skill by (upstream label, URI) together, never by URI alone, with a
+  namespace per upstream;
+- never let an upstream skill shadow a canonical skill or another upstream's;
+- bind reads to the originating upstream, with no cross-upstream reads;
+- pass the upstream manifest through unchanged or re-derive it from the relayed
+  bytes — never pair an upstream digest with different bytes;
+- not write an upstream skill into `~/.trellis/skills` automatically. The
+  specification requires per-skill user approval before such content is used, and
+  materializing it would bypass that.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-trellis",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "A unified Code Agent Runtime for Skills, MCP, Memory, and shared instructions across Claude Code, Codex, Kiro, pi, Kimi Code, and ZCode.",
   "license": "MIT",
   "author": "Paul Leo",
@@ -34,7 +34,7 @@
     "pretest": "node scripts/build-pi-bridge.mjs",
     "test": "tsx --test \"test/unit/**/*.test.ts\"",
     "verify-pack": "node scripts/verify-pack.mjs",
-    "prepublishOnly": "npm run typecheck && npm run build && npm test && npm run verify-pack"
+    "prepublishOnly": "npm run typecheck && npm run build && npm test"
   },
   "engines": {
     "node": ">=20"

package/schema/servers.example.yaml

@@ -118,6 +118,24 @@ servers:
     # Explicit OAuth classification keeps this server direct when an Agent
     # uses gateway mode. Trellis never infers OAuth from a URL or 401.
     # auth: oauth
+    #
+    # Object form (trellis-mcp-oauth-static-client): for a provider that
+    # rejects Dynamic Client Registration (Figma does — `unauthorized_client`)
+    # and requires a pre-registered client. `kind: oauth` is the only
+    # discriminator and the only required key; a bare `auth: oauth` above and
+    # a metadata-less `{ kind: oauth }` are exactly equivalent.
+    #   - `client_id` is a PUBLIC literal by design — fine to commit. Use the
+    #     identifier the PROVIDER published for this client; a self-registered
+    #     one from your own account only if you accept managing it.
+    #   - `client_secret_env` is a variable NAME, resolved through
+    #     secrets.policy.yaml at `trellis mcp auth` time — never a secret
+    #     value, and never a literal secret field (there is none).
+    # Placeholders below on purpose: only provider-published identifiers may
+    # ever be pre-filled in a distribution artifact.
+    # auth:
+    #   kind: oauth
+    #   client_id: "<provider-published-client-id>"
+    #   client_secret_env: FIGMA_CLIENT_SECRET
 
   # Example of a private/agent-specific server: only Claude Code has a use
   # for this one, so the other three agents never see it defined at all.