agent-trellis 0.20.0 → 0.22.0

package/dist/commands/remoteSkill.js

@@ -15,6 +15,7 @@ import { isBuiltinSkillName } from "../lib/builtinSkills.js";
 import { emptyRemoteSkillLock, readRemoteSkillLock, writeRemoteSkillLock } from "../lib/remoteSkillLock.js";
 import { fetchRemoteRepository, normalizeGitHubRepository } from "../lib/remoteSkillSource.js";
 import { collectSyncReport, printReport as printSyncReport } from "./sync.js";
+import { requestSkillScope } from "../lib/skillScope.js";
 function safeSkillName(name) {
     return typeof name === "string" && /^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(name) && name !== "." && name !== "..";
 }
@@ -41,7 +42,9 @@ function scopeForRequest(homeDir, agents) {
         return { error: error instanceof Error ? error.message : String(error) };
     }
     if (!agents || agents.length === 0)
-        return { scope: undefined };
+        return { error: 'choose applicable agents with --agent <ids> or --agent "*"' };
+    if (agents.length === 1 && agents[0] === "none")
+        return { scope: [] };
     const values = agents.flatMap((value) => value.split(",").map((id) => id.trim()).filter(Boolean));
     if (values.length === 0)
         return { error: "--agent needs at least one Agent id" };
@@ -164,6 +167,20 @@ export async function runRemoteSkillAdd(sourceInput, name, opts = {}) {
             console.error(plan.detail);
         return { exitCode: 1 };
     }
