@kuznai/inception-engine 0.19.0 → 0.21.0

package/dist/src/core/preflight.js

@@ -0,0 +1,296 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
+import { describeCapabilityConfidence, planCapabilityForDeploy, } from "./capabilities.js";
+import { resolveRuntimePaths } from "./runtime-paths.js";
+const BUDGET_WARN_BYTES = 50 * 1024; // 50 KB
+async function detectEnterpriseManagement(agentId, home) {
+    if (!AGENT_REGISTRY_BY_ID[agentId]?.enterprisePolicyDetection)
+        return null;
+    // Check for common GitHub Enterprise environment variables
+    if (process.env.GITHUB_ENTERPRISE_URL ||
+        process.env.GH_ENTERPRISE_TOKEN ||
+        process.env.GITHUB_TOKEN_TYPE === "enterprise") {
+        return "GitHub Enterprise environment variables detected. Enterprise policies may override local configurations.";
+    }
+    const { xdgConfig, localAppdata } = resolveRuntimePaths(home);
+    const configPath = process.platform === "win32"
+        ? path.join(localAppdata, "github-copilot", "hosts.json")
+        : path.join(xdgConfig, "github-copilot", "hosts.json");
+    try {
+        const content = await readFile(configPath, "utf8");
+        const hosts = JSON.parse(content);
+        const hostNames = Object.keys(hosts);
+        const enterpriseHosts = hostNames.filter((h) => h !== "github.com" && h !== "localhost");
+        if (enterpriseHosts.length > 0) {
+            return `GitHub Copilot is authenticated against enterprise host(s): ${enterpriseHosts.join(", ")}. Enterprise policies may override local configurations.`;
+        }
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT" &&
+            code !== "EACCES" &&
+            code !== "EPERM" &&
+            code !== undefined) {
+            throw err;
+        }
+    }
+    return null;
+}
+/**
+ * Reads ~/.gemini/settings.json and warns when `instructionFilename` is set
+ * to a value other than "GEMINI.md". If the override is in effect, inception-
+ * engine's agentRules deployment to GEMINI.md will be silently ignored by the
+ * agent at runtime.
+ */
+async function detectGeminiCustomInstructionFilename(home) {
+    const settingsPath = path.join(home, ".gemini", "settings.json");
+    try {
+        const raw = await readFile(settingsPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === "object" &&
+            parsed !== null &&
+            typeof parsed.instructionFilename ===
+                "string") {
+            const configured = parsed
+                .instructionFilename;
+            if (configured !== "GEMINI.md") {
+                return {
+                    kind: "config-authority",
+                    message: `Agent "gemini-cli": settings.json sets instructionFilename to "${configured}" but inception-engine deploys agentRules to "GEMINI.md". The deployed rules file may not be loaded by the agent. Remove the override or align the deploy target.`,
+                };
+            }
+        }
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT" && code !== "EACCES" && code !== "EPERM") {
+            throw err;
+        }
+    }
+    return null;
+}
+function groupRulesByPath(rulesForAgent) {
+    const entriesByPath = new Map();
+    for (const entry of rulesForAgent ?? []) {
+        const list = entriesByPath.get(entry.path) ?? [];
+        list.push({ name: entry.name, scope: entry.scope });
+        entriesByPath.set(entry.path, list);
+    }
+    return entriesByPath;
+}
+function detectScopeOverlaps(agentId, rulesForAgent) {
+    const warnings = [];
+    const entriesByPath = groupRulesByPath(rulesForAgent);
+    for (const [path, list] of entriesByPath) {
+        const scopes = new Set(list.map((l) => l.scope));
+        if (scopes.size < 2)
+            continue;
+        const scopeList = Array.from(scopes).sort();
+        for (let i = 0; i < scopeList.length; i++) {
+            for (let j = i + 1; j < scopeList.length; j++) {
+                const entryB = list.find((l) => l.scope === scopeList[j]);
+                if (entryB) {
+                    warnings.push({
+                        kind: "precedence",
+                        message: `Agent "${agentId}" has agentRules entry "${entryB.name}" deployed to both ${scopeList[i]} and ${scopeList[j]} scope from the same source path "${path}". The file will be written to two distinct targets — verify this is intentional and not a copy-paste mistake.`,
+                    });
+                }
+            }
+        }
+    }
+    return warnings;
+}
+function detectMultipleActiveInstructionScopes(agentId, rulesForAgent) {
+    const activeScopes = Array.from(new Set((rulesForAgent ?? []).map((e) => e.scope))).sort();
+    if (activeScopes.length <= 1)
+        return [];
+    const scopeDescriptions = activeScopes
+        .map((s) => {
+        const entries = (rulesForAgent ?? []).filter((e) => e.scope === s);
+        return `${s} [${entries.map((e) => `"${e.name}"`).join(", ")}]`;
+    })
+        .join(" and ");
+    return [
+        {
+            kind: "precedence",
+            message: `Agent "${agentId}" will have multiple instruction files active simultaneously across ${activeScopes.length} scopes: ${scopeDescriptions}. All will be loaded by the agent — ensure the content is intended to stack and does not conflict.`,
+        },
+    ];
+}
+function detectInstructionPrecedence(detectedAgents, manifest) {
+    const warnings = [];
+    for (const agentId of detectedAgents) {
+        const rulesForAgent = (manifest.agentRules ?? []).filter((e) => e.agents.includes(agentId));
+        warnings.push(...detectScopeOverlaps(agentId, rulesForAgent));
+        warnings.push(...detectMultipleActiveInstructionScopes(agentId, rulesForAgent));
+    }
+    return warnings;
+}
+async function detectInstructionBudgetRisk(detectedAgents, manifest, sourceDir) {
+    const warnings = [];
+    const checkedPaths = new Set();
+    async function checkEntry(entryPath, label, agentIds) {
+        if (!agentIds.some((id) => detectedAgents.includes(id)))
+            return;
+        const sourcePath = path.resolve(sourceDir, entryPath);
+        if (checkedPaths.has(sourcePath))
+            return;
+        checkedPaths.add(sourcePath);
+        try {
+            const fileStat = await stat(sourcePath);
+            if (fileStat.size > BUDGET_WARN_BYTES) {
+                const sizeKb = (fileStat.size / 1024).toFixed(1);
+                warnings.push({
+                    kind: "budget",
+                    message: `${label} source "${entryPath}" is ${sizeKb} KB — large instruction files risk crowding out code context in the agent's context window. Consider splitting into smaller focused files.`,
+                });
+            }
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "ENOENT" && code !== "EACCES" && code !== "EPERM")
+                throw err;
+            // Missing/unreadable files are silently skipped; compileAgentRuleActions
+            // will produce the proper UserError during action compilation.
+        }
+    }
+    const entries = [];
+    for (const entry of manifest.agentRules ?? []) {
+        entries.push({
+            path: entry.path,
+            label: "agentRules",
+            agents: entry.agents,
+        });
+    }
+    for (const entry of manifest.agentDefinitions ?? []) {
+        entries.push({
+            path: entry.path,
+            label: "agentDefinitions",
+            agents: entry.agents,
+        });
+    }
+    await Promise.all(entries.map((e) => checkEntry(e.path, e.label, e.agents)));
+    return warnings;
+}
+function pushCapabilityWarning(acc, kind, message) {
+    if (acc.seen.has(`${kind}:${message}`))
+        return;
+    acc.seen.add(`${kind}:${message}`);
+    acc.warnings.push({ kind, message });
+}
+function collectPlannedSurfaceWarnings(acc, agentId, capability) {
+    const agent = AGENT_REGISTRY_BY_ID[agentId];
+    if (!agent?.unsupportedSurfaces ||
+        (capability !== "mcpServers" && capability !== "permissions")) {
+        return;
+    }
+    for (const surface of agent.unsupportedSurfaces) {
+        if (surface.status === "planned") {
+            pushCapabilityWarning(acc, "info", `Agent "${agentId}": ${surface.reason ?? surface.plannedSurface}`);
+        }
+        else if (surface.status === "unsupported") {
+            pushCapabilityWarning(acc, "config-authority", `Agent "${agentId}": ${surface.reason ?? surface.schemaLabel}`);
+        }
+    }
+}
+function collectCapabilityWarningsForAgent(acc, agentId, capability, entryName, targetAgents, scope) {
+    const plan = planCapabilityForDeploy({
+        agentId,
+        capability,
+        entryName,
+        targetAgentIds: targetAgents,
+        scope,
+    });
+    if (plan.outcome === "warn") {
+        pushCapabilityWarning(acc, "info", plan.warning.message);
+        return;
+    }
+    if (capability !== "skills") {
+        const confidence = describeCapabilityConfidence(agentId, capability, scope);
+        if (confidence.message) {
+            pushCapabilityWarning(acc, "config-authority", confidence.message);
+        }
+    }
+    collectPlannedSurfaceWarnings(acc, agentId, capability);
+}
+function collectCapabilityWarningsForTargets(acc, targetAgents, capability, entryName, scope) {
+    for (const agentId of targetAgents) {
+        collectCapabilityWarningsForAgent(acc, agentId, capability, entryName, targetAgents, scope);
+    }
+}
+function collectManifestCapabilityWarnings(manifest, detectedAgents) {
+    const acc = {
+        warnings: [],
+        seen: new Set(),
+    };
+    for (const entry of manifest.skills) {
+        collectCapabilityWarningsForTargets(acc, entry.agents.filter((agentId) => detectedAgents.includes(agentId)), "skills", entry.name);
+    }
+    for (const entry of manifest.mcpServers ?? []) {
+        collectCapabilityWarningsForTargets(acc, entry.agents.filter((agentId) => detectedAgents.includes(agentId)), "mcpServers", entry.name, entry.scope);
+    }
+    for (const entry of manifest.agentRules ?? []) {
+        collectCapabilityWarningsForTargets(acc, entry.agents.filter((agentId) => detectedAgents.includes(agentId)), "agentRules", entry.name, entry.scope);
+    }
+    for (const entry of manifest.permissions ?? []) {
+        collectCapabilityWarningsForTargets(acc, entry.agents.filter((agentId) => detectedAgents.includes(agentId)), "permissions", entry.name);
+    }
+    for (const entry of manifest.agentDefinitions ?? []) {
+        collectCapabilityWarningsForTargets(acc, entry.agents.filter((agentId) => detectedAgents.includes(agentId)), "agentDefinitions", entry.name, entry.scope);
+    }
+    return acc.warnings;
+}
+function detectCapabilityPlanningWarnings(manifest, detectedAgents) {
+    return collectManifestCapabilityWarnings(manifest, detectedAgents);
+}
+async function collectAgentWarnings(agentId, manifest, home) {
+    const agent = AGENT_REGISTRY_BY_ID[agentId];
+    if (!agent)
+        return [];
+    const warnings = [];
+    const skillConfidence = describeCapabilityConfidence(agentId, "skills");
+    if (skillConfidence.confidence === "implementation-only" ||
+        skillConfidence.confidence === "provisional") {
+        warnings.push({
+            kind: "config-authority",
+            message: skillConfidence.message ??
+                `Agent "${agentId}" skill support is ${skillConfidence.confidence}.`,
+        });
+    }
+    const enterpriseWarning = await detectEnterpriseManagement(agentId, home);
+    if (enterpriseWarning) {
+        warnings.push({
+            kind: "policy",
+            message: `Agent "${agentId}": ${enterpriseWarning}`,
+        });
+    }
+    else if (agent.policyNote &&
+        !agent.policyNote
+            .toLowerCase()
+            .includes("organization policies may override")) {
+        warnings.push({
+            kind: "policy",
+            message: `Agent "${agentId}": ${agent.policyNote}`,
+        });
+    }
+    if (agentId === "gemini-cli") {
+        const hasGeminiRules = (manifest.agentRules ?? []).some((e) => e.agents.includes("gemini-cli"));
+        if (hasGeminiRules) {
+            const filenameWarning = await detectGeminiCustomInstructionFilename(home);
+            if (filenameWarning)
+                warnings.push(filenameWarning);
+        }
+    }
+    return warnings;
+}
+export async function runPreflight(options, manifest, home, detectedAgents) {
+    const warnings = [];
+    for (const agentId of detectedAgents) {
+        warnings.push(...(await collectAgentWarnings(agentId, manifest, home)));
+    }
+    warnings.push(...detectCapabilityPlanningWarnings(manifest, detectedAgents));
+    warnings.push(...detectInstructionPrecedence(detectedAgents, manifest));
+    warnings.push(...(await detectInstructionBudgetRisk(detectedAgents, manifest, options.directory)));
+    return warnings;
+}

