agent-trellis 0.14.1 → 0.15.0

package/dist/adapters/claude-code.js

@@ -18,6 +18,7 @@ import * as claudeCodeProbe from "../probes/claude-code.js";
 import { applySymlinkPlan, planSymlinks } from "./symlinkPlan.js";
 import { applyJsonMcp, planJsonMcp, renderJsonServerEntry } from "./jsonMcp.js";
 import { loadMcpOwnership, ownedByAgent, recordOwned, forgetOwned, saveMcpOwnership } from "../lib/mcpOwnership.js";
+import { globalLayerMcp, globalLayerSkills } from "../lib/workspaceMerge.js";
 export class ClaudeCodeAdapter {
     homeDir;
     name = "Claude Code";
@@ -32,7 +33,7 @@ export class ClaudeCodeAdapter {
     async plan(canonical) {
         const canonicalRoot = dirname(canonical.instructionsFile);
         const skillsRoot = join(this.homeDir, ".claude", "skills");
-        const desiredSkills = canonical.skills
+        const desiredSkills = globalLayerSkills(canonical)
             .filter((skill) => usesNativeCapabilityDelivery(this.id, canonical.mcp) && isInScope(this.id, skill.scope, canonical.managedAgents))
             .map((skill) => ({ name: skill.name, target: skill.dir }));
         const skillItems = planSymlinks({
@@ -54,7 +55,7 @@ export class ClaudeCodeAdapter {
         const configPath = join(this.homeDir, ".claude.json");
         const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
         const ownership = ownedByAgent(loadMcpOwnership(this.homeDir), this.id);
-        return planJsonMcp({ configPath, parsed, mcp: canonical.mcp, agentId: this.id, managedAgents: canonical.managedAgents, policy: canonical.secretsPolicy, ownership });
+        return planJsonMcp({ configPath, parsed, mcp: globalLayerMcp(canonical), agentId: this.id, managedAgents: canonical.managedAgents, policy: canonical.secretsPolicy, ownership });
     }
     async apply(plan, backup) {
         await applySymlinkPlan(plan.filter((item) => item.kind !== "mcp"), backup);
@@ -83,7 +84,7 @@ export class ClaudeCodeAdapter {
             return { ok: false, mismatches: ["claude-code is not present on this machine"] };
         }
         const mismatches = [];
-        const desiredNames = new Set(canonical.skills.filter((s) => usesNativeCapabilityDelivery(this.id, canonical.mcp) && isInScope(this.id, s.scope, canonical.managedAgents)).map((s) => s.name));
+        const desiredNames = new Set(globalLayerSkills(canonical).filter((s) => usesNativeCapabilityDelivery(this.id, canonical.mcp) && isInScope(this.id, s.scope, canonical.managedAgents)).map((s) => s.name));
         const actualSkills = new Set(snapshot.skillRoots.flatMap((root) => root.skills).map((s) => s.name));
         for (const name of desiredNames) {
             if (!actualSkills.has(name)) {

package/dist/adapters/codex.js

@@ -26,6 +26,7 @@ import { applySymlinkPlan, planSymlinks } from "./symlinkPlan.js";
 import { resolveMcpPlan } from "./mcpPlan.js";
 import { currentServerSectionText, removeSection, renderServerSection, upsertSection } from "../lib/tomlSection.js";
 import { loadMcpOwnership, ownedByAgent, recordOwned, forgetOwned, saveMcpOwnership } from "../lib/mcpOwnership.js";
+import { globalLayerMcp, globalLayerSkills } from "../lib/workspaceMerge.js";
 export class CodexAdapter {
     homeDir;
     name = "Codex";
@@ -40,7 +41,7 @@ export class CodexAdapter {
     async plan(canonical) {
         const canonicalRoot = dirname(canonical.instructionsFile);
         const skillsRoot = join(this.homeDir, ".agents", "skills");
-        const desiredSkills = canonical.skills
+        const desiredSkills = globalLayerSkills(canonical)
             .filter((skill) => usesNativeCapabilityDelivery(this.id, canonical.mcp) && isInScope(this.id, skill.scope, canonical.managedAgents))
             .map((skill) => ({ name: skill.name, target: skill.dir }));
         const skillItems = planSymlinks({
@@ -67,7 +68,7 @@ export class CodexAdapter {
     planMcp(canonical) {
         const configTomlPath = join(this.homeDir, ".codex", "config.toml");
         const content = existsSync(configTomlPath) ? readFileSync(configTomlPath, "utf-8") : "";
-        const { desired, conflicts } = resolveMcpPlan(this.id, canonical.mcp, canonical.managedAgents, canonical.secretsPolicy);
+        const { desired, conflicts } = resolveMcpPlan(this.id, globalLayerMcp(canonical), canonical.managedAgents, canonical.secretsPolicy);
         const items = [];
         for (const { name, def } of desired) {
             const current = currentServerSectionText(content, name);
@@ -137,7 +138,7 @@ export class CodexAdapter {
             return { ok: false, mismatches: ["codex is not present on this machine"] };
         }
         const mismatches = [];
-        const desiredNames = new Set(canonical.skills.filter((s) => usesNativeCapabilityDelivery(this.id, canonical.mcp) && isInScope(this.id, s.scope, canonical.managedAgents)).map((s) => s.name));
+        const desiredNames = new Set(globalLayerSkills(canonical).filter((s) => usesNativeCapabilityDelivery(this.id, canonical.mcp) && isInScope(this.id, s.scope, canonical.managedAgents)).map((s) => s.name));
         const actualSkills = new Set(snapshot.skillRoots.flatMap((root) => root.skills).map((s) => s.name));
         for (const name of desiredNames) {
             if (!actualSkills.has(name)) {

package/dist/adapters/kimi-code.js

@@ -16,6 +16,7 @@ import { applyJsonMcp, planJsonMcp, renderJsonServerEntry } from "./jsonMcp.js";
 import { RUNTIME_COMMAND, RUNTIME_ENTRY_NAME } from "./mcpPlan.js";
 import { applySymlinkPlan, planSymlinks } from "./symlinkPlan.js";
 import { loadMcpOwnership, ownedByAgent, recordOwned, forgetOwned, saveMcpOwnership } from "../lib/mcpOwnership.js";
+import { globalLayerMcp, globalLayerSkills } from "../lib/workspaceMerge.js";
 const KIMI_RUNTIME_STARTUP_TIMEOUT_MS = 30_000;
 function renderKimiServerEntry(def, name) {
     const entry = renderJsonServerEntry(def);
@@ -46,7 +47,7 @@ export class KimiCodeAdapter {
         items.push(...planSymlinks({
             rootDir: join(root, "skills"),
             desired: native
-                ? canonical.skills
+                ? globalLayerSkills(canonical)
                     .filter((skill) => isInScope(this.id, skill.scope, canonical.managedAgents))
                     .map((skill) => ({ name: skill.name, target: skill.dir }))
                 : [],
@@ -65,7 +66,7 @@ export class KimiCodeAdapter {
         items.push(...planJsonMcp({
             configPath,
             parsed,
-            mcp: canonical.mcp,
+            mcp: globalLayerMcp(canonical),
             agentId: this.id,
             managedAgents: canonical.managedAgents,
             policy: canonical.secretsPolicy,
@@ -96,7 +97,7 @@ export class KimiCodeAdapter {
         const snapshot = await kimiProbe.probe(this.homeDir);
         if (!snapshot.present)
             return { ok: false, mismatches: ["kimi-code is not present on this machine"] };
-        const desired = new Set(canonical.skills.filter((skill) => usesNativeCapabilityDelivery(this.id, canonical.mcp) && isInScope(this.id, skill.scope, canonical.managedAgents)).map((skill) => skill.name));
+        const desired = new Set(globalLayerSkills(canonical).filter((skill) => usesNativeCapabilityDelivery(this.id, canonical.mcp) && isInScope(this.id, skill.scope, canonical.managedAgents)).map((skill) => skill.name));
         const actual = new Set(snapshot.skillRoots.flatMap((root) => root.skills).filter((skill) => skill.dir.includes("/.kimi-code/skills/")).map((skill) => skill.name));
         const mismatches = [
             ...[...desired].filter((name) => !actual.has(name)).map((name) => `skill "${name}" is missing on Kimi Code`),

package/dist/adapters/kiro.js

@@ -26,6 +26,7 @@ import { applyJsonMcp, planJsonMcp, renderJsonServerEntry } from "./jsonMcp.js";
 import { resolveMcpPlan } from "./mcpPlan.js";
 import { declaredEnvNames } from "../lib/envVarNames.js";
 import { loadMcpOwnership, ownedByAgent, recordOwned, forgetOwned, saveMcpOwnership } from "../lib/mcpOwnership.js";
+import { globalLayerMcp, globalLayerSkills } from "../lib/workspaceMerge.js";
 /** VS-Code-family global settings path. macOS only — see
  * trellis-kiro-approved-env-vars proposal.md Non-Goals: Linux/Windows
  * equivalents are the well-known convention but unverified against a
@@ -48,7 +49,7 @@ export class KiroAdapter {
     async plan(canonical) {
         const canonicalRoot = dirname(canonical.instructionsFile);
         const skillsRoot = join(this.homeDir, ".kiro", "skills");
-        const desiredSkills = canonical.skills
+        const desiredSkills = globalLayerSkills(canonical)
             .filter((skill) => usesNativeCapabilityDelivery(this.id, canonical.mcp) && isInScope(this.id, skill.scope, canonical.managedAgents))
             .map((skill) => ({ name: skill.name, target: skill.dir }));
         const skillItems = planSymlinks({
@@ -71,13 +72,13 @@ export class KiroAdapter {
         const configPath = join(this.homeDir, ".kiro", "settings", "mcp.json");
         const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
         const ownership = ownedByAgent(loadMcpOwnership(this.homeDir), this.id);
-        return planJsonMcp({ configPath, parsed, mcp: canonical.mcp, agentId: this.id, managedAgents: canonical.managedAgents, policy: canonical.secretsPolicy, ownership });
+        return planJsonMcp({ configPath, parsed, mcp: globalLayerMcp(canonical), agentId: this.id, managedAgents: canonical.managedAgents, policy: canonical.secretsPolicy, ownership });
     }
     /** Names come from `resolveMcpPlan`, not a raw scan of `canonical.mcp.servers`
      * (design.md D2) — a server scoped away from Kiro, or refused for a
      * known_host_injected collision, never contributes a name here either. */
     desiredApprovedEnvVars(canonical) {
-        const { desired } = resolveMcpPlan(this.id, canonical.mcp, canonical.managedAgents, canonical.secretsPolicy);
+        const { desired } = resolveMcpPlan(this.id, globalLayerMcp(canonical), canonical.managedAgents, canonical.secretsPolicy);
         const names = new Set();
         for (const { def } of desired) {
             for (const name of declaredEnvNames(def))
@@ -162,7 +163,7 @@ export class KiroAdapter {
             return { ok: false, mismatches: ["kiro is not present on this machine"] };
         }
         const mismatches = [];
-        const desiredNames = new Set(canonical.skills.filter((s) => usesNativeCapabilityDelivery(this.id, canonical.mcp) && isInScope(this.id, s.scope, canonical.managedAgents)).map((s) => s.name));
+        const desiredNames = new Set(globalLayerSkills(canonical).filter((s) => usesNativeCapabilityDelivery(this.id, canonical.mcp) && isInScope(this.id, s.scope, canonical.managedAgents)).map((s) => s.name));
         const actualSkills = new Set(snapshot.skillRoots.flatMap((root) => root.skills).map((s) => s.name));
         for (const name of desiredNames) {
             if (!actualSkills.has(name)) {

package/dist/adapters/pi.js

@@ -36,6 +36,7 @@ import { applyJsonMcp, planJsonMcp } from "./jsonMcp.js";
 import { piRenderer, supportsNativeMcp } from "./piMcp.js";
 import { loadMcpOwnership, ownedByAgent, recordOwned, forgetOwned, saveMcpOwnership } from "../lib/mcpOwnership.js";
 import { currentLinkTarget } from "../lib/backup.js";
+import { globalLayerMcp, globalLayerSkills } from "../lib/workspaceMerge.js";
 const BRIDGE_SYMLINK_NAME = "trellis-mcp-bridge.js";
 /**
  * A source-checkout bridge can survive a switch to the packaged CLI. Adopt it
@@ -97,7 +98,7 @@ export class PiAdapter {
     async plan(canonical) {
         const canonicalRoot = dirname(canonical.instructionsFile);
         const agentDir = join(this.homeDir, ".pi", "agent");
-        const desiredSkills = canonical.skills
+        const desiredSkills = globalLayerSkills(canonical)
             .filter((skill) => usesNativeCapabilityDelivery(this.id, canonical.mcp) && isInScope(this.id, skill.scope, canonical.managedAgents))
             .map((skill) => ({ name: skill.name, target: skill.dir }));
         const skillItems = planSymlinks({
@@ -146,7 +147,7 @@ export class PiAdapter {
         const items = planJsonMcp({
             configPath,
             parsed,
-            mcp: canonical.mcp,
+            mcp: globalLayerMcp(canonical),
             agentId: this.id,
             managedAgents: canonical.managedAgents,
             policy: canonical.secretsPolicy,
@@ -233,7 +234,7 @@ export class PiAdapter {
             return { ok: false, mismatches: ["pi is not present on this machine"] };
         }
         const mismatches = [];
-        const desiredNames = new Set(canonical.skills.filter((s) => usesNativeCapabilityDelivery(this.id, canonical.mcp) && isInScope(this.id, s.scope, canonical.managedAgents)).map((s) => s.name));
+        const desiredNames = new Set(globalLayerSkills(canonical).filter((s) => usesNativeCapabilityDelivery(this.id, canonical.mcp) && isInScope(this.id, s.scope, canonical.managedAgents)).map((s) => s.name));
         const actualSkills = new Set(snapshot.skillRoots.flatMap((root) => root.skills).map((s) => s.name));
         for (const name of desiredNames) {
             if (!actualSkills.has(name)) {

package/dist/adapters/zcode.d.ts

@@ -6,8 +6,18 @@
  * native Skill switches through a ledger-backed, reversible config change.
  */
 import type { AdapterPlanItem, AdapterProbeResult, AdapterVerifyResult, TrellisAdapter } from "../core/adapter.js";
-import type { CanonicalSource } from "../core/types.js";
+import type { CanonicalSource, McpConfig, SecretsPolicy } from "../core/types.js";
 import type { BackupSession } from "../lib/backup.js";
+type JsonRecord = Record<string, unknown>;
+export declare function planZcodeMcp(opts: {
+    configPath: string;
+    parsed: JsonRecord | undefined;
+    mcp: McpConfig;
+    managedAgents: readonly import("../core/types.js").AgentId[];
+    policy: SecretsPolicy;
+    ownership: JsonRecord;
+}): AdapterPlanItem[];
+export declare function applyZcodeMcp(parsed: JsonRecord | undefined, items: readonly AdapterPlanItem[]): JsonRecord;
 export declare class ZcodeAdapter implements TrellisAdapter {
     private readonly homeDir;
     private readonly env;
@@ -19,3 +29,4 @@ export declare class ZcodeAdapter implements TrellisAdapter {
     apply(plan: AdapterPlanItem[], backup: BackupSession): Promise<void>;
     verify(canonical: CanonicalSource): Promise<AdapterVerifyResult>;
 }
+export {};

package/dist/adapters/zcode.js

@@ -17,6 +17,7 @@ import { deepEqual } from "../lib/deepEqual.js";
 import { forgetOwned, loadMcpOwnership, ownedByAgent, recordOwned, saveMcpOwnership } from "../lib/mcpOwnership.js";
 import { forgetZcodeSettingsOwnership, loadZcodeSettingsOwnership, saveZcodeSettingsOwnership } from "../lib/zcodeOwnership.js";
 import * as zcodeProbe from "../probes/zcode.js";
+import { globalLayerMcp, globalLayerSkills } from "../lib/workspaceMerge.js";
 function readConfig(path) {
     if (!existsSync(path))
         return undefined;
@@ -28,7 +29,7 @@ function record(value) {
 function zcodeServers(parsed) {
     return record(record(parsed?.mcp).servers);
 }
-function planZcodeMcp(opts) {
+export function planZcodeMcp(opts) {
     const { desired, conflicts } = resolveMcpPlan("zcode", opts.mcp, opts.managedAgents, opts.policy);
     const existing = zcodeServers(opts.parsed);
     const items = [];
@@ -65,7 +66,7 @@ function planZcodeMcp(opts) {
     }
     return items;
 }
-function applyZcodeMcp(parsed, items) {
+export function applyZcodeMcp(parsed, items) {
     const base = parsed ?? {};
     const mcp = record(base.mcp);
     const servers = { ...record(mcp.servers) };
@@ -124,7 +125,7 @@ export class ZcodeAdapter {
         items.push(...planSymlinks({
             rootDir: join(this.homeDir, ".zcode", "skills"),
             desired: usesNativeCapabilityDelivery(this.id, canonical.mcp)
-                ? canonical.skills.filter((skill) => isInScope(this.id, skill.scope, canonical.managedAgents)).map((skill) => ({ name: skill.name, target: skill.dir }))
+                ? globalLayerSkills(canonical).filter((skill) => isInScope(this.id, skill.scope, canonical.managedAgents)).map((skill) => ({ name: skill.name, target: skill.dir }))
                 : [],
             canonicalRoot: join(canonicalRoot, "skills"),
             kind: "skill",
@@ -138,7 +139,7 @@ export class ZcodeAdapter {
         items.push(...planZcodeMcp({
             configPath: profile.configPath,
             parsed,
-            mcp: canonical.mcp,
+            mcp: globalLayerMcp(canonical),
             managedAgents: canonical.managedAgents,
             policy: canonical.secretsPolicy,
             ownership: ownedByAgent(loadMcpOwnership(this.homeDir), this.id),
@@ -206,7 +207,7 @@ export class ZcodeAdapter {
         if (!profile)
             return { ok: false, mismatches: ["zcode profile cannot be selected"] };
         const mismatches = [];
-        const desiredNativeSkills = canonical.skills
+        const desiredNativeSkills = globalLayerSkills(canonical)
             .filter((skill) => usesNativeCapabilityDelivery(this.id, canonical.mcp) && isInScope(this.id, skill.scope, canonical.managedAgents))
             .map((skill) => skill.name);
         const actualNativeSkills = new Set(snapshot.skillRoots.filter((root) => root.path === join(this.homeDir, ".zcode", "skills")).flatMap((root) => root.skills.map((skill) => skill.name)));
@@ -216,7 +217,7 @@ export class ZcodeAdapter {
         const expectedMcp = planZcodeMcp({
             configPath: profile.configPath,
             parsed: readConfig(profile.configPath),
-            mcp: canonical.mcp,
+            mcp: globalLayerMcp(canonical),
             managedAgents: canonical.managedAgents,
             policy: canonical.secretsPolicy,
             ownership: ownedByAgent(loadMcpOwnership(this.homeDir), this.id),

package/dist/cli.js

@@ -7,6 +7,7 @@
 import { runDoctor } from "./commands/doctor.js";
 import { runInit } from "./commands/init.js";
 import { runMigrate } from "./commands/migrate.js";
+import { runMigrateWorkspace } from "./commands/migrateWorkspace.js";
 import { runOnboard } from "./commands/onboard.js";
 import { runSync } from "./commands/sync.js";
 import { runMcpSync, runMcpList, runMcpAdd, runMcpRemove, runMcpSetAuth, runMcpScope, parseMcpAddArgs, parseMcpSetArgs } from "./commands/mcp.js";
@@ -74,6 +75,7 @@ Commands:
               (never overwrites an existing file — fills in only what's
               missing) and prints which agents are present
               --json    machine-readable output, no report text
+              --workspace  scaffold .agents/ in the current project instead
   migrate --from <agent>
             Import an existing agent's real skills/instructions/MCP/memory
             servers into canonical source (claude-code | codex | kiro |
@@ -84,6 +86,18 @@ Commands:
                                     restrict to one category
               --dry-run    preview the plan, write nothing
               --json       machine-readable output, no report text
+  migrate --workspace
+            Absorb the repo's existing project-level agent config (all six
+            agents' MCP files + root AGENTS.md) into .agents/, then
+            re-render. Plaintext secrets are intercepted into the global
+            secret store as \${VAR} references, never written under
+            .agents/; *.local.* files are listed, never read.
+              --choose name=agentId   pick a side for a cross-agent conflict
+              --dedup drop|override   identical-to-global entries: skip
+                                      (default) or import as an intentional
+                                      shadow
+              --dry-run    preview the plan, write nothing
+              --json       machine-readable output, no report text
   doctor    Scan Claude Code / Codex / Kiro / pi for drift
               --json         machine-readable output, no table text
               --probe-mcp    also handshake every configured MCP server
@@ -123,6 +137,7 @@ Commands:
             no overwrite): --command <cmd> [--args a,b] (stdio) or
             --url <url> (http/sse); [--headers k=v,...]
             [--auth oauth] [--env NAME,...] [--static-env k=v,...] [--agents id,...]
+            [--workspace]  write to .agents/config.json instead of servers.yaml
             [--enabled true|false]
             --dry-run    preview the plan, write nothing
             --json       machine-readable output, no report text
@@ -186,6 +201,7 @@ Commands:
   skill add <name> --from <path>
             Import a real skill directory into canonical (refuses on
               an existing name with different content, no overwrite)
+              --workspace  copy into .agents/skills/ instead of canonical
               --dry-run    preview the plan, write nothing
               --json       machine-readable output, no report text
   skill remove <name>
@@ -341,11 +357,28 @@ async function main(argv) {
         return;
     }
     if (command === "init") {
-        const { exitCode } = await runInit({ json: rest.includes("--json") });
+        const { exitCode } = await runInit({ json: rest.includes("--json"), workspace: rest.includes("--workspace") });
         process.exitCode = exitCode;
         return;
     }
     if (command === "migrate") {
+        if (rest.includes("--workspace")) {
+            // Repeated `--choose name=agentId` flags collect into an array.
+            const choose = [];
+            for (let i = 0; i < rest.length; i++) {
+                if (rest[i] === "--choose" && rest[i + 1] !== undefined)
+                    choose.push(rest[i + 1]);
+            }
+            const dedupIndex = rest.indexOf("--dedup");
+            const { exitCode } = await runMigrateWorkspace({
+                choose,
+                dedup: dedupIndex >= 0 ? rest[dedupIndex + 1] : undefined,
+                dryRun: rest.includes("--dry-run"),
+                json: rest.includes("--json"),
+            });
+            process.exitCode = exitCode;
+            return;
+        }
         const fromIndex = rest.indexOf("--from");
         const from = fromIndex >= 0 ? rest[fromIndex + 1] : undefined;
         const onlyIndex = rest.indexOf("--only");
@@ -383,7 +416,7 @@ async function main(argv) {
             process.exitCode = 1;
             return;
         }
-        const { exitCode } = await runSync({ target, json: rest.includes("--json"), dryRun: rest.includes("--dry-run") });
+        const { exitCode } = await runSync({ target, json: rest.includes("--json"), dryRun: rest.includes("--dry-run"), check: rest.includes("--check"), globalOnly: rest.includes("--global-only") });
         process.exitCode = exitCode;
         return;
     }
@@ -443,7 +476,7 @@ async function main(argv) {
         const json = mcpRest.includes("--json");
         const dryRun = mcpRest.includes("--dry-run");
         if (subcommand === "sync") {
-            const { exitCode } = await runMcpSync({ json, dryRun });
+            const { exitCode } = await runMcpSync({ json, dryRun, check: mcpRest.includes("--check"), globalOnly: mcpRest.includes("--global-only") });
             process.exitCode = exitCode;
             return;
         }
@@ -453,7 +486,7 @@ async function main(argv) {
         }
         if (subcommand === "add") {
             const [name] = mcpRest;
-            process.exitCode = (await runMcpAdd(name, parseMcpAddArgs(mcpRest), { json, dryRun })).exitCode;
+            process.exitCode = (await runMcpAdd(name, parseMcpAddArgs(mcpRest), { json, dryRun, workspace: mcpRest.includes("--workspace") })).exitCode;
             return;
         }
         if (subcommand === "import") {
@@ -518,7 +551,7 @@ async function main(argv) {
                 process.exitCode = 1;
                 return;
             }
-            process.exitCode = (await runSkillAdd(name, from, { json, dryRun })).exitCode;
+            process.exitCode = (await runSkillAdd(name, from, { json, dryRun, workspace: skillRest.includes("--workspace") })).exitCode;
             return;
         }
         if (subcommand === "remove") {

package/dist/commands/doctor.d.ts

@@ -6,6 +6,7 @@
  */
 import { loadCanonicalSource } from "../core/canonical.js";
 import type { AgentId, AgentSnapshot, CanonicalSource } from "../core/types.js";
+import { type WorkspaceDoctorSection } from "../lib/workspaceDoctor.js";
 /**
  * Interim default until P1 wires this from `.trellis/mcp/servers.yaml`'s
  * real `known_host_injected` field (P0 has no canonical source at all —
@@ -47,6 +48,10 @@ export interface RunDoctorOptions {
     /** Defaults to the real `~`; overridable for tests only — same seam
      * every other Trellis entry point uses. */
     homeDir?: string;
+    /** Explicit workspace root for layer attribution — the test/sandbox
+     * seam. CLI discovery walks up from cwd via `findWorkspaceRoot`;
+     * null = no workspace layer. */
+    workspaceDir?: string | null;
 }
 export interface OAuthHealthEntry {
     server: string;
@@ -61,6 +66,9 @@ export interface DoctorReport {
      * server is OAuth-classified. Read-only by construction
      * (trellis-mcp-oauth-renew design.md D4). */
     oauth?: OAuthHealthEntry[];
+    /** Per-entry layer attribution when a `.agents/` workspace layer
+     * participated (trellis-workspace-scope task 3.5). */
+    workspace?: WorkspaceDoctorSection;
 }
 /** Exported so tests can assert on this resolution directly, without
  * routing through real per-agent probes `runDoctor` also runs. */
@@ -76,7 +84,7 @@ export declare function runDoctor(opts?: RunDoctorOptions): Promise<{
  * existing call site (which now passes `opts.homeDir`, itself normally
  * `undefined`) is unaffected.
  */
-export declare function collectDoctorReport(homeDir?: string, knownHostInjected?: readonly string[], probeMcp?: boolean): Promise<DoctorReport>;
+export declare function collectDoctorReport(homeDir?: string, knownHostInjected?: readonly string[], probeMcp?: boolean, workspaceDir?: string | null): Promise<DoctorReport>;
 /**
  * Read-only OAuth credential health (trellis-mcp-oauth-renew design.md
  * D4): classified from the stored token file alone — no token endpoint,

package/dist/commands/doctor.js

@@ -16,6 +16,8 @@ import { GATEWAY_ENTRY_NAME, RUNTIME_ENTRY_NAME, resolveMcpPlan } from "../adapt
 import { ALL_AGENTS, isOAuthAuth, oauthOwner } from "../core/types.js";
 import { classifyStoredToken, remediationFor } from "../lib/oauth/renew.js";
 import { readToken } from "../lib/oauth/store.js";
+import { findWorkspaceRoot } from "../lib/workspace.js";
+import { collectWorkspaceDoctorSection } from "../lib/workspaceDoctor.js";
 /**
  * Interim default until P1 wires this from `.trellis/mcp/servers.yaml`'s
  * real `known_host_injected` field (P0 has no canonical source at all —
@@ -58,7 +60,8 @@ export function resolveKnownHostInjected(opts) {
     }
 }
 export async function runDoctor(opts = {}) {
-    const report = await collectDoctorReport(opts.homeDir, resolveKnownHostInjected(opts), opts.probeMcp);
+    const workspaceDir = opts.workspaceDir !== undefined ? opts.workspaceDir : findWorkspaceRoot(process.cwd());
+    const report = await collectDoctorReport(opts.homeDir, resolveKnownHostInjected(opts), opts.probeMcp, workspaceDir);
     const exitCode = report.findings.some((f) => EXIT_NONZERO_KINDS.has(f.kind)) ? 1 : 0;
     if (opts.json) {
         console.log(JSON.stringify(report, null, 2));
@@ -76,7 +79,7 @@ export async function runDoctor(opts = {}) {
  * existing call site (which now passes `opts.homeDir`, itself normally
  * `undefined`) is unaffected.
  */
-export async function collectDoctorReport(homeDir = homedir(), knownHostInjected = DEFAULT_KNOWN_HOST_INJECTED, probeMcp = false) {
+export async function collectDoctorReport(homeDir = homedir(), knownHostInjected = DEFAULT_KNOWN_HOST_INJECTED, probeMcp = false, workspaceDir) {
     const probeList = [
         { agent: "claude-code", run: () => claudeCodeProbe.probe(homeDir, { probeMcp }) },
         { agent: "codex", run: () => codexProbe.probe(homeDir, { probeMcp }) },
@@ -103,15 +106,24 @@ export async function collectDoctorReport(homeDir = homedir(), knownHostInjected
     });
     let canonical;
     try {
-        canonical = loadCanonicalSource(homeDir);
+        // Workspace-merged when a layer is in play — doctor's attribution is
+        // the merged view, and a broken workspace config degrades doctor to
+        // the global-only view rather than failing the whole scan.
+        canonical = loadCanonicalSource({ homeDir, workspaceDir: workspaceDir ?? null });
     }
     catch {
-        // Doctor remains useful as a standalone cross-agent scanner when
-        // canonical has not been initialized yet.
+        try {
+            canonical = loadCanonicalSource(homeDir);
+        }
+        catch {
+            // Doctor remains useful as a standalone cross-agent scanner when
+            // canonical has not been initialized yet.
+        }
     }
+    const workspace = canonical?.workspace ? collectWorkspaceDoctorSection(canonical) : undefined;
     const oauth = canonical ? collectOAuthHealth(homeDir, canonical) : [];
     findings.push(...detectDuplication(snapshots), ...detectCollisions(snapshots, knownHostInjected), ...detectCrossAgentDrift(snapshots), ...detectCaseMismatches(snapshots), ...detectParseDiagnostics(snapshots), ...(canonical ? detectRuntimeDrift(snapshots, canonical) : []), ...detectMcpUnreachable(snapshots), ...oauth.flatMap((entry) => (entry.status === "valid" ? [] : [oauthFinding(entry)])));
-    return { snapshots, findings, ...(oauth.length > 0 ? { oauth } : {}) };
+    return { snapshots, findings, ...(oauth.length > 0 ? { oauth } : {}), ...(workspace ? { workspace } : {}) };
 }
 /**
  * Read-only OAuth credential health (trellis-mcp-oauth-renew design.md
@@ -362,4 +374,29 @@ export function printReport(report) {
             console.log(`⚠️  ${finding.message}`);
         }
     }
+    if (report.workspace) {
+        const ws = report.workspace;
+        console.log(`\nWorkspace layer: ${ws.root} (.agents/)`);
+        for (const entry of ws.mcp) {
+            console.log(`   mcp ${entry.name} — ${entry.layer}`);
+        }
+        for (const entry of ws.skills) {
+            console.log(`   skill ${entry.name} — ${entry.layer}`);
+        }
+        if (ws.shadowed.length > 0) {
+            console.log(`   shadowed by workspace: ${ws.shadowed.join(", ")}`);
+        }
+        if (ws.tombstoned.length > 0) {
+            console.log(`   tombstoned (disabled for this project): ${ws.tombstoned.join(", ")}`);
+        }
+        for (const ref of ws.unresolvedVars) {
+            console.log(`   ⚠ ${ref.server} ${ref.field}: \${${ref.name}} does not resolve under the current secrets policy`);
+        }
+        for (const hint of ws.unmigrated) {
+            console.log(`   ⚠ ${hint.path} holds ${hint.entries.length} entr${hint.entries.length === 1 ? "y" : "ies"} Trellis didn't render (${hint.entries.join(", ")}) — run \`trellis migrate --workspace\``);
+        }
+        for (const warning of ws.precedenceWarnings) {
+            console.log(`   ⚠ ${warning}`);
+        }
+    }
 }

package/dist/commands/init.d.ts

@@ -12,6 +12,12 @@ export interface RunInitOptions {
     /** Defaults to the real `~`; overridable for tests only — same seam
      * every other Trellis entry point uses. */
     homeDir?: string;
+    /** `--workspace`: scaffold `.agents/` in the project instead of the
+     * global `~/.trellis/` (trellis-workspace-scope task 3.3). */
+    workspace?: boolean;
+    /** Workspace scaffold target — the test/sandbox seam. CLI discovery is
+     * simply `process.cwd()`. */
+    workspaceDir?: string;
 }
 export interface InitFileResult {
     path: string;

package/dist/commands/init.js

@@ -18,6 +18,7 @@ import * as piProbe from "../probes/pi.js";
 import * as kimiCodeProbe from "../probes/kimi-code.js";
 import * as zcodeProbe from "../probes/zcode.js";
 import { ALL_AGENTS } from "../core/types.js";
+import { scaffoldWorkspace } from "../lib/workspaceConfig.js";
 /** Exported so `migrate` can byte-compare canonical `agents.md` against
  * this exact string (design.md D3, trellis-cli-migrate) rather than
  * retyping an equivalent one that could silently drift from this. */
@@ -148,6 +149,29 @@ export async function collectInitReport(homeDir = homedir(), options = {}) {
     return { files, agents };
 }
 export async function runInit(opts = {}) {
+    if (opts.workspace) {
+        const dir = opts.workspaceDir ?? process.cwd();
+        const files = scaffoldWorkspace(dir);
+        if (opts.json) {
+            console.log(JSON.stringify({ workspace: dir, files }, null, 2));
+        }
+        else {
+            const created = files.filter((f) => f.action === "create");
+            if (created.length === 0) {
+                console.log(`${dir}/.agents already fully initialized — nothing to create.`);
+            }
+            else {
+                console.log(`Created ${created.length} file(s) under ${dir}/.agents:`);
+                for (const f of created)
+                    console.log(`  - ${f.path}`);
+            }
+            for (const f of files.filter((f) => f.action === "already-present")) {
+                console.log(`  - ${f.path} (already present, left untouched)`);
+            }
+            console.log("\nNext: commit .agents/ to share it, then `trellis sync` renders per-agent project files.");
+        }
+        return { exitCode: 0 };
+    }
     const homeDir = opts.homeDir ?? homedir();
     const report = await collectInitReport(homeDir);
     if (opts.json) {

package/dist/commands/mcp.d.ts

@@ -33,14 +33,23 @@ export interface RunMcpSyncOptions {
     /** Onboard-only seam — see RunSyncOptions.backupSession. Never a CLI
      * flag. */
     backupSession?: BackupSession;
+    /** Force global-only behavior even inside a workspace (`--global-only`). */
+    globalOnly?: boolean;
+    /** Explicit workspace root — the test/sandbox seam (see RunSyncOptions). */
+    workspaceDir?: string | null;
+    /** `--check`: plan only, write nothing, exit non-zero on any stale or
+     * missing rendered artifact (trellis-workspace-scope design D7). */
+    check?: boolean;
 }
 export interface AgentMcpSyncReport {
     agent: AgentId;
     present: boolean;
     items: AdapterPlanItem[];
+    warnings?: string[];
 }
 export interface McpSyncReport {
     reports: AgentMcpSyncReport[];
+    workspaceRoot?: string;
 }
 export declare function collectMcpSyncReport(opts?: RunMcpSyncOptions): Promise<McpSyncReport>;
 export declare function runMcpSync(opts?: RunMcpSyncOptions): Promise<{
@@ -49,7 +58,7 @@ export declare function runMcpSync(opts?: RunMcpSyncOptions): Promise<{
 /** Exported so `onboard` prints an mcp-sync report identically to running
  * `mcp sync` standalone, instead of a second, easily-drifting copy of this
  * formatting. */
-export declare function printReport(report: McpSyncReport, dryRun: boolean): void;
+export declare function printReport(report: McpSyncReport, dryRun: boolean, check?: boolean): void;
 export interface McpListEntry {
     name: string;
     transport: Transport;
@@ -147,8 +156,30 @@ export interface McpAddPlan {
  * write failure — design.md's open question, resolved in favor of
  * refusing early with a specific reason. No `--force`: an existing name
  * always refuses, ever (design.md D4).
+ *
+ * Split into two steps so `mcp add --workspace` reuses the identical
+ * flag validation/def construction and only swaps which file's existing
+ * entries it conflicts against (trellis-workspace-scope task 3.4):
+ * `buildMcpAddDef` is the pure part, `collectMcpAddPlan` adds the
+ * global-canonical existence check.
  */
+export declare function buildMcpAddDef(name: string | undefined, raw: McpAddRawArgs): {
+    ok: true;
+    name: string;
+    def: McpServerDef;
+} | {
+    ok: false;
+    plan: McpAddPlan;
+};
 export declare function collectMcpAddPlan(name: string | undefined, raw: McpAddRawArgs, homeDir?: string): McpAddPlan;
+/** The workspace twin of `collectMcpAddPlan` (trellis-workspace-scope
+ * task 3.4): identical validation, but the existence check runs against
+ * `.agents/config.json` — compared through the same snake_case
+ * serialization the file stores, so a re-add of the same definition is
+ * a clean "already-present" no-op. A global same-name entry is NOT a
+ * conflict here (workspace shadowing a global entry is a legal,
+ * documented merge outcome), just noted in the detail. */
+export declare function collectMcpAddWorkspacePlan(name: string | undefined, raw: McpAddRawArgs, workspaceRoot: string, homeDir?: string): McpAddPlan;
 export type McpSetAuthAction = "updated" | "already-set" | "not-found" | "invalid-input";
 export interface McpSetAuthPlan {
     name: string;
@@ -269,10 +300,22 @@ export declare function applyMcpAddWithSync(plan: McpAddPlan, opts?: {
     dryRun?: boolean;
     backupSession?: BackupSession;
 }): Promise<McpAddOutcome>;
+/** Workspace twin of `applyMcpAddWithSync` (trellis-workspace-scope task
+ * 3.4): writes `.agents/config.json` instead of `servers.yaml`, then
+ * cascades the same mcp sync — which, run inside the workspace, renders
+ * only the project-level targets for the workspace layer (plus the usual
+ * global-layer targets; the agent does its own layering). */
+export declare function applyMcpAddWorkspaceWithSync(plan: McpAddPlan, workspaceRoot: string, opts?: {
+    homeDir?: string;
+    dryRun?: boolean;
+    backupSession?: BackupSession;
+}): Promise<McpAddOutcome>;
 export declare function runMcpAdd(name: string | undefined, raw: McpAddRawArgs, opts?: {
     homeDir?: string;
     json?: boolean;
     dryRun?: boolean;
+    workspace?: boolean;
+    workspaceDir?: string;
 }): Promise<{
     exitCode: number;
 }>;