agent-trellis 0.14.0 → 0.15.0

package/dist/core/adapter.d.ts

@@ -98,6 +98,20 @@ export interface AdapterPlanItem {
             skillsEnabled: boolean | null;
         };
     };
+    /** Set when this item renders the workspace (`.agents/`) layer rather
+     * than the global one (trellis-workspace-scope) — the command layer
+     * routes these to the workspace apply functions, never to the agent's
+     * global adapter apply. */
+    layer?: "workspace";
+    /** Only set when `layer === "workspace"`, `kind === "skill"`, and
+     * `action === "create"`: the canonical directory to copy into `target`
+     * (workspace skills are COPIED, never symlinked — rendered artifacts
+     * must be committable and Windows-safe, design D5). */
+    copyFrom?: string;
+    /** Only set when `layer === "workspace"`, `kind === "instructions"`, and
+     * `action === "create"`: the full rendered file content (managed marker
+     * header + workspace AGENTS.md body) to write at `target`. */
+    fileContent?: string;
 }
 export interface AdapterVerifyResult {
     ok: boolean;

package/dist/core/canonical.d.ts

@@ -1,38 +1,14 @@
 /**
- * Loads `~/.trellis/` into a `CanonicalSource`. Global only — no `root`
- * parameter, no workspace merge (docs/architecture.md "Global vs.
- * workspace scope"). See openspec/changes/trellis-sync-p1/specs/
- * canonical-source-loading/spec.md for the exact contract this implements.
+ * Loads `~/.trellis/` into a `CanonicalSource`. Global-only by default —
+ * no working-directory consultation; a caller that explicitly discovered a
+ * workspace root (src/lib/workspace.ts `findWorkspaceRoot`) may pass it in
+ * to layer `<workspace>/.agents/` over the global source
+ * (openspec/changes/trellis-workspace-scope, design D2).
  */
 import type { AgentId, CapabilityDelivery, CanonicalSource, McpRoute, McpServerDef, Scope } from "./types.js";
 import type { BackupSession } from "../lib/backup.js";
-/**
- * The on-disk shape for one server entry — `static_env`/`env_aliases`
- * (snake_case, like every other multi-word key across `.trellis/*.yaml`)
- * are translated to `McpServerDef.staticEnv`/`envAliases` (camelCase)
- * below, and `auth`'s object form carries `client_id`/`client_secret_env`
- * the same way (trellis-mcp-static-env-and-disabled-servers,
- * trellis-migrate-env-var-alias, trellis-mcp-oauth-static-client).
- */
-type McpServerDefYaml = Omit<McpServerDef, "staticEnv" | "envAliases" | "auth"> & {
-    static_env?: Record<string, string>;
-    env_aliases?: Record<string, string>;
-    auth?: McpAuthYaml;
-};
-/** The on-disk `auth`: the `oauth` scalar exactly as before, or the object
- * form whose keys are snake_case like every other multi-word key in
- * `.trellis/*.yaml`. Values are `unknown` until `fromAuthYaml` validates
- * them — a YAML cast is optimistic, validation is this module's job. */
-type McpAuthYaml = string | {
-    kind?: unknown;
-    owner?: unknown;
-    client_id?: unknown;
-    client_secret_env?: unknown;
-};
-/** Inverse of `fromServerDefYaml` (trellis-canonical-cli-crud) — strips
- * `undefined` fields so the written YAML never gets a literal `null`
- * for an omitted optional. */
-export declare function toServerDefYaml(def: McpServerDef): McpServerDefYaml;
+export { toServerDefYaml } from "./mcpServerDef.js";
+export type { McpServerDefYaml } from "./mcpServerDef.js";
 export type ServersYamlWriteResult = {
     ok: true;
 } | {
@@ -138,6 +114,18 @@ export declare function ensureGitignoreEntry(gitignorePath: string, line: string
  * `export` prefix of its own.
  */
 export declare function ensureShellEnvSource(rcPath: string, envFilePath: string, backup?: BackupSession): void;
+/**
+ * Options form of `loadCanonicalSource` (trellis-workspace-scope design D2).
+ * `homeDir` anchors BOTH the global canonical root and user-home semantics
+ * (secrets `env_file` `~` expansion) at all times; `workspaceDir` — a root
+ * previously discovered via `findWorkspaceRoot` — only adds the `.agents/`
+ * project layer on top, never relocates either.
+ */
+export interface LoadCanonicalOptions {
+    homeDir?: string;
+    workspaceDir?: string | null;
+}
 /** Load the global canonical source from the supplied home directory. */
 export declare function loadCanonicalSource(homeDir?: string): CanonicalSource;
-export {};
+/** Load the global canonical source, optionally layered with an explicit workspace's `.agents/`. */
+export declare function loadCanonicalSource(options: LoadCanonicalOptions): CanonicalSource;

package/dist/core/canonical.js

@@ -1,93 +1,19 @@
 /**
- * Loads `~/.trellis/` into a `CanonicalSource`. Global only — no `root`
- * parameter, no workspace merge (docs/architecture.md "Global vs.
- * workspace scope"). See openspec/changes/trellis-sync-p1/specs/
- * canonical-source-loading/spec.md for the exact contract this implements.
+ * Loads `~/.trellis/` into a `CanonicalSource`. Global-only by default —
+ * no working-directory consultation; a caller that explicitly discovered a
+ * workspace root (src/lib/workspace.ts `findWorkspaceRoot`) may pass it in
+ * to layer `<workspace>/.agents/` over the global source
+ * (openspec/changes/trellis-workspace-scope, design D2).
  */
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { isMap, isSeq, parse as parseYaml, parseDocument } from "yaml";
 import { ALL_AGENTS, oauthClientMetadata } from "./types.js";
-import { isValidSecretVarName } from "../lib/secretEnv.js";
-function fromServerDefYaml(serverName, def) {
-    const { static_env, env_aliases, auth, ...rest } = def;
-    const out = { ...rest };
-    if (static_env)
-        out.staticEnv = static_env;
-    if (env_aliases)
-        out.envAliases = env_aliases;
-    if (auth !== undefined)
-        out.auth = fromAuthYaml(serverName, auth);
-    return out;
-}
-/**
- * `auth` translation and shape validation
- * (trellis-mcp-oauth-static-client tasks 1.1/1.3): the scalar and the
- * object form share one discriminator — `kind: oauth` — and the object
- * accepts exactly `kind`, `owner`, `client_id`, `client_secret_env`. Everything
- * else is refused here at load, naming the field but never echoing the
- * value: an invalid `client_secret_env` is at best a typo, at worst a
- * pasted secret.
- */
-function fromAuthYaml(serverName, auth) {
-    if (auth === "oauth")
-        return "oauth";
-    if (typeof auth !== "object" || auth === null) {
-        throw new Error(`mcp/servers.yaml: "${serverName}" auth must be the scalar "oauth" or { kind: oauth, client_id?, client_secret_env? }`);
-    }
-    const { kind, owner, client_id, client_secret_env, ...extra } = auth;
-    const unknownKey = Object.keys(extra)[0];
-    if (unknownKey !== undefined) {
-        throw new Error(`mcp/servers.yaml: "${serverName}" auth has unrecognized key "${unknownKey}" — expected kind, owner, client_id, client_secret_env`);
-    }
-    if (kind !== "oauth") {
-        throw new Error(`mcp/servers.yaml: "${serverName}" auth.kind must be "oauth" — kind is the only recognized discriminator`);
-    }
-    if (client_id !== undefined && typeof client_id !== "string") {
-        throw new Error(`mcp/servers.yaml: "${serverName}" auth.client_id must be a string`);
-    }
-    if (client_secret_env !== undefined && (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 (owner !== undefined && owner !== "agent" && owner !== "trellis")
-        throw new Error(`mcp/servers.yaml: "${serverName}" auth.owner must be agent or trellis`);
-    if (owner !== undefined)
-        out.owner = owner;
-    if (typeof client_id === "string")
-        out.clientId = client_id;
-    if (typeof client_secret_env === "string")
-        out.clientSecretEnv = client_secret_env;
-    return out;
-}
-/** Inverse of `fromServerDefYaml` (trellis-canonical-cli-crud) — strips
- * `undefined` fields so the written YAML never gets a literal `null`
- * for an omitted optional. */
-export function toServerDefYaml(def) {
-    const { staticEnv, envAliases, auth, ...rest } = def;
-    const out = { ...rest };
-    if (staticEnv)
-        out.static_env = staticEnv;
-    if (envAliases)
-        out.env_aliases = envAliases;
-    if (auth !== undefined) {
-        out.auth =
-            typeof auth === "string"
-                ? auth
-                : {
-                    kind: auth.kind,
-                    ...(auth.owner !== undefined ? { owner: auth.owner } : {}),
-                    ...(auth.clientId !== undefined ? { client_id: auth.clientId } : {}),
-                    ...(auth.clientSecretEnv !== undefined ? { client_secret_env: auth.clientSecretEnv } : {}),
-                };
-    }
-    for (const key of Object.keys(out)) {
-        if (out[key] === undefined)
-            delete out[key];
-    }
-    return out;
-}
+import { fromServerDefYaml, toServerDefYaml } from "./mcpServerDef.js";
+import { loadWorkspaceLayer } from "../lib/workspace.js";
+import { mergeWorkspaceLayer } from "../lib/workspaceMerge.js";
+export { toServerDefYaml } from "./mcpServerDef.js";
 function trellisRoot(homeDir) {
     return join(homeDir, ".trellis");
 }
@@ -559,8 +485,9 @@ function assertAuthMetadataClean(mcp, policy) {
         }
     }
 }
-/** Load the global canonical source from the supplied home directory. */
-export function loadCanonicalSource(homeDir = homedir()) {
+export function loadCanonicalSource(arg = {}) {
+    const options = typeof arg === "string" ? { homeDir: arg } : arg;
+    const homeDir = options.homeDir ?? homedir();
     const root = trellisRoot(homeDir);
     if (!existsSync(root)) {
         throw new Error(`No canonical source at ${root}. Run trellis init before trellis sync.`);
@@ -603,7 +530,7 @@ export 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 {
+    const source = {
         instructionsFile: join(root, "agents.md"),
         managedAgents,
         skills,
@@ -613,4 +540,9 @@ export function loadCanonicalSource(homeDir = homedir()) {
         secretsPolicy,
         diagnostics,
     };
+    if (options.workspaceDir) {
+        const layer = loadWorkspaceLayer(options.workspaceDir, secretsPolicy);
+        return mergeWorkspaceLayer(source, layer);
+    }
+    return source;
 }

package/dist/core/mcpServerDef.d.ts

@@ -0,0 +1,39 @@
+/**
+ * On-disk ⇄ canonical translation for one MCP server entry, shared by
+ * `~/.trellis/mcp/servers.yaml` (YAML) and `<workspace>/.agents/config.json`
+ * (JSON). Both use the identical snake_case field set so there is exactly
+ * one server schema and one validator (trellis-workspace-scope design D1);
+ * the `source` label exists only so diagnostics name the file the user
+ * actually edited.
+ */
+import type { McpServerDef } from "./types.js";
+/**
+ * The on-disk shape for one server entry — `static_env`/`env_aliases`
+ * (snake_case, like every other multi-word key across `.trellis/*.yaml`)
+ * are translated to `McpServerDef.staticEnv`/`envAliases` (camelCase)
+ * below, and `auth`'s object form carries `client_id`/`client_secret_env`/
+ * `client_name` the same way (trellis-mcp-static-env-and-disabled-servers,
+ * trellis-migrate-env-var-alias, trellis-mcp-oauth-static-client,
+ * oauth-client-name).
+ */
+export type McpServerDefYaml = Omit<McpServerDef, "staticEnv" | "envAliases" | "auth"> & {
+    static_env?: Record<string, string>;
+    env_aliases?: Record<string, string>;
+    auth?: McpAuthYaml;
+};
+/** The on-disk `auth`: the `oauth` scalar exactly as before, or the object
+ * form whose keys are snake_case like every other multi-word key in
+ * `.trellis/*.yaml`. Values are `unknown` until `fromAuthYaml` validates
+ * them — a YAML/JSON cast is optimistic, validation is this module's job. */
+export type McpAuthYaml = string | {
+    kind?: unknown;
+    owner?: unknown;
+    client_id?: unknown;
+    client_secret_env?: unknown;
+    client_name?: unknown;
+};
+export declare function fromServerDefYaml(serverName: string, def: McpServerDefYaml, source?: string): McpServerDef;
+/** Inverse of `fromServerDefYaml` (trellis-canonical-cli-crud) — strips
+ * `undefined` fields so the written file never gets a literal `null`
+ * for an omitted optional. */
+export declare function toServerDefYaml(def: McpServerDef): McpServerDefYaml;

package/dist/core/mcpServerDef.js

@@ -0,0 +1,93 @@
+/**
+ * On-disk ⇄ canonical translation for one MCP server entry, shared by
+ * `~/.trellis/mcp/servers.yaml` (YAML) and `<workspace>/.agents/config.json`
+ * (JSON). Both use the identical snake_case field set so there is exactly
+ * one server schema and one validator (trellis-workspace-scope design D1);
+ * the `source` label exists only so diagnostics name the file the user
+ * actually edited.
+ */
+import { isValidSecretVarName } from "../lib/secretEnv.js";
+export function fromServerDefYaml(serverName, def, source = "mcp/servers.yaml") {
+    const { static_env, env_aliases, auth, ...rest } = def;
+    const out = { ...rest };
+    if (static_env)
+        out.staticEnv = static_env;
+    if (env_aliases)
+        out.envAliases = env_aliases;
+    if (auth !== undefined)
+        out.auth = fromAuthYaml(serverName, auth, source);
+    return out;
+}
+/**
+ * `auth` translation and shape validation
+ * (trellis-mcp-oauth-static-client tasks 1.1/1.3): the scalar and the
+ * object form share one discriminator — `kind: oauth` — and the object
+ * accepts exactly `kind`, `owner`, `client_id`, `client_secret_env`. Everything
+ * else is refused here at load, naming the field but never echoing the
+ * value: an invalid `client_secret_env` is at best a typo, at worst a
+ * pasted secret.
+ */
+function fromAuthYaml(serverName, auth, source) {
+    if (auth === "oauth")
+        return "oauth";
+    if (typeof auth !== "object" || auth === null) {
+        throw new Error(`${source}: "${serverName}" auth must be the scalar "oauth" or { kind: oauth, client_id?, client_secret_env?, client_name? }`);
+    }
+    const { kind, owner, client_id, client_secret_env, client_name, ...extra } = auth;
+    const unknownKey = Object.keys(extra)[0];
+    if (unknownKey !== undefined) {
+        throw new Error(`${source}: "${serverName}" auth has unrecognized key "${unknownKey}" — expected kind, owner, client_id, client_secret_env, client_name`);
+    }
+    if (kind !== "oauth") {
+        throw new Error(`${source}: "${serverName}" auth.kind must be "oauth" — kind is the only recognized discriminator`);
+    }
+    if (client_id !== undefined && typeof client_id !== "string") {
+        throw new Error(`${source}: "${serverName}" auth.client_id must be a string`);
+    }
+    if (client_secret_env !== undefined && (typeof client_secret_env !== "string" || !isValidSecretVarName(client_secret_env))) {
+        throw new Error(`${source}: "${serverName}" auth.client_secret_env must be a variable NAME (e.g. FIGMA_CLIENT_SECRET), never a secret value`);
+    }
+    if (client_name !== undefined && typeof client_name !== "string") {
+        throw new Error(`${source}: "${serverName}" auth.client_name must be a string`);
+    }
+    const out = { kind: "oauth" };
+    if (owner !== undefined && owner !== "agent" && owner !== "trellis")
+        throw new Error(`${source}: "${serverName}" auth.owner must be agent or trellis`);
+    if (owner !== undefined)
+        out.owner = owner;
+    if (typeof client_id === "string")
+        out.clientId = client_id;
+    if (typeof client_secret_env === "string")
+        out.clientSecretEnv = client_secret_env;
+    if (typeof client_name === "string")
+        out.clientName = client_name;
+    return out;
+}
+/** Inverse of `fromServerDefYaml` (trellis-canonical-cli-crud) — strips
+ * `undefined` fields so the written file never gets a literal `null`
+ * for an omitted optional. */
+export function toServerDefYaml(def) {
+    const { staticEnv, envAliases, auth, ...rest } = def;
+    const out = { ...rest };
+    if (staticEnv)
+        out.static_env = staticEnv;
+    if (envAliases)
+        out.env_aliases = envAliases;
+    if (auth !== undefined) {
+        out.auth =
+            typeof auth === "string"
+                ? auth
+                : {
+                    kind: auth.kind,
+                    ...(auth.owner !== undefined ? { owner: auth.owner } : {}),
+                    ...(auth.clientId !== undefined ? { client_id: auth.clientId } : {}),
+                    ...(auth.clientSecretEnv !== undefined ? { client_secret_env: auth.clientSecretEnv } : {}),
+                    ...(auth.clientName !== undefined ? { client_name: auth.clientName } : {}),
+                };
+    }
+    for (const key of Object.keys(out)) {
+        if (out[key] === undefined)
+            delete out[key];
+    }
+    return out;
+}

package/dist/core/types.d.ts

@@ -19,6 +19,10 @@ export interface McpAuthConfig {
     owner?: "agent" | "trellis";
     clientId?: string;
     clientSecretEnv?: string;
+    /** Self-asserted display name an Agent presents at dynamic client
+     * registration — for providers that gate DCR by client name (Figma).
+     * Public metadata, not a credential (oauth-client-name design.md D1). */
+    clientName?: string;
 }
 /** True when `auth` classifies the server as OAuth, in either form. Every
  * former `def.auth === "oauth"` check must go through this now that the
@@ -299,10 +303,11 @@ export interface AgentSnapshot {
 }
 export interface CanonicalSource {
     /**
-     * Global (`~/.trellis`) only for now. Project-local `.trellis/` and its
-     * merge-over-global precedence are an explicit non-goal until a later
-     * phase — see docs/roadmap.md. Don't build workspace resolution ahead of
-     * that decision.
+     * Global (`~/.trellis`) by default. When the caller explicitly supplies a
+     * discovered workspace root, the `<workspace>/.agents/` project layer is
+     * merged over the global layer (workspace wins by ID, `enabled: false`
+     * tombstones) and `workspace` below carries the merge's provenance — see
+     * openspec/changes/trellis-workspace-scope.
      */
     instructionsFile: string;
     /** From `~/.trellis/managed.yaml`. Missing file and `agents: []` both
@@ -313,7 +318,41 @@ export interface CanonicalSource {
     memories: MemoryEntry[];
     mcp: McpConfig;
     secretsPolicy: SecretsPolicy;
+    /** Present only when the source was loaded with a workspace layer. */
+    workspace?: WorkspaceLayerInfo;
     /** e.g. a `scope.yaml` entry naming a skill/agent/memory that doesn't
      * exist — recorded, not a load failure. See `loadCanonicalSource`. */
     diagnostics: string[];
 }
+export type LayerProvenance = "global" | "workspace";
+/** Merge metadata produced when a workspace `.agents/` layer is in scope. */
+export interface WorkspaceLayerInfo {
+    /** Absolute path of the workspace root (the directory containing `.agents/`). */
+    root: string;
+    /** `<root>/.agents/AGENTS.md`, when the workspace declares instructions. */
+    instructionsFile?: string;
+    /** Per-server source layer for every entry in `mcp.servers`. */
+    mcpProvenance: Record<string, LayerProvenance>;
+    /** The pre-merge GLOBAL layer's server map — what global (user-level)
+     * delivery must render, layer-preserving (workspace-delivery spec:
+     * "global config files are untouched by the workspace entries"). Includes
+     * shadowed entries with their GLOBAL definitions (zcode resolves same-name
+     * conflicts user-first, so the global def is what zcode will actually use)
+     * and tombstoned entries (a tombstone only removes the server from the
+     * workspace's effective view; the shared user-level files still carry the
+     * global def for every other context). */
+    mcpGlobalServers: Record<string, McpServerDef>;
+    /** Per-skill source layer for every entry in `skills`. */
+    skillProvenance: Record<string, LayerProvenance>;
+    /** The pre-merge GLOBAL layer's skills — what global (user-level)
+     * delivery must symlink, layer-preserving, same invariant as
+     * `mcpGlobalServers`. Includes entries the workspace shadows, with their
+     * GLOBAL definitions: the user-level skill dirs are shared by every
+     * project, so a workspace override only governs project-level delivery.
+     * (zcode's Runtime SkillProvider is the deliberate exception — it serves
+     * the merged view by design, trellis-workspace-scope task 2.2.) */
+    globalSkills: SkillRef[];
+    /** Global entries the workspace overrode or tombstoned, as
+     * `"mcp:<name>"` / `"skill:<name>"` — surfaced by doctor/status. */
+    shadowed: string[];
+}

package/dist/lib/mcpMigrateRead.d.ts

@@ -35,6 +35,30 @@ export interface McpMigrateReadResult {
  * independent derivations of it.
  */
 export declare function resolvedEnvTextMap(def: Pick<McpServerDef, "env" | "envAliases" | "staticEnv">): Record<string, string>;
+/** Shared by claude-code and kiro — both write the identical JSON shape
+ * (`jsonMcp.ts` is their common writer). Deliberately richer than either
+ * probe's own read-side type: adds `headers`, which both probes' own
+ * types currently omit despite it being a real field Trellis itself
+ * writes for http/sse servers into this exact shape (confirmed via
+ * `grep -n "headers" src/probes/kiro.ts src/probes/claude-code.ts
+ * src/adapters/jsonMcp.ts` — only the writer declares it). */
+interface RichJsonServerDef {
+    type?: "stdio" | "http" | "sse";
+    command?: string;
+    args?: string[];
+    url?: string;
+    env?: Record<string, string>;
+    headers?: Record<string, string>;
+}
+/** Also exported for the workspace-migration scanner's zcode reader
+ * (trellis-workspace-scope task 4.1): zcode's project config nests the
+ * same rich-JSON server shape under `mcp.servers`, so the walker there
+ * reuses this per-entry mapping unchanged. */
+export declare function fromRichJsonServerDef(raw: RichJsonServerDef): McpServerDef | undefined;
+/** Also the workspace-migration scanner's JSON reader (trellis-workspace-
+ * scope task 4.1): project-level `.mcp.json`-shape files parse through
+ * the exact same rules as their global counterparts. */
+export declare function readRichJsonMcpDefs(configPath: string): McpMigrateReadResult;
 export declare function readClaudeCodeMcpDefs(homeDir: string): McpMigrateReadResult;
 export declare function readKiroMcpDefs(homeDir: string): McpMigrateReadResult;
 export declare function readKimiCodeMcpDefs(homeDir: string): McpMigrateReadResult;
@@ -81,3 +105,4 @@ export declare function buildCodexMcpReadResult(mcpEntries: CodexMcpEntryRich[],
  * entry is reported as unsupported instead.
  */
 export declare function readCodexMcpDefs(homeDir: string): McpMigrateReadResult;
+export {};

package/dist/lib/mcpMigrateRead.js

@@ -73,7 +73,11 @@ function splitJsonEnvMap(env) {
         result.staticEnv = literal;
     return result;
 }
-function fromRichJsonServerDef(raw) {
+/** Also exported for the workspace-migration scanner's zcode reader
+ * (trellis-workspace-scope task 4.1): zcode's project config nests the
+ * same rich-JSON server shape under `mcp.servers`, so the walker there
+ * reuses this per-entry mapping unchanged. */
+export function fromRichJsonServerDef(raw) {
     if (raw.url) {
         const transport = raw.type === "sse" ? "sse" : "http";
         const def = { transport, url: raw.url };
@@ -89,7 +93,10 @@ function fromRichJsonServerDef(raw) {
     Object.assign(def, splitJsonEnvMap(raw.env));
     return def;
 }
-function readRichJsonMcpDefs(configPath) {
+/** Also the workspace-migration scanner's JSON reader (trellis-workspace-
+ * scope task 4.1): project-level `.mcp.json`-shape files parse through
+ * the exact same rules as their global counterparts. */
+export function readRichJsonMcpDefs(configPath) {
     const parsed = readJsonFile(configPath);
     const entries = [];
     const unsupported = [];

package/dist/lib/skillProvider.js

@@ -4,10 +4,23 @@ import { resolve, relative, sep } from "node:path";
 import { parse as parseYaml } from "yaml";
 import { isInScope } from "../core/adapter.js";
 import { loadCanonicalSource } from "../core/canonical.js";
+import { findWorkspaceRoot } from "./workspace.js";
 import { resolveScope } from "../core/types.js";
 import { buildSkillEntry, parseSkillUri, readSkillFileBytes, toResourceContent } from "./skillManifest.js";
 const MAX_FILE_BYTES = 256 * 1024;
 const SKILL_RESOURCE_PREFIX = "trellis://skills/";
+/**
+ * The Runtime process is spawned by the agent with the agent's own cwd —
+ * inside a repo carrying `.agents/`, skills served over the Runtime
+ * (zcode's delivery path) include the workspace layer, exactly like the
+ * file-delivered agents get their project copies (trellis-workspace-scope
+ * task 2.2). MCP upstream connections are deliberately NOT layered this
+ * way (design D6: workspace servers are direct, agent-owned) — this
+ * helper is used only here, never in the gateway's upstream resolution.
+ */
+function loadSkillCanonical(homeDir) {
+    return loadCanonicalSource({ homeDir, workspaceDir: findWorkspaceRoot(process.cwd()) });
+}
 const SEARCH_TOOL = {
     name: "trellis.skills.search",
     description: "Search in-scope Trellis skills by name or description, then read one selected skill on demand.",
@@ -131,7 +144,7 @@ export class SkillProvider {
     }
     /** `skills/list` — one entry per servable, in-scope skill. */
     listSkillEntries(context) {
-        return this.catalog(loadCanonicalSource(context.homeDir), context.agentId).map(({ entry }) => entry);
+        return this.catalog(loadSkillCanonical(context.homeDir), context.agentId).map(({ entry }) => entry);
     }
     /** `skills/get` — lookup by URI, independent of listing. Out-of-scope and
      * unknown URIs are indistinguishable by design. */
@@ -145,7 +158,7 @@ export class SkillProvider {
         return [SEARCH_TOOL, READ_TOOL, READ_FILE_TOOL];
     }
     async callTool(name, args, context) {
-        const canonical = loadCanonicalSource(context.homeDir);
+        const canonical = loadSkillCanonical(context.homeDir);
         const input = (args ?? {});
         if (name === SEARCH_TOOL.name)
             return this.search(canonical, context.agentId, input);
@@ -156,7 +169,7 @@ export class SkillProvider {
         return errorResult(`unknown skill provider tool "${name}"`);
     }
     listResources(context) {
-        const canonical = loadCanonicalSource(context.homeDir);
+        const canonical = loadSkillCanonical(context.homeDir);
         const legacy = canonical.skills
             .filter((skill) => hasSkillDocument(skill) && isInScope(context.agentId, skill.scope, canonical.managedAgents))
             .map((skill) => ({
@@ -181,7 +194,7 @@ export class SkillProvider {
         if (segments.length !== 2 || segments[1] !== "SKILL.md") {
             throw new Error(`unsupported skill resource URI "${uri.toString()}"`);
         }
-        const canonical = loadCanonicalSource(context.homeDir);
+        const canonical = loadSkillCanonical(context.homeDir);
         const skill = skillFor(canonical, context.agentId, segments[0]);
         if (!skill)
             throw new Error(`skill "${segments[0]}" is not available to ${context.agentId}`);
@@ -192,7 +205,7 @@ export class SkillProvider {
      * computed its digests — the two cannot disagree. */
     readConventionalResource(uri, context) {
         const parsed = parseSkillUri(uri);
-        const canonical = loadCanonicalSource(context.homeDir);
+        const canonical = loadSkillCanonical(context.homeDir);
         const skill = parsed ? skillFor(canonical, context.agentId, parsed.name) : undefined;
         const served = skill && parsed ? this.catalog(canonical, context.agentId).find(({ entry }) => entry.uri === `skill://${parsed.name}/SKILL.md`) : undefined;
         if (!parsed || !skill || !served || !served.entry.resources.some((file) => file.uri === uri)) {

package/dist/lib/workspace.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Workspace (project-level) canonical layer: discovery of the nearest
+ * `.agents/` directory and loading of its `config.json` / `AGENTS.md` /
+ * `skills/` into a `WorkspaceLayer` (openspec trellis-workspace-scope,
+ * design D1/D2). The shape follows the `.agents` Protocol draft's
+ * two-layer model; skills under `.agents/skills/` are additionally read
+ * natively by Codex, pi, and Kimi Code, so the canonical directory is
+ * itself the deliverable for those agents.
+ */
+import type { McpServerDef, SecretsPolicy, SkillRef } from "../core/types.js";
+export declare const WORKSPACE_DIR_NAME = ".agents";
+/** The only `config.json` schema version this implementation understands. */
+export declare const WORKSPACE_CONFIG_VERSION = 1;
+/**
+ * Walk ancestors of `startDir` upward; the first directory containing a
+ * `.agents/` directory is the workspace root. The user's home directory
+ * itself is never a workspace root (a `~/.agents/` global convention, if
+ * one ever exists, is a separate decision), and reaching the filesystem
+ * root yields `null` — pure global-only behavior.
+ */
+export declare function findWorkspaceRoot(startDir: string): string | null;
+export interface WorkspaceLayer {
+    /** Absolute workspace root (the directory containing `.agents/`). */
+    root: string;
+    /** Validated MCP servers from `config.json`, minus tombstones. */
+    servers: Record<string, McpServerDef>;
+    /** Server names declared with `enabled: false` — they disable a same-ID
+     * global entry and render nothing themselves. */
+    tombstones: string[];
+    /** Skills from `.agents/skills/<name>/`. */
+    skills: SkillRef[];
+    /** `.agents/AGENTS.md`, when present. */
+    instructionsFile?: string;
+    diagnostics: string[];
+}
+/** Load `<workspaceDir>/.agents/` into a `WorkspaceLayer`. Every file is
+ * optional; a present-but-invalid `config.json` is a hard error (never a
+ * silent misread), with the secrets boundary enforced against `policy`. */
+export declare function loadWorkspaceLayer(workspaceDir: string, policy: SecretsPolicy): WorkspaceLayer;