agent-trellis 0.14.1 → 0.15.1

package/dist/commands/sync.js

@@ -14,6 +14,9 @@ import { PiAdapter } from "../adapters/pi.js";
 import { KimiCodeAdapter } from "../adapters/kimi-code.js";
 import { ZcodeAdapter } from "../adapters/zcode.js";
 import { openBackupSession } from "../lib/backup.js";
+import { findWorkspaceRoot } from "../lib/workspace.js";
+import { applyWorkspaceFiles, planWorkspaceFiles } from "../lib/workspaceFiles.js";
+import { workspacePrecedenceWarnings } from "../lib/workspaceMcp.js";
 const ADAPTER_FACTORY = {
     "claude-code": (homeDir) => new ClaudeCodeAdapter(homeDir),
     codex: (homeDir) => new CodexAdapter(homeDir),
@@ -30,7 +33,11 @@ function buildAdapters(homeDir, managedAgents) {
 }
 export async function collectSyncReport(opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
-    const loaded = loadCanonicalSource(homeDir);
+    // Workspace participation is automatic inside a repo carrying `.agents/`
+    // and revocable via --global-only; outside any workspace (or when it
+    // resolves null) the load is byte-identical to before.
+    const workspaceDir = opts.globalOnly ? null : (opts.workspaceDir !== undefined ? opts.workspaceDir : findWorkspaceRoot(process.cwd()));
+    const loaded = loadCanonicalSource({ homeDir, workspaceDir });
     // A single override point, not two: every downstream read of "who's
     // managed" — the adapter list built here AND each adapter's own
     // in-scope filtering via `canonical.managedAgents` — must agree, or a
@@ -39,9 +46,10 @@ export async function collectSyncReport(opts = {}) {
     const canonical = opts.managedAgents ? { ...loaded, managedAgents: opts.managedAgents } : loaded;
     const reports = [];
     // Own session only when the caller didn't share one (trellis-backup-
-    // rollback D2) — dry-run never opens or writes one, there's nothing to
-    // record.
-    const ownSession = !opts.dryRun && !opts.backupSession ? openBackupSession(homeDir, "sync") : undefined;
+    // rollback D2) — dry-run/check never opens or writes one, there's
+    // nothing to record.
+    const writeMode = !opts.dryRun && !opts.check;
+    const ownSession = writeMode && !opts.backupSession ? openBackupSession(homeDir, "sync") : undefined;
     const backup = opts.backupSession ?? ownSession;
     for (const adapter of buildAdapters(homeDir, canonical.managedAgents)) {
         const probeResult = await adapter.probe();
@@ -53,6 +61,7 @@ export async function collectSyncReport(opts = {}) {
         // `trellis sync` never touches MCP, that's `trellis mcp sync`'s own
         // command, so exclude it unconditionally before any target filter.
         let items = (await adapter.plan(canonical)).filter((item) => item.kind !== "mcp");
+        let wsItems = planWorkspaceFiles(adapter.id, canonical);
         if (opts.target) {
             // CLI/option vocabulary is plural ("skills"/"instructions",
             // matching `trellis sync skills`); AdapterPlanItem.kind is singular
@@ -63,14 +72,18 @@ export async function collectSyncReport(opts = {}) {
             // sync" even with real create items pending).
             const kind = opts.target === "skills" ? "skill" : "instructions";
             items = items.filter((item) => item.kind === kind || (kind === "skill" && item.kind === "zcode-skill-control"));
+            wsItems = wsItems.filter((item) => item.kind === kind);
         }
-        if (!opts.dryRun) {
+        const allItems = [...items, ...wsItems];
+        if (writeMode) {
             await adapter.apply(items, backup);
+            applyWorkspaceFiles(adapter.id, canonical, wsItems, backup);
         }
-        reports.push({ agent: adapter.id, present: true, items });
+        const warnings = workspacePrecedenceWarnings(adapter.id, canonical);
+        reports.push({ agent: adapter.id, present: true, items: allItems, ...(warnings.length > 0 ? { warnings } : {}) });
     }
     ownSession?.finalize();
-    return { reports };
+    return { reports, ...(canonical.workspace ? { workspaceRoot: canonical.workspace.root } : {}) };
 }
 export async function runSync(opts = {}) {
     let report;
@@ -85,22 +98,34 @@ export async function runSync(opts = {}) {
         console.log(JSON.stringify(report, null, 2));
     }
     else {
-        printReport(report, opts.dryRun ?? false);
+        printReport(report, opts.dryRun ?? false, opts.check ?? false);
     }
     const hasConflict = report.reports.some((r) => r.items.some((i) => i.action === "conflict"));
+    if (opts.check) {
+        // Freshness gate: any pending write (create/remove) or conflict means
+        // the rendered artifacts are stale — exit non-zero, having written
+        // nothing.
+        const hasPending = report.reports.some((r) => r.items.some((i) => i.action !== "conflict"));
+        return { exitCode: hasPending || hasConflict ? 1 : 0 };
+    }
     return { exitCode: hasConflict ? 1 : 0 };
 }
 /** Exported so `onboard` prints a sync report identically to running
  * `sync` standalone, instead of a second, easily-drifting copy of this
  * formatting. */
-export function printReport(report, dryRun) {
+export function printReport(report, dryRun, check = false) {
     if (dryRun)
         console.log("[dry run]");
+    if (check)
+        console.log("[check]");
+    if (report.workspaceRoot) {
+        console.log(`Workspace layer: ${report.workspaceRoot} (.agents/)`);
+    }
     if (report.reports.length === 0) {
         console.log("No managed agents yet — run `trellis onboard` or list agent ids in ~/.trellis/managed.yaml.");
         return;
     }
-    for (const { agent, present, items } of report.reports) {
+    for (const { agent, present, items, warnings } of report.reports) {
         if (!present) {
             console.log(`—  ${agent} (not installed)`);
             continue;
@@ -110,12 +135,20 @@ export function printReport(report, dryRun) {
         const conflicts = items.filter((i) => i.action === "conflict");
         if (created.length === 0 && removed.length === 0 && conflicts.length === 0) {
             console.log(`✅ ${agent} — already in sync`);
-            continue;
         }
-        const icon = conflicts.length > 0 ? "⚠️ " : "✅";
-        console.log(`${icon} ${agent} — ${created.length} created, ${removed.length} removed, ${conflicts.length} conflict(s)`);
-        for (const item of [...created, ...removed, ...conflicts]) {
-            console.log(`   - [${item.action}] ${item.description}`);
+        else {
+            const icon = conflicts.length > 0 ? "⚠️ " : "✅";
+            console.log(`${icon} ${agent} — ${created.length} created, ${removed.length} removed, ${conflicts.length} conflict(s)`);
+            for (const item of [...created, ...removed, ...conflicts]) {
+                console.log(`   - [${item.action}]${item.layer === "workspace" ? " (workspace)" : ""} ${item.description}`);
+                // Same as mcp.ts's printer: a conflict's remediation IS the fix —
+                // never leave the user at "left untouched" with no next step.
+                if (item.remediation)
+                    console.log(`     → ${item.remediation}`);
+            }
+        }
+        for (const warning of warnings ?? []) {
+            console.log(`   ⚠ ${warning}`);
         }
     }
 }

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,40 +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`/
- * `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).
- */
-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;
-    client_name?: 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;
 } | {
@@ -140,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,99 +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?, 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(`mcp/servers.yaml: "${serverName}" auth has unrecognized key "${unknownKey}" — expected kind, owner, client_id, client_secret_env, client_name`);
-    }
-    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`);
-    }
-    if (client_name !== undefined && typeof client_name !== "string") {
-        throw new Error(`mcp/servers.yaml: "${serverName}" auth.client_name must be a string`);
-    }
-    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;
-    if (typeof client_name === "string")
-        out.clientName = client_name;
-    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 } : {}),
-                    ...(auth.clientName !== undefined ? { client_name: auth.clientName } : {}),
-                };
-    }
-    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");
 }
@@ -565,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.`);
@@ -609,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,
@@ -619,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

@@ -303,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
@@ -317,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/cliArgs.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared CLI flag readers. Every command historically rolled its own
+ * `argv.indexOf("--flag")` lookup — which silently ignores the equally
+ * common `--flag=value` form (real incident, found by the v0.15.0
+ * real-machine smoke test: `mcp add --args=-y,…` exited 0 with the args
+ * silently dropped from canonical). These helpers accept both forms, and
+ * `unknownFlags` catches typos instead of letting them vanish.
+ */
+/** Value of `--name <value>` or `--name=<value>`; undefined when absent.
+ * The space form returns the next token verbatim (even one starting with
+ * `-`), matching the historical `indexOf` behavior. First occurrence wins,
+ * same as `indexOf`. */
+export declare function flagValue(argv: readonly string[], name: string): string | undefined;
+/** `--*` tokens none of `known` claims. Non-flag tokens (positionals,
+ * values) are never flags; a `--name=value` token is classified by its
+ * name part, so a known flag in `=` form is not "unknown". */
+export declare function unknownFlags(argv: readonly string[], known: readonly string[]): string[];

package/dist/lib/cliArgs.js

@@ -0,0 +1,36 @@
+/**
+ * Shared CLI flag readers. Every command historically rolled its own
+ * `argv.indexOf("--flag")` lookup — which silently ignores the equally
+ * common `--flag=value` form (real incident, found by the v0.15.0
+ * real-machine smoke test: `mcp add --args=-y,…` exited 0 with the args
+ * silently dropped from canonical). These helpers accept both forms, and
+ * `unknownFlags` catches typos instead of letting them vanish.
+ */
+/** Value of `--name <value>` or `--name=<value>`; undefined when absent.
+ * The space form returns the next token verbatim (even one starting with
+ * `-`), matching the historical `indexOf` behavior. First occurrence wins,
+ * same as `indexOf`. */
+export function flagValue(argv, name) {
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === name)
+            return argv[i + 1];
+        if (token.startsWith(`${name}=`))
+            return token.slice(name.length + 1);
+    }
+    return undefined;
+}
+/** `--*` tokens none of `known` claims. Non-flag tokens (positionals,
+ * values) are never flags; a `--name=value` token is classified by its
+ * name part, so a known flag in `=` form is not "unknown". */
+export function unknownFlags(argv, known) {
+    const result = [];
+    for (const token of argv) {
+        if (!token.startsWith("--"))
+            continue;
+        const key = token.split("=", 1)[0];
+        if (!known.includes(key))
+            result.push(token);
+    }
+    return result;
+}

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 {};