+    if (!opts.agents) {
+        const home = opts.homeDir ?? homedir();
+        const managed = existsSync(join(home, ".trellis")) ? loadCanonicalSource(home).managedAgents : [];
+        const selected = await requestSkillScope({}, managed, !opts.json);
+        if ("error" in selected) {
+            const detail = `${selected.error}; remote import uses --agent <ids>, --agent "*" or --agent none`;
+            if (opts.json)
+                console.log(JSON.stringify({ action: "invalid-options", detail }));
+            else
+                console.error(detail);
+            return { exitCode: 1 };
+        }
+        opts = { ...opts, agents: selected.scope.length ? selected.scope : ["none"] };
+    }
     let fetched;
     try {
         fetched = fetchRemoteRepository(repository, { branch: opts.branch });

package/dist/commands/secretsAudit.d.ts

@@ -35,7 +35,7 @@ export interface SecretsFinding {
      * `~/.trellis/mcp/servers.yaml` itself (see module doc comment). */
     agent: AgentId | "environment" | "canonical";
     file: string;
-    kind: "literal-secret" | "unexpected-var-name" | "missing-env-value";
+    kind: "literal-secret" | "unexpected-var-name" | "missing-env-value" | "malformed-reference";
     detail: string;
 }
 export interface SecretsAuditReport {

package/dist/commands/secretsAudit.js

@@ -29,7 +29,7 @@ import { KiroAdapter } from "../adapters/kiro.js";
 import { ZcodeAdapter } from "../adapters/zcode.js";
 import { declaredEnvNames, extractJsonEnvVarNames, extractTomlEnvVarNames, extractZcodeEnvVarNames } from "../lib/envVarNames.js";
 import { resolveZcodeProfile } from "../probes/zcode.js";
-import { resolveSecretEnv } from "../lib/secretEnv.js";
+import { parseEnvEntry, resolveSecretEntries, SecretReferenceError } from "../lib/secretEnv.js";
 /** Only agents in `managedAgents` — a present-but-unmanaged agent's config
  * file is never even read (trellis-managed-agents), same restriction as
  * `sync`/`mcp sync`. pi has no static, generated MCP config file to audit
@@ -49,7 +49,7 @@ function auditedAgents(homeDir, managedAgents) {
  * a problem regardless of which agents' `servers.yaml` `agents:` field
  * would route it to (trellis-secrets-env-management design.md D3).
  */
-function findMissingEnvValues(servers, policy) {
+async function findMissingEnvValues(servers, policy) {
     const names = new Set();
     for (const def of Object.values(servers)) {
         for (const name of declaredEnvNames(def))
@@ -57,16 +57,52 @@ function findMissingEnvValues(servers, policy) {
     }
     if (names.size === 0)
         return [];
-    const resolved = resolveSecretEnv([...names], policy);
-    const source = policy.envFile ?? "process environment";
-    return [...names]
-        .filter((name) => !resolved[name])
-        .map((name) => ({
-        agent: "environment",
-        file: source,
-        kind: "missing-env-value",
-        detail: `"${name}" is declared by a canonical MCP server's env but has no resolvable value`,
-    }));
+    // Malformed `mxenv://` entries are findings in their own right — never
+    // skipped, never treated as bare names (mx-env-secret-source spec).
+    const entries = [...names];
+    const parsed = entries.map(parseEnvEntry);
+    const findings = [];
+    for (const p of parsed) {
+        if (p.kind === "invalid") {
+            findings.push({
+                agent: "environment",
+                file: policy.envFile ?? "process environment",
+                kind: "malformed-reference",
+                detail: `"${p.entry}" is not a valid mxenv://<profile>/<KEY> reference`,
+            });
+        }
+    }
+    const resolvable = entries.filter((_, i) => parsed[i].kind !== "invalid");
+    if (resolvable.length === 0)
+        return findings;
+    // Findings name the DELIVERED name (the KEY segment for a reference).
+    const pending = [...resolvable];
+    let resolved = {};
+    // One broken profile must be a finding, not abort the entire audit.
+    while (pending.length) {
+        try {
+            resolved = await resolveSecretEntries(pending, policy);
+            break;
+        }
+        catch (error) {
+            if (!(error instanceof SecretReferenceError))
+                throw error;
+            pending.splice(pending.indexOf(error.entry), 1);
+        }
+    }
+    for (const entry of resolvable) {
+        const p = parseEnvEntry(entry);
+        const delivered = p.kind === "invalid" ? entry : p.delivered;
+        if (!resolved[entry]) {
+            findings.push({
+                agent: "environment",
+                file: p.kind === "ref" ? `the mxenv composition (profile "${p.profile}")` : (policy.envFile ?? "process environment"),
+                kind: "missing-env-value",
+                detail: `"${delivered}" is declared by a canonical MCP server's env or headers but has no resolvable value`,
+            });
+        }
+    }
+    return findings;
 }
 /**
  * Reject-pattern-only scan of canonical's own `mcp/servers.yaml` (design.md
@@ -118,7 +154,7 @@ export async function collectSecretsAuditReport(opts = {}) {
         const content = readFileSync(file, "utf-8");
         findings.push(...auditFile(agent.id, file, content, canonical.secretsPolicy, agent.extractNames));
     }
-    findings.push(...findMissingEnvValues(canonical.mcp.servers, canonical.secretsPolicy));
+    findings.push(...await findMissingEnvValues(canonical.mcp.servers, canonical.secretsPolicy));
     findings.push(...auditCanonicalServersYaml(homeDir, canonical.secretsPolicy));
     return { findings };
 }

package/dist/commands/skill.d.ts

@@ -31,12 +31,18 @@ export declare function runSkillUpdateBuiltin(opts?: {
 export interface SkillListEntry {
     name: string;
     scope: readonly AgentId[];
+    registered?: boolean;
+    delivery?: {
+        state: "linked" | "missing" | "conflict" | "runtime";
+        path?: string;
+    };
     remote?: Pick<RemoteSkillLockEntry, "source" | "requestedRef" | "commit" | "subdirectory" | "digest">;
 }
-export declare function collectSkillList(homeDir?: string): SkillListEntry[];
+export declare function collectSkillList(homeDir?: string, agent?: AgentId): SkillListEntry[];
 export declare function runSkillList(opts?: {
     homeDir?: string;
     json?: boolean;
+    agent?: string;
 }): {
     exitCode: number;
 };
@@ -46,6 +52,7 @@ export interface SkillAddPlan {
     action: SkillAddAction;
     detail: string;
     sourceDir?: string;
+    scope?: AgentId[];
 }
 export declare function collectSkillAddPlan(name: string, fromPath: string, homeDir?: string): SkillAddPlan;
 export declare function applySkillAddPlan(plan: SkillAddPlan, homeDir?: string, backup?: BackupSession): void;
@@ -84,6 +91,7 @@ export declare function runSkillAdd(name: string, fromPath: string, opts?: {
     dryRun?: boolean;
     workspace?: boolean;
     workspaceDir?: string;
+    selection?: ScopeSelectorRaw;
 }): Promise<{
     exitCode: number;
 }>;
@@ -117,13 +125,10 @@ 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. */
+    /** Applicable agents recorded in scope.yaml. Even --all is a fixed list. */
     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). */
+    /** Retained for API compatibility; skill lists are never normalized away. */
     normalizedFromFull?: boolean;
     /** The agents that will actually receive the skill afterwards. */
     effective?: readonly AgentId[];

package/dist/commands/skill.js

@@ -14,14 +14,17 @@ import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { decideDirImport } from "../lib/dirEquals.js";
 import { findSkillFile } from "../lib/skillFile.js";
-import { loadCanonicalSource, writeSkillScopeYaml } from "../core/canonical.js";
+import { loadCanonicalSource, validateSkillScopeYaml, 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";
+import { sameScope } from "../lib/scopeSelection.js";
 import { findWorkspaceRoot } from "../lib/workspace.js";
+import { readSkillScopes, requestSkillScope, selectSkillScope } from "../lib/skillScope.js";
+import { isSymlinkTo } from "../lib/fsIdentity.js";
+import { usesNativeCapabilityDelivery, ALL_AGENTS } from "../core/types.js";
 function builtinSkillTemplate() {
     const here = dirname(fileURLToPath(import.meta.url));
     return readFileSync(join(here, "..", "..", "schema", "builtin-skills", "trellis-runtime", "SKILL.md"), "utf8");
@@ -58,17 +61,34 @@ export function runSkillUpdateBuiltin(opts = {}) {
         console.log(`${opts.dryRun ? "[dry run] " : ""}skill update-builtin\n  [${plan.action}] ${plan.detail}`);
     return { exitCode: 0 };
 }
-export function collectSkillList(homeDir = homedir()) {
+export function collectSkillList(homeDir = homedir(), agent) {
     const canonical = loadCanonicalSource(homeDir);
     const provenance = remoteSkillProvenance(homeDir);
-    return canonical.skills.filter((skill) => !isBuiltinSkillName(skill.name)).map((skill) => ({
+    const registry = readSkillScopes(join(homeDir, ".trellis", "scope.yaml"));
+    const roots = {
+        "claude-code": join(homeDir, ".claude", "skills"), codex: join(homeDir, ".agents", "skills"),
+        kiro: join(homeDir, ".kiro", "skills"), pi: join(homeDir, ".pi", "agent", "skills"),
+        "kimi-code": join(homeDir, ".kimi-code", "skills"), zcode: "",
+    };
+    return canonical.skills.filter((skill) => agent ? resolveScope(skill.scope, canonical.managedAgents).includes(agent) : !isBuiltinSkillName(skill.name)).map((skill) => ({
         name: skill.name,
         scope: resolveScope(skill.scope, canonical.managedAgents),
+        ...(agent ? {
+            registered: Object.hasOwn(registry, skill.name) || isBuiltinSkillName(skill.name),
+            delivery: !usesNativeCapabilityDelivery(agent, canonical.mcp) || agent === "zcode"
+                ? { state: "runtime" }
+                : { state: isSymlinkTo(join(roots[agent], skill.name), skill.dir) ? "linked"
+                        : existsSync(join(roots[agent], skill.name)) ? "conflict" : "missing", path: join(roots[agent], skill.name) },
+        } : {}),
         ...(provenance[skill.name] ? { remote: provenance[skill.name] } : {}),
     }));
 }
 export function runSkillList(opts = {}) {
-    const entries = collectSkillList(opts.homeDir ?? homedir());
+    if (opts.agent !== undefined && !ALL_AGENTS.includes(opts.agent)) {
+        console.error(`unknown agent: ${opts.agent}; choose ${ALL_AGENTS.join(", ")}`);
+        return { exitCode: 1 };
+    }
+    const entries = collectSkillList(opts.homeDir ?? homedir(), opts.agent);
     if (opts.json) {
         console.log(JSON.stringify(entries, null, 2));
     }
@@ -76,9 +96,9 @@ export function runSkillList(opts = {}) {
         console.log("No skills in canonical source yet.");
     }
     else {
-        for (const { name, scope, remote } of entries) {
+        for (const { name, scope, remote, delivery } of entries) {
             const provenance = remote ? ` — remote: ${remote.source}@${remote.commit.slice(0, 12)}` : "";
-            console.log(`${name} — ${scope.length > 0 ? scope.join(", ") : "(no managed agent reaches it)"}${provenance}`);
+            console.log(`${name} — ${scope.length > 0 ? scope.join(", ") : "(paused: no applicable managed agent)"}${delivery ? ` [${delivery.state}]` : ""}${provenance}`);
         }
     }
     return { exitCode: 0 };
@@ -105,15 +125,26 @@ export function collectSkillAddPlan(name, fromPath, homeDir = homedir()) {
     }
 }
 export function applySkillAddPlan(plan, homeDir = homedir(), backup) {
-    if (plan.action !== "create" || !plan.sourceDir)
+    if (plan.action !== "create" && !(plan.action === "already-present" && plan.scope !== undefined))
         return;
-    const dest = join(homeDir, ".trellis", "skills", plan.name);
-    if (backup) {
-        backup.createDirFromSource(dest, plan.sourceDir);
+    if (plan.action === "create" && !plan.sourceDir)
         return;
+    const scopePath = join(homeDir, ".trellis", "scope.yaml");
+    const validation = validateSkillScopeYaml(scopePath);
+    if (!validation.ok)
+        throw new Error(validation.error);
+    const dest = join(homeDir, ".trellis", "skills", plan.name);
+    if (plan.action === "create") {
+        if (backup)
+            backup.createDirFromSource(dest, plan.sourceDir);
+        else {
+            mkdirSync(dest, { recursive: true });
+            cpSync(plan.sourceDir, dest, { recursive: true });
+        }
     }
-    mkdirSync(dest, { recursive: true });
-    cpSync(plan.sourceDir, dest, { recursive: true });
+    const written = writeSkillScopeYaml(scopePath, plan.name, plan.scope ?? [], backup);
+    if (!written.ok)
+        throw new Error(written.error);
 }
 /** The workspace twin of `collectSkillAddPlan` (trellis-workspace-scope
  * task 3.4): same source validation, destination is `.agents/skills/`
@@ -137,29 +168,40 @@ export function collectSkillAddWorkspacePlan(name, fromPath, workspaceRoot) {
     }
 }
 export function applySkillAddWorkspacePlan(plan, workspaceRoot, backup) {
-    if (plan.action !== "create" || !plan.sourceDir)
+    if (plan.action !== "create" && !(plan.action === "already-present" && plan.scope !== undefined))
         return;
-    const dest = join(workspaceRoot, ".agents", "skills", plan.name);
-    if (backup) {
-        backup.createDirFromSource(dest, plan.sourceDir);
+    if (plan.action === "create" && !plan.sourceDir)
         return;
+    const scopePath = join(workspaceRoot, ".agents", "scope.yaml");
+    const validation = validateSkillScopeYaml(scopePath);
+    if (!validation.ok)
+        throw new Error(validation.error);
+    const dest = join(workspaceRoot, ".agents", "skills", plan.name);
+    if (plan.action === "create") {
+        if (backup)
+            backup.createDirFromSource(dest, plan.sourceDir);
+        else {
+            mkdirSync(dest, { recursive: true });
+            cpSync(plan.sourceDir, dest, { recursive: true });
+        }
     }
-    mkdirSync(dest, { recursive: true });
-    cpSync(plan.sourceDir, dest, { recursive: true });
+    const written = writeSkillScopeYaml(scopePath, plan.name, plan.scope ?? [], backup);
+    if (!written.ok)
+        throw new Error(written.error);
 }
 /** Same own-backup-session + cascade-sync posture as
  * `applySkillAddWithSync`, scoped to the workspace layer. */
 export async function applySkillAddWorkspaceWithSync(plan, workspaceRoot, opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
-    const ownSession = !opts.dryRun && !opts.backupSession && plan.action === "create" ? openBackupSession(homeDir, "skill-add") : undefined;
+    const ownSession = !opts.dryRun && !opts.backupSession && (plan.action === "create" || plan.action === "already-present" && plan.scope !== undefined) ? openBackupSession(homeDir, "skill-add") : undefined;
     const session = opts.backupSession ?? ownSession;
-    if (!opts.dryRun && plan.action === "create") {
+    if (!opts.dryRun && (plan.action === "create" || plan.action === "already-present")) {
         applySkillAddWorkspacePlan(plan, workspaceRoot, session);
     }
     ownSession?.finalize();
     const failed = plan.action === "conflict" || plan.action === "invalid-source";
     let syncReport;
-    if (!failed && plan.action === "create" && existsSync(join(homeDir, ".trellis"))) {
+    if (!failed && (plan.action === "create" || plan.scope !== undefined) && existsSync(join(homeDir, ".trellis"))) {
         syncReport = await collectSyncReport({ target: "skills", homeDir, workspaceDir: workspaceRoot, dryRun: opts.dryRun });
     }
     return { plan, ...(syncReport ? { sync: syncReport } : {}) };
@@ -174,21 +216,30 @@ export async function applySkillAddWorkspaceWithSync(plan, workspaceRoot, opts =
  */
 export async function applySkillAddWithSync(plan, opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
-    const ownSession = !opts.dryRun && !opts.backupSession && plan.action === "create" ? openBackupSession(homeDir, "skill-add") : undefined;
+    const ownSession = !opts.dryRun && !opts.backupSession && (plan.action === "create" || plan.action === "already-present" && plan.scope !== undefined) ? openBackupSession(homeDir, "skill-add") : undefined;
     const session = opts.backupSession ?? ownSession;
-    if (!opts.dryRun && plan.action === "create") {
+    if (!opts.dryRun && (plan.action === "create" || plan.action === "already-present")) {
         applySkillAddPlan(plan, homeDir, session);
     }
     ownSession?.finalize();
     const failed = plan.action === "conflict" || plan.action === "invalid-source";
     let syncReport;
-    if (!failed && plan.action === "create" && existsSync(join(homeDir, ".trellis"))) {
+    if (!failed && (plan.action === "create" || plan.scope !== undefined) && existsSync(join(homeDir, ".trellis"))) {
         syncReport = await collectSyncReport({ target: "skills", homeDir, dryRun: opts.dryRun });
     }
     return { plan, ...(syncReport ? { sync: syncReport } : {}) };
 }
 export async function runSkillAdd(name, fromPath, opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
+    const managed = existsSync(join(homeDir, ".trellis")) ? loadCanonicalSource(homeDir).managedAgents : [];
+    const selected = await requestSkillScope(opts.selection ?? {}, managed, !opts.json);
+    if ("error" in selected) {
+        if (opts.json)
+            console.log(JSON.stringify({ name, action: "invalid-source", detail: selected.error }));
+        else
+            console.error(selected.error);
+        return { exitCode: 1 };
+    }
     if (opts.workspace) {
         const workspaceRoot = opts.workspaceDir ?? findWorkspaceRoot(process.cwd());
         if (!workspaceRoot) {
@@ -196,6 +247,7 @@ export async function runSkillAdd(name, fromPath, opts = {}) {
             return { exitCode: 1 };
         }
         const plan = collectSkillAddWorkspacePlan(name, fromPath, workspaceRoot);
+        plan.scope = selected.scope;
         const { sync: syncReport } = await applySkillAddWorkspaceWithSync(plan, workspaceRoot, { homeDir, dryRun: opts.dryRun });
         const failed = plan.action === "conflict" || plan.action === "invalid-source";
         if (opts.json) {
@@ -211,6 +263,7 @@ export async function runSkillAdd(name, fromPath, opts = {}) {
         return { exitCode: failed || syncConflict ? 1 : 0 };
     }
     const plan = collectSkillAddPlan(name, fromPath, homeDir);
+    plan.scope = selected.scope;
     const { sync: syncReport } = await applySkillAddWithSync(plan, { homeDir, dryRun: opts.dryRun });
     const failed = plan.action === "conflict" || plan.action === "invalid-source";
     if (opts.json) {
@@ -289,9 +342,10 @@ export function collectSkillScopePlan(name, raw, homeDir = homedir()) {
         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 chosen = selectSkillScope(raw, canonical.managedAgents);
+    if ("error" in chosen)
+        return { name, action: "invalid-input", detail: chosen.error };
+    const selection = { scope: chosen.scope, mode: raw.all ? "all" : raw.none ? "none" : "explicit", normalizedFromFull: false };
     const skill = canonical.skills.find((candidate) => candidate.name === name);
     if (!skill)
         return { name, action: "not-found", detail: `no canonical skill named "${name}"` };
@@ -302,12 +356,11 @@ export function collectSkillScopePlan(name, raw, homeDir = homedir()) {
         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)) {
+    const summary = selection.scope.length ? selection.scope.join(", ") : "no agent (paused)";
+    if (sameScope(skill.scope, selection.scope) && Object.hasOwn(readSkillScopes(join(homeDir, ".trellis", "scope.yaml")), name)) {
         return { ...base, action: "already-set", detail: `scope is already ${summary}` };
     }
-    return { ...base, action: "updated", detail: `set scope to ${summary}${normalized}` };
+    return { ...base, action: "updated", detail: `set scope to ${summary}` };
 }
 /** Write inside a backup session so `trellis rollback` covers it, then the
  * same skills sync `add` / `remove` run — narrowing is converged by

package/dist/commands/sync.d.ts

@@ -55,6 +55,7 @@ export interface AgentSyncReport {
 }
 export interface SyncReport {
     reports: AgentSyncReport[];
+    diagnostics?: string[];
     /** Workspace root when a `.agents/` layer participated in this run. */
     workspaceRoot?: string;
 }

package/dist/commands/sync.js

@@ -83,7 +83,7 @@ export async function collectSyncReport(opts = {}) {
         reports.push({ agent: adapter.id, present: true, items: allItems, ...(warnings.length > 0 ? { warnings } : {}) });
     }
     ownSession?.finalize();
-    return { reports, ...(canonical.workspace ? { workspaceRoot: canonical.workspace.root } : {}) };
+    return { reports, ...(canonical.diagnostics.length ? { diagnostics: canonical.diagnostics } : {}), ...(canonical.workspace ? { workspaceRoot: canonical.workspace.root } : {}) };
 }
 export async function runSync(opts = {}) {
     let report;
@@ -118,6 +118,8 @@ export function printReport(report, dryRun, check = false) {
         console.log("[dry run]");
     if (check)
         console.log("[check]");
+    for (const diagnostic of report.diagnostics ?? [])
+        console.log(`  ${diagnostic}`);
     if (report.workspaceRoot) {
         console.log(`Workspace layer: ${report.workspaceRoot} (.agents/)`);
     }

package/dist/core/canonical.d.ts

@@ -27,8 +27,7 @@ export type ScopeYamlWriteResult = {
 export declare function validateSkillScopeYaml(path: string): ScopeYamlWriteResult;
 /**
  * Sets one Skill's canonical scope without rebuilding unrelated hand-authored
- * scope entries.  `undefined` removes this Skill's explicit entry and
- * therefore restores the normal all-managed default.
+ * scope entries. `undefined` removes registration, pausing distribution.
  */
 export declare function writeSkillScopeYaml(path: string, name: string, scope: Scope, backup?: BackupSession): ScopeYamlWriteResult;
 export declare function upsertServerYaml(path: string, name: string, def: McpServerDef, backup?: BackupSession): ServersYamlWriteResult;

package/dist/core/canonical.js

@@ -13,6 +13,8 @@ import { ALL_AGENTS, oauthClientMetadata } from "./types.js";
 import { fromServerDefYaml, toServerDefYaml } from "./mcpServerDef.js";
 import { loadWorkspaceLayer } from "../lib/workspace.js";
 import { mergeWorkspaceLayer } from "../lib/workspaceMerge.js";
+import { registeredSkillScope } from "../lib/skillScope.js";
+import { isBuiltinSkillName } from "../lib/builtinSkills.js";
 export { toServerDefYaml } from "./mcpServerDef.js";
 function trellisRoot(homeDir) {
     return join(homeDir, ".trellis");
@@ -166,6 +168,9 @@ export function validateSkillScopeYaml(path) {
         const doc = parseDocument(readFileSync(path, "utf-8"));
         if (doc.errors.length > 0)
             throw new Error(doc.errors.map((error) => error.message).join("; "));
+        const skills = doc.get("skills", true);
+        if (skills !== undefined && !isMap(skills))
+            throw new Error("skills must be a map of names to agent lists");
         return { ok: true };
     }
     catch (err) {
@@ -174,8 +179,7 @@ export function validateSkillScopeYaml(path) {
 }
 /**
  * Sets one Skill's canonical scope without rebuilding unrelated hand-authored
- * scope entries.  `undefined` removes this Skill's explicit entry and
- * therefore restores the normal all-managed default.
+ * scope entries. `undefined` removes registration, pausing distribution.
  */
 export function writeSkillScopeYaml(path, name, scope, backup) {
     if (!existsSync(path) && scope === undefined)
@@ -428,9 +432,6 @@ export function ensureShellEnvSource(rcPath, envFilePath, backup) {
     mkdirSync(dirname(rcPath), { recursive: true });
     persistText(rcPath, `${existing}${separator}${block}`, backup);
 }
-/** `undefined` if the name has no entry in scope.yaml's map — "shared with
- * all managed agents by default. A recognized but empty list is left as
- * authored (an explicitly agent-less scope), not coerced to "all". */
 /** Missing file and `agents: []` both resolve to `[]` — zero managed
  * agents, never "everyone." An unrecognized id is dropped with a
  * diagnostic, same posture as an unrecognized scope.yaml agent id. */
@@ -455,9 +456,9 @@ function scopeFor(map, name) {
     return map?.[name];
 }
 function validAgentIds(scope) {
-    if (!scope)
+    if (scope === undefined)
         return true;
-    return scope.every((id) => ALL_AGENTS.includes(id));
+    return Array.isArray(scope) && scope.every((id) => ALL_AGENTS.includes(id));
 }
 /**
  * Load-time literal-value scan for OAuth client metadata
@@ -497,7 +498,13 @@ export function loadCanonicalSource(arg = {}) {
     const scopeYaml = loadScopeYaml(join(root, "scope.yaml"));
     const skillDirs = listSkillDirs(join(root, "skills"));
     const knownSkillNames = new Set(skillDirs.map((s) => s.name));
-    const skills = skillDirs.map(({ name, dir }) => ({ name, dir, scope: scopeFor(scopeYaml.skills, name) }));
+    const skills = skillDirs.map(({ name, dir }) => {
+        const declared = scopeFor(scopeYaml.skills, name);
+        if (declared === undefined && !isBuiltinSkillName(name)) {
+            diagnostics.push(`scope.yaml: skill "${name}" has no registered agents — distribution paused; run trellis skill scope ${name} --agents <ids>`);
+        }
+        return { name, dir, scope: isBuiltinSkillName(name) && declared === undefined ? undefined : registeredSkillScope(declared) };
+    });
     const agentFiles = listMarkdownFiles(join(root, "agents"));
     const knownAgentProfileNames = new Set(agentFiles.map((a) => a.name));
     const agents = agentFiles.map(({ name, file }) => ({
@@ -523,7 +530,7 @@ export function loadCanonicalSource(arg = {}) {
                 diagnostics.push(`scope.yaml: "${section}.${name}" does not match any known ${section.slice(0, -1)} — ignored`);
             }
             else if (!validAgentIds(map?.[name])) {
-                diagnostics.push(`scope.yaml: "${section}.${name}" lists an unrecognized agent id — ignored`);
+                diagnostics.push(`scope.yaml: "${section}.${name}" lists an unrecognized agent id${section === "skills" ? " — distribution paused" : " — ignored"}`);
             }
         }
     }

package/dist/core/types.d.ts

@@ -39,11 +39,9 @@ export declare function oauthClientMetadata(auth: McpAuthMode | McpAuthConfig |
 export type AgentId = "claude-code" | "codex" | "kiro" | "pi" | "kimi-code" | "zcode";
 export declare const ALL_AGENTS: readonly AgentId[];
 /**
- * Every scopable item (skill, subagent, memory entry, MCP server) defaults
- * to all managed agents when `scope` is omitted — sharing everywhere is the
- * common case Trellis exists for; restricting to specific agents is the
- * exception and must be declared explicitly. See docs/architecture.md
- * "Private / agent-specific capabilities".
+ * Omitted scope resolves to the managed set. Custom skills are registered
+ * explicitly by the canonical/workspace loaders: missing or invalid skill
+ * registration becomes `[]` (paused). Other capability defaults are unchanged.
  */
 export type Scope = AgentId[] | undefined;
 /**
@@ -69,7 +67,9 @@ export interface McpServerDef {
     /** http/sse only */
     url?: string;
     /**
-     * http/sse only. Values are `${VAR}` references, same discipline as
+     * http/sse only. Values are `${VAR}` or `${mxenv://profile/KEY}` templates,
+     * the latter requiring Trellis-hosted resolution (gateway/runtime/pi).
+     * Same discipline as
      * `env` — never a real value. Codex has no generic headers concept;
      * only the single shape `{ Authorization: "Bearer ${VAR}" }` is
      * expressible there (trellis-mcp-transport-auth design.md D4) — any
@@ -190,7 +190,8 @@ export interface SkillRef {
      * filename is case-sensitive on at least one target agent (Codex). */
     dir: string;
     /**
-     * Omit for "all agents" (the default). Deliberately NOT read from
+     * Explicit applicable agents; unregistered custom skills load as `[]`.
+     * Package-owned built-ins may supply their own default. NOT read from
      * SKILL.md's own frontmatter — Codex validates SKILL.md frontmatter
      * against an allow-list of known keys and rejects unknown ones (see
      * docs/research.md), so a Trellis-only field embedded there would break

package/dist/lib/envVarNames.d.ts

@@ -7,7 +7,11 @@
  * still more machinery than this one narrow extraction needs.
  */
 import type { McpServerDef } from "../core/types.js";
-/** Every `${NAME}` occurrence in a string — a header value can in
+export declare function replaceTemplateVars(value: string, replace: (entry: string) => string): string;
+/** Report only the header's name, never a potentially sensitive template. */
+export declare function invalidHeaderTemplate(headers: Record<string, string> | undefined): string | undefined;
+/** Every `${NAME}` or `${mxenv://profile/KEY}` occurrence in a string,
+ * including malformed placeholders for validation — a header value can in
  * principle reference more than one name (trellis-mcp-transport-auth
  * design.md D6), same extraction `env`'s single-name-per-value case
  * already needed, just generalized. */

package/dist/lib/envVarNames.js

@@ -6,8 +6,21 @@
  * there is no round-trip-fidelity concern here, but a full parser is
  * still more machinery than this one narrow extraction needs.
  */
-const TEMPLATE_VAR_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
-/** Every `${NAME}` occurrence in a string — a header value can in
+// Keep malformed placeholders visible too: a misspelled reference scheme
+// must reach validation rather than silently survive as literal header text.
+const TEMPLATE_VAR_RE = /\$\{([^{}]*)\}/g;
+export function replaceTemplateVars(value, replace) {
+    return value.replace(TEMPLATE_VAR_RE, (_match, entry) => replace(entry));
+}
+/** Report only the header's name, never a potentially sensitive template. */
+export function invalidHeaderTemplate(headers) {
+    return Object.entries(headers ?? {}).find(([, value]) => {
+        const literal = replaceTemplateVars(value, () => "");
+        return literal.includes("${") || /mx-?env:\/\//.test(literal);
+    })?.[0];
+}
+/** Every `${NAME}` or `${mxenv://profile/KEY}` occurrence in a string,
+ * including malformed placeholders for validation — a header value can in
  * principle reference more than one name (trellis-mcp-transport-auth
  * design.md D6), same extraction `env`'s single-name-per-value case
  * already needed, just generalized. */
@@ -22,7 +35,14 @@ export function extractTemplateVarNames(value) {
  * same answer to "what names does this def reference," not two
  * separately-maintained collections. */
 export function declaredEnvNames(def) {
+    // RAW entries, including `envAliases` sources (mx-env-secret-source
+    // secrets-audit delta): consumers that RESOLVE must see the original
+    // `mxenv://` text so references go through composition, then look the
+    // result up by delivered name; consumers that want the delivered NAMES
+    // map through `deliveredName` at their own use site (e.g. Kiro).
     const names = new Set(def.env ?? []);
+    for (const source of Object.values(def.envAliases ?? {}))
+        names.add(source);
     for (const value of Object.values(def.headers ?? {})) {
         for (const name of extractTemplateVarNames(value))
             names.add(name);

package/dist/lib/mcpConnect.d.ts

@@ -45,7 +45,7 @@ export declare function connectWithCleanup<T, TTransport extends {
     connect(transport: TTransport): Promise<unknown>;
 }, transport: TTransport, timeoutMs: number, message: string): Promise<T>;
 export declare function connectStdio(def: McpServerDef, secretsPolicy: SecretsPolicy, timeoutMs: number, clientInfo: McpClientInfo): Promise<Client>;
-export declare function resolveHeaders(def: McpServerDef, secretsPolicy: SecretsPolicy): Record<string, string> | undefined;
+export declare function resolveHeaders(def: McpServerDef, secretsPolicy: SecretsPolicy): Promise<Record<string, string> | undefined>;
 export declare function connectHttp(def: McpServerDef, secretsPolicy: SecretsPolicy, timeoutMs: number, clientInfo: McpClientInfo, authProvider?: AuthProvider): Promise<Client>;
 export declare function connectSse(def: McpServerDef, secretsPolicy: SecretsPolicy, timeoutMs: number, clientInfo: McpClientInfo, authProvider?: AuthProvider): Promise<Client>;
 /**