agent-trellis 0.10.0 → 0.11.0

package/dist/cli.js

@@ -9,13 +9,14 @@ import { runInit } from "./commands/init.js";
 import { runMigrate } from "./commands/migrate.js";
 import { runOnboard } from "./commands/onboard.js";
 import { runSync } from "./commands/sync.js";
-import { runMcpSync, runMcpList, runMcpAdd, runMcpRemove, runMcpSetAuth, parseMcpAddArgs, parseMcpSetArgs } from "./commands/mcp.js";
+import { runMcpSync, runMcpList, runMcpAdd, runMcpRemove, runMcpSetAuth, runMcpScope, parseMcpAddArgs, parseMcpSetArgs } from "./commands/mcp.js";
+import { parseScopeArgs } from "./lib/scopeSelection.js";
 import { runMcpImport } from "./commands/mcpImport.js";
 import { parseMcpGatewayArgs, runMcpGateway, runMcpRuntime } from "./commands/mcpGateway.js";
 import { runMcpAuth } from "./commands/mcpAuth.js";
 import { runSecretsAudit } from "./commands/secretsAudit.js";
 import { runRollback } from "./commands/rollback.js";
-import { runSkillList, runSkillAdd, runSkillRemove, runSkillUpdateBuiltin } from "./commands/skill.js";
+import { runSkillList, runSkillAdd, runSkillRemove, runSkillScope, runSkillUpdateBuiltin } from "./commands/skill.js";
 import { runRemoteSkillAdd, runRemoteSkillList, runRemoteSkillUpdate } from "./commands/remoteSkill.js";
 import { collectMemoryList, runMemoryExtraction, runMemorySync } from "./commands/memory.js";
 import { parseManageArgs, runManage } from "./commands/manage.js";
@@ -142,6 +143,14 @@ Commands:
                          --auth none removes it along with the classification.
             --dry-run    preview the plan, write nothing
             --json       machine-readable output, no report text
+  mcp scope <name> --agents <ids> | --all | --none
+            Choose which managed agents reach a canonical MCP server, then
+            run the same sync as mcp sync. Exactly one selector is
+            required; ids must be managed agents. Selecting every managed
+            agent records no explicit scope, so a newly managed agent is
+            included. An entry Trellis did not write is never removed.
+              --dry-run    preview the plan, write nothing
+              --json       machine-readable output, no report text
   mcp auth <server-name>
             Authorize a remote (http/sse) MCP server that uses OAuth —
               opens a browser once, stores the result 0600 under
@@ -169,6 +178,12 @@ Commands:
               --dry-run    preview the plan, write nothing
               --json       machine-readable output, no report text
   skill remove <name>
+  skill scope <name> --agents <ids> | --all | --none
+            Choose which managed agents receive a canonical skill, then
+            sync it. Same selector rules as mcp scope; a built-in skill's
+            scope is not editable
+              --dry-run    preview the plan, write nothing
+              --json       machine-readable output, no report text
   skill update-builtin
             Refresh the package-owned trellis-runtime Skill in canonical
             source; existing native symlinks see the update
@@ -440,6 +455,11 @@ async function main(argv) {
             process.exitCode = runMcpSetAuth(name, parseMcpSetArgs(mcpRest), { json, dryRun }).exitCode;
             return;
         }