package/dist/{core → src/core}/revert.js

@@ -1,8 +1,10 @@
 import { lstat, readFile, rm, unlink, writeFile } from "node:fs/promises";
 import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
 import { logger } from "../logger.js";
+import * as frontmatterAdapter from "./adapters/frontmatter.js";
 import { compileAgentDefinitionReverts, compileAgentRuleReverts, compileMcpServerReverts, compilePermissionsReverts, } from "./adapters/index.js";
 import { revertTomlMcpPatch } from "./adapters/toml.js";
+import { applyUndoPatch } from "./merge-patch.js";
 import { lookupDeployment, unregisterDeployment, } from "./ownership.js";
 import { resolveAgentSkillPath } from "./resolve.js";
 import { resolveTargetTemplate } from "./runtime-paths.js";
@@ -112,24 +114,6 @@ async function readJsonConfig(filePath) {
     }
     return parsed;
 }
-function isPlainObject(v) {
-    return typeof v === "object" && v !== null && !Array.isArray(v);
-}
-function applyUndoPatch(current, undoPatch) {
-    const restored = { ...current };
-    for (const [key, originalValue] of Object.entries(undoPatch)) {
-        if (originalValue === null) {
-            delete restored[key];
-        }
-        else if (isPlainObject(originalValue) && isPlainObject(restored[key])) {
-            restored[key] = applyUndoPatch(restored[key], originalValue);
-        }
-        else {
-            restored[key] = originalValue;
-        }
-    }
-    return restored;
-}
 function lstatOutcome(err) {
     if (err.code === "ENOENT") {
         return { outcome: "skip" };
@@ -157,14 +141,7 @@ export async function executeRevert(actions, dryRun, verbose, home, deps = {}) {
                 result = await revertTomlPatch(action, dryRun, verbose, home, planned, deps);
                 break;
             case "frontmatter-emit":
-                // Frontmatter-emit files are fully managed by inception — revert
-                // deletes the file, same as a file-write revert.
-                result = await revertFileWrite({
-                    kind: "file-write",
-                    skill: action.skill,
-                    agent: action.agent,
-                    target: action.target,
-                }, dryRun, verbose, home, planned, deps);
+                result = await revertFrontmatterEmit(action, dryRun, verbose, home, planned, deps);
                 break;
             default: {
                 throw new Error(`Unhandled revert action kind: ${action.kind}`);
@@ -179,6 +156,89 @@ export async function executeRevert(actions, dryRun, verbose, home, deps = {}) {
         planned,
     };
 }
+function isManagedFrontmatterEntry(entry, action) {
+    return (entry !== null &&
+        entry.kind === "frontmatter-emit" &&
+        entry.skill === action.skill &&
+        entry.agent === action.agent);
+}
+async function loadManagedFrontmatterEntry(action, home, deps) {
+    const entry = await lookupDeployment(home, action.target, deps.registry);
+    return isManagedFrontmatterEntry(entry, action) ? entry : null;
+}
+function planFrontmatterRevert(action, frontmatterEntry, planned) {
+    planned.push({
+        verb: "unapply-patch",
+        kind: "frontmatter-emit",
+        skill: action.skill,
+        agent: action.agent,
+        target: action.target,
+        patch: frontmatterEntry.undoPatch,
+    });
+    return { outcome: "ok" };
+}
+async function applyFrontmatterRevert(action, frontmatterEntry) {
+    const current = await frontmatterAdapter.readFrontmatterDocumentFile(action.target);
+    const restoredFrontmatter = applyUndoPatch(current.attributes, frontmatterEntry.undoPatch ?? {});
+    const shouldDeleteFile = frontmatterEntry.created === true &&
+        !frontmatterEntry.hadFrontmatter &&
+        Object.keys(restoredFrontmatter).length === 0 &&
+        current.body.trim() === "";
+    if (shouldDeleteFile) {
+        await unlink(action.target);
+        return { shouldDeleteFile };
+    }
+    const restoredContent = frontmatterAdapter.buildMarkdownDocument(restoredFrontmatter, current.body, { hasFrontmatter: frontmatterEntry.hadFrontmatter ?? false });
+    await writeFile(action.target, restoredContent, "utf-8");
+    return { shouldDeleteFile };
+}
+async function revertFrontmatterEmit(action, dryRun, verbose, home, planned, deps) {
+    const label = `${action.skill} -> ${action.agent}`;
+    try {
+        await lstat(action.target);
+    }
+    catch (err) {
+        const result = lstatOutcome(err);
+        if (result.outcome === "skip") {
+            logger.skip(label, "(not found, skipping)");
+            return result;
+        }
+        logger.fail(label, result.error);
+        return result;
+    }
+    const frontmatterEntry = await loadManagedFrontmatterEntry(action, home, deps);
+    if (!frontmatterEntry) {
+        logger.warn(label, `skipping: ${action.target} is not in the deployment registry — not managed by inception-engine`);
+        return { outcome: "skip" };
+    }
+    if (!frontmatterEntry.undoPatch) {
+        return revertFileWrite({
+            kind: "file-write",
+            skill: action.skill,
+            agent: action.agent,
+            target: action.target,
+        }, dryRun, verbose, home, planned, deps);
+    }
+    if (dryRun) {
+        return planFrontmatterRevert(action, frontmatterEntry, planned);
+    }
+    try {
+        const { shouldDeleteFile } = await applyFrontmatterRevert(action, frontmatterEntry);
+        await unregisterDeployment(home, action.target, deps.registry);
+        logger.ok(label);
+        if (verbose) {
+            logger.detail(shouldDeleteFile
+                ? `removed: ${action.target}`
+                : `unapplied frontmatter patch from: ${action.target}`);
+        }
+        return { outcome: "ok" };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.fail(label, msg);
+        return { outcome: "fail", error: msg };
+    }
+}
 async function executeRevertAction(action, dryRun, verbose, home, planned, deps) {
     const label = `${action.skill} -> ${action.agent}`;
     try {

package/dist/{core → src/core}/validation.js

@@ -135,6 +135,23 @@ function validateCodexPermissions(config, entryName) {
         throw new UserError("DEPLOY_FAILED", `permissions entry "${entryName}" for agent "codex" must define "approval_policy" as one of: ${CODEX_APPROVAL_POLICY_VALUES.join(", ")}`);
     }
 }
+function validateOpenCodePermissions(config, entryName) {
+    rejectUnknownKeys(config, ["permissions"], entryName, "opencode");
+    const perms = config.permissions;
+    if (perms === undefined)
+        return;
+    if (typeof perms !== "object" || perms === null || Array.isArray(perms)) {
+        throw new UserError("DEPLOY_FAILED", `permissions entry "${entryName}" for agent "opencode" must define "permissions" as an object`);
+    }
+    const permsObj = perms;
+    for (const key of ["allow", "ask", "deny"]) {
+        const val = permsObj[key];
+        if (val !== undefined &&
+            (!Array.isArray(val) || val.some((item) => typeof item !== "string"))) {
+            throw new UserError("DEPLOY_FAILED", `permissions entry "${entryName}" for agent "opencode" must define "permissions.${key}" as an array of strings when present`);
+        }
+    }
+}
 export function validatePermissionsConfigShape(config, entryName, agentId) {
     if (agentId === "claude-code") {
         validateClaudeCodePermissions(config, entryName);
@@ -142,6 +159,9 @@ export function validatePermissionsConfigShape(config, entryName, agentId) {
     else if (agentId === "codex") {
         validateCodexPermissions(config, entryName);
     }
+    else if (agentId === "opencode") {
+        validateOpenCodePermissions(config, entryName);
+    }
 }
 export function validateAgentRuleMarkdownPath(manifestPath, agentId) {
     const extension = path.extname(manifestPath).toLowerCase();
@@ -198,6 +218,17 @@ function validateGithubCopilotRequirements(attributes, manifestPath) {
     if (!(hasTools || hasInstructions)) {
         throw new UserError("DEPLOY_FAILED", `Instruction file "${manifestPath}" for agent "github-copilot" must define "tools" or "instructions" in frontmatter`);
     }
+    if (hasTools) {
+        const tools = attributes.tools;
+        if (!Array.isArray(tools)) {
+            throw new UserError("DEPLOY_FAILED", `Instruction file "${manifestPath}" for agent "github-copilot" has a "tools" field that must be an array`);
+        }
+        for (const tool of tools) {
+            if (typeof tool !== "string") {
+                throw new UserError("DEPLOY_FAILED", `Instruction file "${manifestPath}" for agent "github-copilot" has a "tools" entry that must be a string`);
+            }
+        }
+    }
 }
 function validateAntigravityRequirements(attributes, manifestPath) {
     const mcpServers = attributes["mcp-servers"] ?? attributes.mcpServers;

package/dist/{errors.d.ts → src/errors.d.ts}

@@ -1,5 +1,7 @@
 export type ErrorCode = "INVALID_ARGS" | "MANIFEST_INVALID" | "DEPLOY_FAILED" | "RESOLVE_FAILED";
 export declare class UserError extends Error {
     readonly code: ErrorCode;
-    constructor(code: ErrorCode, message: string);
+    constructor(code: ErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
 }

package/dist/{errors.js → src/errors.js}

@@ -1,7 +1,7 @@
 export class UserError extends Error {
     code;
-    constructor(code, message) {
-        super(message);
+    constructor(code, message, options) {
+        super(message, options);
         this.name = "UserError";
         this.code = code;
     }

package/dist/{schemas → src/schemas}/manifest.d.ts

@@ -59,6 +59,11 @@ export declare const McpServerEntrySchema: z.ZodObject<{
         "github-copilot": "github-copilot";
     }>>>, z.ZodTransform<("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[], ("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[]>>;
     config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    scope: z.ZodDefault<z.ZodEnum<{
+        global: "global";
+        repo: "repo";
+        workspace: "workspace";
+    }>>;
 }, z.core.$strip>;
 export declare const AgentRuleEntrySchema: z.ZodObject<{
     name: z.ZodString;
@@ -100,6 +105,11 @@ export declare const AgentDefinitionEntrySchema: z.ZodObject<{
         "github-copilot": "github-copilot";
     }>>>, z.ZodTransform<("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[], ("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[]>>;
     path: z.ZodString;
+    scope: z.ZodDefault<z.ZodEnum<{
+        global: "global";
+        repo: "repo";
+        workspace: "workspace";
+    }>>;
 }, z.core.$strip>;
 export declare const ManifestSchema: z.ZodObject<{
     skills: z.ZodArray<z.ZodObject<{
@@ -151,6 +161,11 @@ export declare const ManifestSchema: z.ZodObject<{
             "github-copilot": "github-copilot";
         }>>>, z.ZodTransform<("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[], ("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[]>>;
         config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        scope: z.ZodDefault<z.ZodEnum<{
+            global: "global";
+            repo: "repo";
+            workspace: "workspace";
+        }>>;
     }, z.core.$strip>>>;
     agentRules: z.ZodDefault<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -192,6 +207,11 @@ export declare const ManifestSchema: z.ZodObject<{
             "github-copilot": "github-copilot";
         }>>>, z.ZodTransform<("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[], ("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[]>>;
         path: z.ZodString;
+        scope: z.ZodDefault<z.ZodEnum<{
+            global: "global";
+            repo: "repo";
+            workspace: "workspace";
+        }>>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type SkillEntry = z.infer<typeof SkillEntrySchema>;

package/dist/{schemas → src/schemas}/manifest.js

@@ -83,6 +83,12 @@ export const McpServerEntrySchema = z.object({
     // Raw server descriptor passed verbatim to each agent adapter.
     // Adapters are responsible for validating the shape they need.
     config: z.record(z.string(), z.unknown()),
+    // Deployment scope: "global" (default) targets the agent's user-level MCP
+    // config file. "repo" and "workspace" target repo- or workspace-relative
+    // config files for agents that support them (e.g. GitHub Copilot's
+    // .vscode/mcp.json). For agents without scope-specific surfaces the
+    // adapter falls back to the global surface or emits a warning.
+    scope: z.enum(["global", "repo", "workspace"]).default("global"),
 });
 export const AgentRuleEntrySchema = z.object({
     name: nameField,
@@ -103,6 +109,7 @@ export const PermissionsEntrySchema = z.object({
     // Raw permission config payload validated per agent by the permissions adapter.
     // For claude-code: { permissions: { allow?: string[], deny?: string[] } }
     // For codex: { approval_policy?: "auto" | "manual" | "suggest" | "on-failure" }
+    // For opencode: { permissions: { allow?: string[], ask?: string[], deny?: string[] } }
     config: z.record(z.string(), z.unknown()),
 });
 export const AgentDefinitionEntrySchema = z.object({
@@ -112,6 +119,10 @@ export const AgentDefinitionEntrySchema = z.object({
     // Must be a .md or .markdown file. Structural requirements (e.g. YAML
     // frontmatter) are validated per agent requirements by the adapter.
     path: sourcePathField,
+    // Deployment scope: "global" targets the agent's home-directory definition
+    // directory (if supported), "repo" targets the project-root definition directory
+    // within the deployed repository (default).
+    scope: z.enum(["global", "repo", "workspace"]).default("repo"),
 });
 export const ManifestSchema = z.object({
     skills: z.array(SkillEntrySchema).superRefine((skills, ctx) => {