+        if (subcommand === "scope") {
+            const [name] = mcpRest;
+            process.exitCode = (await runMcpScope(name && !name.startsWith("--") ? name : undefined, parseScopeArgs(mcpRest), { json, dryRun })).exitCode;
+            return;
+        }
         if (subcommand === "remove") {
             const [name] = mcpRest;
             if (!name) {
@@ -461,7 +481,7 @@ async function main(argv) {
             process.exitCode = exitCode;
             return;
         }
-        console.error(`Unknown mcp subcommand: ${subcommand ?? "(none)"}\nUsage: trellis mcp sync|list|add <name>|set <name>|remove <name>|auth <name>\n`);
+        console.error(`Unknown mcp subcommand: ${subcommand ?? "(none)"}\nUsage: trellis mcp sync|list|add <name>|set <name>|scope <name>|remove <name>|auth <name>\n`);
         process.exitCode = 1;
         return;
     }
@@ -495,11 +515,16 @@ async function main(argv) {
             process.exitCode = (await runSkillRemove(name, { json, dryRun })).exitCode;
             return;
         }
+        if (subcommand === "scope") {
+            const [name] = skillRest;
+            process.exitCode = (await runSkillScope(name && !name.startsWith("--") ? name : undefined, parseScopeArgs(skillRest), { json, dryRun })).exitCode;
+            return;
+        }
         if (subcommand === "update-builtin") {
             process.exitCode = runSkillUpdateBuiltin({ json, dryRun }).exitCode;
             return;
         }
-        console.error(`Unknown skill subcommand: ${subcommand ?? "(none)"}\nUsage: trellis skill list|add <name> --from <path>|remove <name>|update-builtin\n`);
+        console.error(`Unknown skill subcommand: ${subcommand ?? "(none)"}\nUsage: trellis skill list|add <name> --from <path>|remove <name>|scope <name> --agents <ids>|--all|--none|update-builtin\n`);
         process.exitCode = 1;
         return;
     }

package/dist/commands/mcp.d.ts

@@ -15,6 +15,7 @@
 import { type ServersYamlWriteResult } from "../core/canonical.js";
 import type { AdapterPlanItem } from "../core/adapter.js";
 import type { AgentId, McpAuthMode, McpConfig, McpServerDef, Transport } from "../core/types.js";
+import { type ScopeSelectorRaw } from "../lib/scopeSelection.js";
 import { type BackupSession } from "../lib/backup.js";
 export interface RunMcpSyncOptions {
     json?: boolean;
@@ -62,6 +63,12 @@ export interface McpListEntry {
      * ever changes and there is one less place a future secret-looking field
      * could leak through. */
     preRegisteredClient?: true;
+    /** State of the stored OAuth credential, for OAuth-classified servers only
+     * (trellis-scope-editing-and-auth-status design.md D6). It describes the
+     * credential, not the connection: an `authorized` server can still be down. */
+    authStatus?: McpAuthStatus;
+    /** Epoch ms, when the stored token advertises an expiry. */
+    authExpiresAt?: number;
     enabled: boolean;
     agents: readonly AgentId[];
     command?: string;
@@ -77,6 +84,18 @@ export interface McpListEntry {
      * printed in full. */
     staticEnv?: Record<string, string>;
 }
+export type McpAuthStatus = "not-authorized" | "authorized" | "refreshable" | "expired";
+/**
+ * Reads only the per-server token store and returns the state, never a
+ * token. Classification stays explicit — the caller only asks for servers
+ * already declared OAuth, so a stray token file never makes one. A server
+ * name that cannot be a token filename, or an unreadable file, simply has no
+ * credential: one odd entry must not take down the whole listing.
+ */
+export declare function mcpCredentialState(homeDir: string, serverName: string): {
+    authStatus: McpAuthStatus;
+    authExpiresAt?: number;
+};
 export declare function collectMcpListPlan(homeDir?: string): McpListEntry[];
 export declare function runMcpList(opts?: {
     homeDir?: string;
@@ -169,6 +188,47 @@ export declare function runMcpSetAuth(name: string | undefined, raw: McpSetAuthR
 }): {
     exitCode: number;
 };
+export type McpScopeAction = "updated" | "already-set" | "not-found" | "invalid-input";
+export interface McpScopePlan {
+    name: string;
+    action: McpScopeAction;
+    detail: string;
+    /** Recorded as `agents:` on the entry; `undefined` removes the key so the
+     * server reaches every managed agent. */
+    scope?: AgentId[];
+    mode?: "all" | "none" | "explicit";
+    normalizedFromFull?: boolean;
+    effective?: readonly AgentId[];
+    /** Only set when action === "updated"; consumed by applyMcpScopeWithSync. */
+    def?: McpServerDef;
+}
+/**
+ * `mcp scope <name> --agents a,b | --all | --none`
+ * (trellis-scope-editing-and-auth-status tasks.md 1.2). Same selector rules as
+ * `skill scope`, which is why both go through `resolveScopeSelection`.
+ */
+export declare function collectMcpScopePlan(name: string | undefined, raw: ScopeSelectorRaw, homeDir?: string): McpScopePlan;
+export interface McpScopeOutcome {
+    plan: McpScopePlan;
+    writeError?: string;
+    sync?: McpSyncReport;
+}
+/** Write inside a backup session, then the same `mcp sync` `add` / `remove`
+ * run. Removal of an entry from an agent narrowed away stays gated by the
+ * ownership ledger, so an entry Trellis did not write is never deleted
+ * (design.md D5). */
+export declare function applyMcpScopeWithSync(plan: McpScopePlan, opts?: {
+    homeDir?: string;
+    dryRun?: boolean;
+    backupSession?: BackupSession;
+}): Promise<McpScopeOutcome>;
+export declare function runMcpScope(name: string | undefined, raw: ScopeSelectorRaw, opts?: {
+    homeDir?: string;
+    json?: boolean;
+    dryRun?: boolean;
+}): Promise<{
+    exitCode: number;
+}>;
 export declare function applyMcpAddPlan(plan: McpAddPlan, homeDir?: string, backup?: BackupSession): ServersYamlWriteResult;
 export interface McpAddOutcome {
     plan: McpAddPlan;

package/dist/commands/mcp.js

@@ -18,6 +18,8 @@ import { join } from "node:path";
 import { loadCanonicalSource, upsertServerYaml, removeServerYaml } from "../core/canonical.js";
 import { ALL_AGENTS, isOAuthAuth, oauthClientMetadata, resolveScope } from "../core/types.js";
 import { isValidSecretVarName } from "../lib/secretEnv.js";
+import { isExpired, readToken } from "../lib/oauth/store.js";
+import { describeScope, resolveScopeSelection, sameScope } from "../lib/scopeSelection.js";
 import { ClaudeCodeAdapter } from "../adapters/claude-code.js";
 import { CodexAdapter } from "../adapters/codex.js";
 import { KiroAdapter } from "../adapters/kiro.js";
@@ -114,6 +116,28 @@ export function printReport(report, dryRun) {
 function serversYamlPath(homeDir) {
     return join(homeDir, ".trellis", "mcp", "servers.yaml");
 }
+/**
+ * Reads only the per-server token store and returns the state, never a
+ * token. Classification stays explicit — the caller only asks for servers
+ * already declared OAuth, so a stray token file never makes one. A server
+ * name that cannot be a token filename, or an unreadable file, simply has no
+ * credential: one odd entry must not take down the whole listing.
+ */
+export function mcpCredentialState(homeDir, serverName) {
+    let token;
+    try {
+        token = readToken(homeDir, serverName);
+    }
+    catch {
+        return { authStatus: "not-authorized" };
+    }
+    if (!token?.accessToken)
+        return { authStatus: "not-authorized" };
+    const expiry = token.expiresAt !== undefined ? { authExpiresAt: token.expiresAt } : {};
+    if (!isExpired(token))
+        return { authStatus: "authorized", ...expiry };
+    return { authStatus: token.refreshToken ? "refreshable" : "expired", ...expiry };
+}
 export function collectMcpListPlan(homeDir = homedir()) {
     const canonical = loadCanonicalSource(homeDir);
     return Object.entries(canonical.mcp.servers).map(([name, def]) => ({
@@ -121,6 +145,7 @@ export function collectMcpListPlan(homeDir = homedir()) {
         transport: def.transport,
         auth: isOAuthAuth(def.auth) ? "oauth" : undefined,
         preRegisteredClient: oauthClientMetadata(def.auth).clientId !== undefined ? true : undefined,
+        ...(isOAuthAuth(def.auth) ? mcpCredentialState(homeDir, name) : {}),
         enabled: def.enabled ?? true,
         agents: resolveScope(def.agents, canonical.managedAgents),
         command: def.command,
@@ -150,7 +175,7 @@ export function runMcpList(opts = {}) {
     else {
         for (const e of entries) {
             const scope = e.agents.length > 0 ? e.agents.join(", ") : "(no managed agent reaches it)";
-            console.log(`${e.name} (${e.transport}${e.auth === "oauth" ? ", oauth" : ""}${e.preRegisteredClient ? ", pre-registered client" : ""})${e.enabled ? "" : " [disabled]"} — ${scope}`);
+            console.log(`${e.name} (${e.transport}${e.auth === "oauth" ? ", oauth" : ""}${e.preRegisteredClient ? ", pre-registered client" : ""}${e.authStatus ? `, credential: ${e.authStatus}` : ""})${e.enabled ? "" : " [disabled]"} — ${scope}`);
             if (e.env && e.env.length > 0)
                 console.log(`   env: ${e.env.join(", ")} (values never read/printed)`);
             if (e.staticEnv)
@@ -399,6 +424,85 @@ export function runMcpSetAuth(name, raw, opts = {}) {
     }
     return { exitCode: ["invalid-input", "not-found"].includes(plan.action) || Boolean(writeError) ? 1 : 0 };
 }
+/**
+ * `mcp scope <name> --agents a,b | --all | --none`
+ * (trellis-scope-editing-and-auth-status tasks.md 1.2). Same selector rules as
+ * `skill scope`, which is why both go through `resolveScopeSelection`.
+ */
+export function collectMcpScopePlan(name, raw, homeDir = homedir()) {
+    if (!name)
+        return { name: "(none)", action: "invalid-input", detail: "usage: trellis mcp scope <name> --agents <ids> | --all | --none" };
+    const canonical = loadCanonicalSource(homeDir);
+    const selection = resolveScopeSelection(raw, canonical.managedAgents);
+    if (!selection.ok)
+        return { name, action: "invalid-input", detail: selection.detail };
+    const current = canonical.mcp.servers[name];
+    if (!current)
+        return { name, action: "not-found", detail: `no canonical MCP server named "${name}"` };
+    const base = {
+        name,
+        scope: selection.scope,
+        mode: selection.mode,
+        normalizedFromFull: selection.normalizedFromFull,
+        effective: resolveScope(selection.scope, canonical.managedAgents),
+    };
+    const summary = describeScope(selection.scope, canonical.managedAgents);
+    if (sameScope(current.agents, selection.scope)) {
+        return { ...base, action: "already-set", detail: `scope is already ${summary}` };
+    }
+    const { agents: _agents, ...withoutAgents } = current;
+    const def = selection.scope === undefined ? withoutAgents : { ...withoutAgents, agents: selection.scope };
+    const normalized = selection.normalizedFromFull ? " (every managed agent selected — recorded as the default, so a newly managed agent is included)" : "";
+    return { ...base, action: "updated", detail: `set scope to ${summary}${normalized}`, def };
+}
+/** Write inside a backup session, then the same `mcp sync` `add` / `remove`
+ * run. Removal of an entry from an agent narrowed away stays gated by the
+ * ownership ledger, so an entry Trellis did not write is never deleted
+ * (design.md D5). */
+export async function applyMcpScopeWithSync(plan, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const ownSession = !opts.dryRun && !opts.backupSession && plan.action === "updated" ? openBackupSession(homeDir, "mcp-scope") : undefined;
+    const session = opts.backupSession ?? ownSession;
+    let writeError;
+    if (!opts.dryRun && plan.action === "updated" && plan.def) {
+        const result = upsertServerYaml(serversYamlPath(homeDir), plan.name, plan.def, session);
+        if (!result.ok)
+            writeError = result.error;
+    }
+    ownSession?.finalize();
+    let syncReport;
+    if (!writeError && plan.action === "updated" && existsSync(join(homeDir, ".trellis"))) {
+        syncReport = await collectMcpSyncReport({ homeDir, dryRun: opts.dryRun });
+    }
+    return { plan, ...(writeError ? { writeError } : {}), ...(syncReport ? { sync: syncReport } : {}) };
+}
+export async function runMcpScope(name, raw, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    let outcome;
+    try {
+        outcome = await applyMcpScopeWithSync(collectMcpScopePlan(name, raw, homeDir), { homeDir, dryRun: opts.dryRun });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
+    }
+    const { plan, writeError, sync: syncReport } = outcome;
+    if (opts.json) {
+        const payload = writeError ? { ...plan, writeError } : plan;
+        console.log(JSON.stringify(syncReport ? { ...payload, sync: syncReport } : payload, null, 2));
+    }
+    else {
+        console.log(`${opts.dryRun ? "[dry run] " : ""}mcp scope ${plan.name}`);
+        console.log(`  [${plan.action}] ${plan.detail}`);
+        if (writeError)
+            console.error(`  write failed: ${writeError}`);
+        if (syncReport)
+            printReport(syncReport, opts.dryRun ?? false);
+    }
+    const failed = plan.action === "invalid-input" || plan.action === "not-found" || Boolean(writeError);
+    const syncConflict = syncReport?.reports.some((r) => r.items.some((i) => i.action === "conflict")) ?? false;
+    return { exitCode: failed || syncConflict ? 1 : 0 };
+}
 export function applyMcpAddPlan(plan, homeDir = homedir(), backup) {
     if (plan.action !== "create" || !plan.def)
         return { ok: true };

package/dist/commands/skill.d.ts

@@ -1,5 +1,5 @@
 /**
- * `trellis skill list|add|remove` — command-line CRUD for canonical
+ * `trellis skill list|add|remove|scope` — command-line CRUD for canonical
  * skills (trellis-canonical-cli-crud), an alternative to hand-editing
  * `~/.trellis/skills/<name>/SKILL.md` directly. `add`'s conflict
  * decision and `remove`'s "sync will un-sync it" behavior both reuse
@@ -10,6 +10,7 @@
 import type { AgentId } from "../core/types.js";
 import { type BackupSession } from "../lib/backup.js";
 import type { SyncReport } from "./sync.js";
+import { type ScopeSelectorRaw } from "../lib/scopeSelection.js";
 import type { RemoteSkillLockEntry } from "../lib/remoteSkillLock.js";
 export type BuiltinSkillUpdateAction = "create" | "update" | "already-current";
 export interface BuiltinSkillUpdatePlan {
@@ -97,3 +98,46 @@ export declare function runSkillRemove(name: string, opts?: {
 }): Promise<{
     exitCode: number;
 }>;
+export type SkillScopeAction = "updated" | "already-set" | "not-found" | "invalid-input";
+export interface SkillScopePlan {
+    name: string;
+    action: SkillScopeAction;
+    detail: string;
+    /** What will be recorded in `scope.yaml`; `undefined` clears the explicit
+     * scope so the skill reaches every managed agent. Set when the selection was
+     * valid, whatever the action. */
+    scope?: AgentId[];
+    mode?: "all" | "none" | "explicit";
+    /** True when a full selection was dropped instead of recorded
+     * (trellis-scope-editing-and-auth-status design.md D3). */
+    normalizedFromFull?: boolean;
+    /** The agents that will actually receive the skill afterwards. */
+    effective?: readonly AgentId[];
+}
+/**
+ * `skill scope <name> --agents a,b | --all | --none`
+ * (trellis-scope-editing-and-auth-status tasks.md 1.1). Plan only — the write
+ * and the cascade sync live in `applySkillScopeWithSync`.
+ */
+export declare function collectSkillScopePlan(name: string | undefined, raw: ScopeSelectorRaw, homeDir?: string): SkillScopePlan;
+export interface SkillScopeOutcome {
+    plan: SkillScopePlan;
+    writeError?: string;
+    sync?: SyncReport;
+}
+/** Write inside a backup session so `trellis rollback` covers it, then the
+ * same skills sync `add` / `remove` run — narrowing is converged by
+ * `symlinkPlan`'s existing "canonical entry gone or scoped away" removal
+ * (design.md D5). */
+export declare function applySkillScopeWithSync(plan: SkillScopePlan, opts?: {
+    homeDir?: string;
+    dryRun?: boolean;
+    backupSession?: BackupSession;
+}): Promise<SkillScopeOutcome>;
+export declare function runSkillScope(name: string | undefined, raw: ScopeSelectorRaw, opts?: {
+    homeDir?: string;
+    json?: boolean;
+    dryRun?: boolean;
+}): Promise<{
+    exitCode: number;
+}>;

package/dist/commands/skill.js

@@ -1,5 +1,5 @@
 /**
- * `trellis skill list|add|remove` — command-line CRUD for canonical
+ * `trellis skill list|add|remove|scope` — command-line CRUD for canonical
  * skills (trellis-canonical-cli-crud), an alternative to hand-editing
  * `~/.trellis/skills/<name>/SKILL.md` directly. `add`'s conflict
  * decision and `remove`'s "sync will un-sync it" behavior both reuse
@@ -14,12 +14,13 @@ import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { decideDirImport } from "../lib/dirEquals.js";
 import { findSkillFile } from "../lib/skillFile.js";
-import { loadCanonicalSource } from "../core/canonical.js";
+import { loadCanonicalSource, writeSkillScopeYaml } from "../core/canonical.js";
 import { resolveScope } from "../core/types.js";
 import { isBuiltinSkillName } from "../lib/builtinSkills.js";
 import { openBackupSession } from "../lib/backup.js";
 import { collectSyncReport, printReport as printSyncReport } from "./sync.js";
 import { remoteSkillProvenance } from "./remoteSkill.js";
+import { describeScope, resolveScopeSelection, sameScope } from "../lib/scopeSelection.js";
 function builtinSkillTemplate() {
     const here = dirname(fileURLToPath(import.meta.url));
     return readFileSync(join(here, "..", "..", "schema", "builtin-skills", "trellis-runtime", "SKILL.md"), "utf8");
@@ -205,3 +206,83 @@ export async function runSkillRemove(name, opts = {}) {
     const syncConflict = syncReport?.reports.some((r) => r.items.some((i) => i.action === "conflict")) ?? false;
     return { exitCode: failed || syncConflict ? 1 : 0 };
 }
+/**
+ * `skill scope <name> --agents a,b | --all | --none`
+ * (trellis-scope-editing-and-auth-status tasks.md 1.1). Plan only — the write
+ * and the cascade sync live in `applySkillScopeWithSync`.
+ */
+export function collectSkillScopePlan(name, raw, homeDir = homedir()) {
+    if (!name)
+        return { name: "(none)", action: "invalid-input", detail: "usage: trellis skill scope <name> --agents <ids> | --all | --none" };
+    if (isBuiltinSkillName(name)) {
+        return { name, action: "invalid-input", detail: `"${name}" is a Trellis package-owned Skill — its scope is not editable` };
+    }
+    const canonical = loadCanonicalSource(homeDir);
+    const selection = resolveScopeSelection(raw, canonical.managedAgents);
+    if (!selection.ok)
+        return { name, action: "invalid-input", detail: selection.detail };
+    const skill = canonical.skills.find((candidate) => candidate.name === name);
+    if (!skill)
+        return { name, action: "not-found", detail: `no canonical skill named "${name}"` };
+    const base = {
+        name,
+        scope: selection.scope,
+        mode: selection.mode,
+        normalizedFromFull: selection.normalizedFromFull,
+        effective: resolveScope(selection.scope, canonical.managedAgents),
+    };
+    const summary = describeScope(selection.scope, canonical.managedAgents);
+    const normalized = selection.normalizedFromFull ? " (every managed agent selected — recorded as the default, so a newly managed agent is included)" : "";
+    if (sameScope(skill.scope, selection.scope)) {
+        return { ...base, action: "already-set", detail: `scope is already ${summary}` };
+    }
+    return { ...base, action: "updated", detail: `set scope to ${summary}${normalized}` };
+}
+/** Write inside a backup session so `trellis rollback` covers it, then the
+ * same skills sync `add` / `remove` run — narrowing is converged by
+ * `symlinkPlan`'s existing "canonical entry gone or scoped away" removal
+ * (design.md D5). */
+export async function applySkillScopeWithSync(plan, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const ownSession = !opts.dryRun && !opts.backupSession && plan.action === "updated" ? openBackupSession(homeDir, "skill-scope") : undefined;
+    const session = opts.backupSession ?? ownSession;
+    let writeError;
+    if (!opts.dryRun && plan.action === "updated") {
+        const result = writeSkillScopeYaml(join(homeDir, ".trellis", "scope.yaml"), plan.name, plan.scope, session);
+        if (!result.ok)
+            writeError = result.error;
+    }
+    ownSession?.finalize();
+    let syncReport;
+    if (!writeError && plan.action === "updated" && existsSync(join(homeDir, ".trellis"))) {
+        syncReport = await collectSyncReport({ target: "skills", homeDir, dryRun: opts.dryRun });
+    }
+    return { plan, ...(writeError ? { writeError } : {}), ...(syncReport ? { sync: syncReport } : {}) };
+}
+export async function runSkillScope(name, raw, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    let outcome;
+    try {
+        outcome = await applySkillScopeWithSync(collectSkillScopePlan(name, raw, homeDir), { homeDir, dryRun: opts.dryRun });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
+    }
+    const { plan, writeError, sync: syncReport } = outcome;
+    if (opts.json) {
+        const payload = writeError ? { ...plan, writeError } : plan;
+        console.log(JSON.stringify(syncReport ? { ...payload, sync: syncReport } : payload, null, 2));
+    }
+    else {
+        console.log(`${opts.dryRun ? "[dry run] " : ""}skill scope ${plan.name}`);
+        console.log(`  [${plan.action}] ${plan.detail}`);
+        if (writeError)
+            console.error(`  write failed: ${writeError}`);
+        if (syncReport)
+            printSyncReport(syncReport, opts.dryRun ?? false);
+    }
+    const failed = plan.action === "invalid-input" || plan.action === "not-found" || Boolean(writeError);
+    const syncConflict = syncReport?.reports.some((r) => r.items.some((i) => i.action === "conflict")) ?? false;
+    return { exitCode: failed || syncConflict ? 1 : 0 };
+}

package/dist/lib/mcpRuntime.d.ts

@@ -2,6 +2,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import type { CallToolResult, GetPromptResult, Implementation, Prompt, ReadResourceResult, Resource, Tool } from "@modelcontextprotocol/sdk/types.js";
 import type { AgentId } from "../core/types.js";
 import type { GatewayBackend } from "./gatewayBackend.js";
+import type { SkillEntry } from "./skillManifest.js";
 export interface RuntimeContext {
     agentId: AgentId;
     homeDir: string;
@@ -14,6 +15,9 @@ export interface TrellisProvider {
     readResource?(uri: URL, context: RuntimeContext): Promise<ReadResourceResult> | ReadResourceResult;
     listPrompts?(context: RuntimeContext): Promise<Prompt[]> | Prompt[];
     getPrompt?(name: string, args: Record<string, string> | undefined, context: RuntimeContext): Promise<GetPromptResult> | GetPromptResult;
+    /** Skills-over-MCP `skills/list` and `skills/get` (trellis-skills-over-mcp). */
+    listSkillEntries?(context: RuntimeContext): Promise<SkillEntry[]> | SkillEntry[];
+    getSkillEntry?(uri: string, context: RuntimeContext): Promise<SkillEntry | undefined> | SkillEntry | undefined;
     close?(): Promise<void>;
 }
 export declare class BuiltinRegistry {
@@ -29,6 +33,8 @@ export declare class BuiltinRegistry {
     callTool(name: string, args: unknown, context: RuntimeContext): Promise<CallToolResult>;
     listResources(context: RuntimeContext): Promise<Resource[]>;
     readResource(uri: URL, context: RuntimeContext): Promise<ReadResourceResult>;
+    listSkills(context: RuntimeContext): Promise<SkillEntry[]>;
+    getSkill(uri: string, context: RuntimeContext): Promise<SkillEntry | undefined>;
     listPrompts(context: RuntimeContext): Promise<Prompt[]>;
     getPrompt(name: string, args: Record<string, string> | undefined, context: RuntimeContext): Promise<GetPromptResult>;
     close(): Promise<void>;

package/dist/lib/mcpRuntime.js

@@ -1,5 +1,5 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ErrorCode, McpError, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { allocateExposedToolNames } from "./mcpToolRegistry.js";
 function compactBuiltinToolName(name) {
     return name.startsWith("trellis.") ? name.slice("trellis.".length).replaceAll(".", "_") : name;
@@ -106,6 +106,35 @@ export class BuiltinRegistry {
             throw new Error(`unknown Trellis resource "${key}"`);
         return provider.readResource(uri, context);
     }
+    async listSkills(context) {
+        const skills = [];
+        for (const provider of this.providers) {
+            if (!provider.listSkillEntries)
+                continue;
+            try {
+                skills.push(...(await provider.listSkillEntries(context)));
+            }
+            catch (err) {
+                this.warn(providerError(provider.id, err));
+            }
+        }
+        return skills;
+    }
+    async getSkill(uri, context) {
+        for (const provider of this.providers) {
+            if (!provider.getSkillEntry)
+                continue;
+            try {
+                const entry = await provider.getSkillEntry(uri, context);
+                if (entry)
+                    return entry;
+            }
+            catch (err) {
+                this.warn(providerError(provider.id, err));
+            }
+        }
+        return undefined;
+    }
     async listPrompts(context) {
         const prompts = [];
         this.promptOwners.clear();
@@ -181,5 +210,27 @@ export function createRuntimeServer(serverInfo, context, registry) {
     server.setRequestHandler(ReadResourceRequestSchema, async (request) => registry.readResource(new URL(request.params.uri), context));
     server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: await registry.listPrompts(context) }));
     server.setRequestHandler(GetPromptRequestSchema, async (request) => registry.getPrompt(request.params.name, request.params.arguments, context));
+    // `skills/list` and `skills/get` are not in this SDK's schema set (it speaks
+    // at most 2025-11-25), so they are answered through the SDK's fallback for
+    // methods with no registered handler, which keeps the extension free of a new
+    // direct zod dependency. The extension itself is deliberately NOT declared in
+    // the capabilities above: the specification declares it only through
+    // `server/discover`, which this revision lacks, and inventing another field
+    // would claim a protocol nobody defined (trellis-skills-over-mcp D4). Any
+    // other unknown method keeps the SDK's usual "method not found".
+    server.fallbackRequestHandler = async (request) => {
+        const cache = { resultType: "complete", ttlMs: 0, cacheScope: "private" };
+        if (request.method === "skills/list") {
+            return { ...cache, skills: await registry.listSkills(context) };
+        }
+        if (request.method === "skills/get") {
+            const uri = request.params?.uri;
+            const entry = typeof uri === "string" ? await registry.getSkill(uri, context) : undefined;
+            if (!entry)
+                throw new McpError(ErrorCode.InvalidParams, "unknown skill");
+            return { ...cache, skill: entry };
+        }
+        throw new McpError(ErrorCode.MethodNotFound, `Method not found: ${request.method}`);
+    };
     return server;
 }

package/dist/lib/scopeSelection.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared agent-scope selection for `skill scope` / `mcp scope`
+ * (trellis-scope-editing-and-auth-status design.md D1–D3). Both commands
+ * take exactly one of `--agents a,b`, `--all`, `--none`; keeping the parsing,
+ * validation and normalization here means a skill and an MCP server can never
+ * disagree about what a given selection means.
+ */
+import type { AgentId } from "../core/types.js";
+/** Raw, unvalidated flag values — the parser stays a dumb reader and every
+ * rule below lives in `resolveScopeSelection`. */
+export interface ScopeSelectorRaw {
+    /** Comma-separated agent ids. */
+    agents?: string;
+    all?: boolean;
+    none?: boolean;
+}
+export type ScopeSelection = {
+    ok: true;
+    /** What to record: `undefined` clears the explicit scope. */
+    scope: AgentId[] | undefined;
+    mode: "all" | "none" | "explicit";
+    /** True when the user listed every managed agent and the explicit scope
+     * was dropped instead of recorded (design.md D3). */
+    normalizedFromFull: boolean;
+} | {
+    ok: false;
+    detail: string;
+};
+export declare const SCOPE_SELECTOR_USAGE = "exactly one of --agents <ids>, --all, --none is required";
+/** `argv.indexOf`-style reader, same idiom as every other command's flags. */
+export declare function parseScopeArgs(argv: readonly string[]): ScopeSelectorRaw;
+export declare function resolveScopeSelection(raw: ScopeSelectorRaw, managed: readonly AgentId[]): ScopeSelection;
+/** Order-insensitive equality between the scope on disk and the one about to
+ * be written, with `undefined` (no explicit scope) distinct from `[]`. */
+export declare function sameScope(current: readonly AgentId[] | undefined, next: readonly AgentId[] | undefined): boolean;
+export declare function describeScope(scope: readonly AgentId[] | undefined, managed: readonly AgentId[]): string;