@kuznai/inception-engine 0.20.0 → 0.21.0

package/README.md

@@ -271,6 +271,8 @@ Global targets where supported:
 
 For GitHub Copilot, deploy also records migration from the legacy `{repo}/.github/agents/{name}.agent.md` path so older installs can be cleaned up safely.
 
+For GitHub Copilot, the `tools` YAML frontmatter field in agent definition files declares which MCP tools and built-in Copilot tools the agent has access to (agent-level tool mapping). Inception-engine validates that `tools`, when present, is an array of strings. Deploy agent-level tool mappings through `agentDefinitions` by including the `tools` field in your source file's frontmatter - no separate manifest section is needed.
+
 Revert removes the deployed agent-definition file.
 
 ## Creating Skills

package/dist/src/config/agents.js

@@ -472,6 +472,12 @@ export const AGENT_REGISTRY = [
                 windows: ["{workspace}", "CLAUDE.md"],
             },
         },
+        mcpDevcontainerSupport: {
+            status: "planned",
+            schemaLabel: "devcontainer.json MCP surface",
+            plannedSurface: "devcontainer.json customizations.vscode.mcp.servers",
+            reason: 'devcontainer.json MCP support is planned — use scope: "repo" or scope: "workspace" to target .vscode/mcp.json in the meantime',
+        },
         permissionsSupport: {
             status: "unsupported",
             schemaLabel: "global permissions surface",
@@ -485,7 +491,27 @@ export const AGENT_REGISTRY = [
                 windows: ["{repo}", ".github", "copilot", "agents", "{name}.md"],
             },
         },
+        // GitHub Copilot agent definitions declare MCP tool access via a top-level
+        // 'tools' array in YAML frontmatter. This surface is deployed through
+        // agentDefinitions - no separate deploy action is emitted.
+        mcpAgentFrontmatterSupport: {
+            status: "supported",
+            schemaLabel: "agent definition frontmatter tools field",
+            surfaceKind: { kind: "native" },
+            path: {
+                posix: ["{repo}", ".github", "copilot", "agents", "{name}.md"],
+                windows: ["{repo}", ".github", "copilot", "agents", "{name}.md"],
+            },
+        },
         policyNote: "Organization policies may override locally deployed configuration. Verify with your GitHub org admin if deployed skills or rules are not active.",
+        unsupportedSurfaces: [
+            {
+                status: "planned",
+                schemaLabel: "devcontainer.json MCP surface",
+                plannedSurface: "devcontainer.json customizations.vscode.mcp.servers",
+                reason: 'devcontainer.json MCP support is planned — use scope: "repo" or scope: "workspace" to target .vscode/mcp.json in the meantime',
+            },
+        ],
         instructionFrontmatterRequired: true,
         enterprisePolicyDetection: true,
     },

package/dist/src/core/adapters/index.js

@@ -3,28 +3,23 @@ import { compileMcpServerActions, compileMcpServerReverts } from "./mcp.js";
 import { compilePermissionsActions, compilePermissionsReverts, } from "./permissions.js";
 import { compileAgentRuleActions, compileAgentRuleReverts } from "./rules.js";
 export { compileAgentDefinitionReverts, compileAgentRuleReverts, compileMcpServerReverts, compilePermissionsReverts, };
+async function compileAll(entries, fn) {
+    const results = await Promise.all(entries.map(fn));
+    return {
+        actions: results.flatMap((r) => r.actions),
+        warnings: results.flatMap((r) => r.warnings),
+    };
+}
 export async function compileAdapterActions(mcpServers, agentRules, permissions, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, agentDefinitions, workspace) {
     const actions = [];
     const warnings = [];
-    for (const entry of mcpServers) {
-        const r = compileMcpServerActions(entry, detectedAgents, home, repo, workspace);
-        actions.push(...r.actions);
-        warnings.push(...r.warnings);
-    }
-    for (const entry of agentRules) {
-        const r = await compileAgentRuleActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace);
-        actions.push(...r.actions);
-        warnings.push(...r.warnings);
-    }
-    for (const entry of permissions) {
-        const r = compilePermissionsActions(entry, detectedAgents, home);
-        actions.push(...r.actions);
-        warnings.push(...r.warnings);
-    }
-    for (const entry of agentDefinitions ?? []) {
-        const r = await compileAgentDefinitionActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace);
-        actions.push(...r.actions);
-        warnings.push(...r.warnings);
-    }
+    const [mcp, rules, perms, defs] = await Promise.all([
+        compileAll(mcpServers, (entry) => compileMcpServerActions(entry, detectedAgents, home, repo, workspace)),
+        compileAll(agentRules, (entry) => compileAgentRuleActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace)),
+        compileAll(permissions, (entry) => compilePermissionsActions(entry, detectedAgents, home)),
+        compileAll(agentDefinitions ?? [], (entry) => compileAgentDefinitionActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace)),
+    ]);
+    actions.push(...mcp.actions, ...rules.actions, ...perms.actions, ...defs.actions);
+    warnings.push(...mcp.warnings, ...rules.warnings, ...perms.warnings, ...defs.warnings);
     return { actions, warnings };
 }

package/dist/src/core/deploy.js

@@ -4,7 +4,9 @@ import path from "node:path";
 import { AGENT_REGISTRY, AGENT_REGISTRY_BY_ID } from "../config/agents.js";
 import { UserError } from "../errors.js";
 import { logger } from "../logger.js";
+import * as frontmatterAdapter from "./adapters/frontmatter.js";
 import { compileAdapterActions } from "./adapters/index.js";
+import { applyTomlMcpPatch } from "./adapters/toml.js";
 import { planCapabilityForDeploy } from "./capabilities.js";
 import { applyMergePatch, computeUndoPatch, isPlainObject, } from "./merge-patch.js";
 import { lookupDeployment, registerDeployment, verifyDeployment, } from "./ownership.js";
@@ -105,7 +107,7 @@ function checkPairAgentRuleAmbiguities(manifest, primary, rider) {
             JSON.stringify(primarySupport.path) === JSON.stringify(riderSupport.path)) {
             warnings.push({
                 kind: "ambiguity",
-                message: `Both "${primary}" and "${rider}" are listed in agentRules entry "${entry.name}". Both target the same surface — listing both is redundant but harmless; deduplication ensures only one write action is emitted.`,
+                message: `Both "${primary}" and "${rider}" are listed in agentRules entry "${entry.name}". Both target the same surface - listing both is redundant but harmless; deduplication ensures only one write action is emitted.`,
             });
         }
     }
@@ -122,7 +124,7 @@ function checkPairMcpAmbiguities(manifest, primary, rider) {
             continue;
         warnings.push({
             kind: "ambiguity",
-            message: `Both "${primary}" and "${rider}" are listed in mcpServers entry "${entry.name}". "${primary}" writes to a shared MCP surface — verify that deploying to both does not produce conflicting MCP server behavior.`,
+            message: `Both "${primary}" and "${rider}" are listed in mcpServers entry "${entry.name}". "${primary}" writes to a shared MCP surface - verify that deploying to both does not produce conflicting MCP server behavior.`,
         });
     }
     return warnings;
@@ -134,7 +136,7 @@ function checkPairAgentDefinitionAmbiguities(manifest, primary, rider) {
             continue;
         warnings.push({
             kind: "ambiguity",
-            message: `Both "${primary}" and "${rider}" are listed in agentDefinitions entry "${entry.name}". They write to distinct surfaces — verify that this behavioral divergence is intended.`,
+            message: `Both "${primary}" and "${rider}" are listed in agentDefinitions entry "${entry.name}". They write to distinct surfaces - verify that this behavioral divergence is intended.`,
         });
     }
     return warnings;
@@ -162,7 +164,7 @@ function checkAntigravityPathCollisions(manifest) {
         if (defNames.has(entry.name)) {
             warnings.push({
                 kind: "collision",
-                message: `agentDefinitions entry "${entry.name}" and mcpServers entry "${entry.name}" for agent "antigravity" both resolve to {repo}/.agents/rules/${entry.name}.md — one will silently overwrite the other; use different names or remove one entry`,
+                message: `agentDefinitions entry "${entry.name}" and mcpServers entry "${entry.name}" for agent "antigravity" both resolve to {repo}/.agents/rules/${entry.name}.md - one will silently overwrite the other; use different names or remove one entry`,
             });
         }
     }
@@ -212,17 +214,15 @@ async function planSkillDirActions(manifest, sourceDir, resolvedSourceDir, realR
             });
         }
     }
-    for (const skill of manifest.skills) {
-        await planSkillEntry(skill);
-    }
+    await Promise.all(manifest.skills.map(planSkillEntry));
     return { actions, warnings };
 }
 async function planFileWriteActions(manifest, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace) {
     const actions = [];
-    for (const fileEntry of manifest.files ?? []) {
+    await Promise.all((manifest.files ?? []).map(async (fileEntry) => {
         const targetAgents = fileEntry.agents.filter((agentId) => detectedAgents.includes(agentId));
         if (targetAgents.length === 0)
-            continue;
+            return;
         const source = path.resolve(sourceDir, fileEntry.path);
         await validateSourcePath(source, fileEntry.path, resolvedSourceDir, realRoot);
         await validateSourceFile(source, fileEntry.path);
@@ -236,10 +236,10 @@ async function planFileWriteActions(manifest, sourceDir, resolvedSourceDir, real
                 agent: agentId,
                 source,
                 target: resolveTargetTemplate(fileEntry.target, home, repo, workspace),
-                confidence: agent.provenance.skills,
+                confidence: "implementation-only",
             });
         }
-    }
+    }));
     return actions;
 }
 function planConfigPatchActions(manifest, detectedAgents, home, repo, workspace) {
@@ -370,7 +370,7 @@ async function backupManagedFileWriteTarget(action, home, deps) {
         agent: action.agent,
     }, deps.registry);
     if (!isOwned) {
-        throw new Error(`Target "${action.target}" exists but is not managed by inception-engine — refusing to overwrite`);
+        throw new Error(`Target "${action.target}" exists but is not managed by inception-engine - refusing to overwrite`);
     }
     const backupPath = `${action.target}.inception-backup`;
     await (deps.fileOps ?? defaultDeployFileOps).rm(backupPath, {
@@ -528,7 +528,7 @@ async function deployConfigPatch(action, dryRun, verbose, home, planned, deps) {
         if (existingEntry &&
             (existingEntry.skill !== action.skill ||
                 existingEntry.agent !== action.agent)) {
-            throw new Error(`Config "${action.target}" is already patched by skill "${existingEntry.skill}" for agent "${existingEntry.agent}" — refusing to double-patch`);
+            throw new Error(`Config "${action.target}" is already patched by skill "${existingEntry.skill}" for agent "${existingEntry.agent}" - refusing to double-patch`);
         }
         const original = await readJsonConfigFile(action.target);
         const undoPatch = computeUndoPatch(original, patch);
@@ -576,7 +576,7 @@ async function deployTomlPatch(action, dryRun, verbose, home, planned, deps) {
     try {
         const { previousValue } = await (deps.registry
             ? Promise.resolve({ previousValue: null })
-            : (await import("./adapters/toml.js")).applyTomlMcpPatch(action.target, action.skill, action.config));
+            : applyTomlMcpPatch(action.target, action.skill, action.config));
         // Note: To truly support custom deps here we'd need to refactor toml adapter to accept deps.
         // For now we assume standard adapter for TOML.
         await registerDeployment(home, action.target, {
@@ -622,9 +622,8 @@ async function deployFrontmatterEmit(action, dryRun, verbose, home, planned, dep
             (existingEntry.kind !== "frontmatter-emit" ||
                 existingEntry.skill !== action.skill ||
                 existingEntry.agent !== action.agent)) {
-            throw new Error(`Frontmatter target "${action.target}" is already patched by skill "${existingEntry.skill}" for agent "${existingEntry.agent}" — refusing to double-patch`);
+            throw new Error(`Frontmatter target "${action.target}" is already patched by skill "${existingEntry.skill}" for agent "${existingEntry.agent}" - refusing to double-patch`);
         }
-        const frontmatterAdapter = await import("./adapters/frontmatter.js");
         const existing = await frontmatterAdapter.readFrontmatterDocumentFile(action.target);
         const undoPatch = computeUndoPatch(existing.attributes, action.frontmatter);
         const patchedFrontmatter = applyMergePatch(existing.attributes, action.frontmatter);
@@ -712,7 +711,7 @@ async function assertTargetAbsent(targetPath) {
     catch (err) {
         if (err instanceof Error && err.message.startsWith("Target path appeared"))
             throw err;
-        // ENOENT is expected — target should not exist after backup
+        // ENOENT is expected - target should not exist after backup
     }
 }
 async function createDeployTarget(action, home, deps) {
@@ -775,7 +774,7 @@ async function backupExisting(targetPath, verbose, home, expected, deps) {
         skill: expected.skill,
         agent: expected.agent,
     }, deps.registry))) {
-        throw new Error(`Target "${targetPath}" exists but is not managed by inception-engine — refusing to overwrite`);
+        throw new Error(`Target "${targetPath}" exists but is not managed by inception-engine - refusing to overwrite`);
     }
     const backupPath = `${targetPath}.inception-backup`;
     if (verbose) {

package/dist/src/core/detect.js

@@ -8,13 +8,8 @@ const defaultExecFn = async (cmd, args) => {
     await execFileAsync(cmd, args);
 };
 export async function detectInstalledAgents(home) {
-    const detected = [];
-    for (const agent of AGENT_REGISTRY) {
-        if (await isAgentInstalled(agent, home)) {
-            detected.push(agent.id);
-        }
-    }
-    return detected;
+    const results = await Promise.all(AGENT_REGISTRY.map((agent) => isAgentInstalled(agent, home)));
+    return AGENT_REGISTRY.filter((_, i) => results[i]).map((a) => a.id);
 }
 async function isAgentInstalled(agent, home) {
     const detectPath = resolveAgentDetectPath(agent, home);

package/dist/src/core/init.js

@@ -521,7 +521,8 @@ function logPathAgentEntries(label, entries) {
         return;
     logger.detail(`${label}:`);
     for (const e of entries) {
-        logger.detail(`  ${e.name}  →  ${e.path}  [${e.agents.join(", ")}]`);
+        const entryAgents = e.agents ?? [];
+        logger.detail(`  ${e.name}  →  ${e.path}  [${entryAgents.join(", ")}]`);
     }
 }
 function logVerboseManifest(skills, agentRules, mcpServers, files, configs, agentDefinitions) {

package/dist/src/core/preflight.js

@@ -155,12 +155,22 @@ async function detectInstructionBudgetRisk(detectedAgents, manifest, sourceDir)
             // will produce the proper UserError during action compilation.
         }
     }
+    const entries = [];
     for (const entry of manifest.agentRules ?? []) {
-        await checkEntry(entry.path, "agentRules", entry.agents);
+        entries.push({
+            path: entry.path,
+            label: "agentRules",
+            agents: entry.agents,
+        });
     }
     for (const entry of manifest.agentDefinitions ?? []) {
-        await checkEntry(entry.path, "agentDefinitions", entry.agents);
+        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) {
@@ -169,6 +179,21 @@ function pushCapabilityWarning(acc, kind, message) {
     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,
@@ -181,24 +206,13 @@ function collectCapabilityWarningsForAgent(acc, agentId, capability, entryName,
         pushCapabilityWarning(acc, "info", plan.warning.message);
         return;
     }
-    // Evaluate undocumented/planned surfaces warning
-    const agent = AGENT_REGISTRY_BY_ID[agentId];
-    if (agent?.unsupportedSurfaces) {
-        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}`);
-            }
+    if (capability !== "skills") {
+        const confidence = describeCapabilityConfidence(agentId, capability, scope);
+        if (confidence.message) {
+            pushCapabilityWarning(acc, "config-authority", confidence.message);
         }
     }
-    if (capability === "skills")
-        return;
-    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) {
@@ -252,7 +266,9 @@ async function collectAgentWarnings(agentId, manifest, home) {
         });
     }
     else if (agent.policyNote &&
-        !agent.policyNote.includes("Organization policies may override")) {
+        !agent.policyNote
+            .toLowerCase()
+            .includes("organization policies may override")) {
         warnings.push({
             kind: "policy",
             message: `Agent "${agentId}": ${agent.policyNote}`,

package/dist/src/core/revert.js

@@ -1,6 +1,7 @@
 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";
@@ -177,7 +178,6 @@ function planFrontmatterRevert(action, frontmatterEntry, planned) {
     return { outcome: "ok" };
 }
 async function applyFrontmatterRevert(action, frontmatterEntry) {
-    const frontmatterAdapter = await import("./adapters/frontmatter.js");
     const current = await frontmatterAdapter.readFrontmatterDocumentFile(action.target);
     const restoredFrontmatter = applyUndoPatch(current.attributes, frontmatterEntry.undoPatch ?? {});
     const shouldDeleteFile = frontmatterEntry.created === true &&

package/dist/src/core/validation.js

@@ -218,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/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/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/src/types.d.ts

@@ -102,6 +102,8 @@ export interface AgentConfig {
     agentDefinitionsWorkspaceSupport?: AgentSurfaceSupport;
     agentDefinitionsTomlSupport?: AgentSurfaceSupport;
     agentDefinitionsTomlRepoSupport?: AgentSurfaceSupport;
+    mcpDevcontainerSupport?: AgentSurfaceSupport;
+    mcpAgentFrontmatterSupport?: AgentSurfaceSupport;
     policyNote?: string;
     /**
      * A list of documented surfaces that are currently not safe to support directly.

package/dist/test/os/windows/agentRules-integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/os/windows/agentRules-integration.test.js

@@ -0,0 +1,245 @@
+import assert from "node:assert/strict";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { describe, it } from "node:test";
+import { executeDeploy } from "../../../src/core/deploy.js";
+import { lookupDeployment, registerDeployment, } from "../../../src/core/ownership.js";
+import { executeRevert } from "../../../src/core/revert.js";
+import { exists, makeTmpDir } from "../../helpers/fs.js";
+describe("agentRules repo/workspace file-write (Windows)", {
+    skip: process.platform !== "win32",
+}, () => {
+    it("deploys agentRules with scope repo and registers it", async () => {
+        const home = await makeTmpDir("ie-rules-home");
+        const repo = await makeTmpDir("ie-rules-repo");
+        const sourceDir = await makeTmpDir("ie-rules-source");
+        try {
+            const source = path.join(sourceDir, "CLAUDE.md");
+            await writeFile(source, "# My Rules\n");
+            const target = path.join(repo, "CLAUDE.md");
+            const action = {
+                kind: "file-write",
+                skill: "my-rules",
+                agent: "claude-code",
+                source,
+                target,
+            };
+            const { succeeded, failed } = await executeDeploy([action], false, false, home);
+            assert.equal(succeeded, 1);
+            assert.equal(failed.length, 0);
+            assert.ok(await exists(target));
+            const entry = await lookupDeployment(home, target);
+            assert.ok(entry !== null);
+            assert.equal(entry?.kind, "file-write");
+        }
+        finally {
+            await rm(home, { recursive: true, force: true });
+            await rm(repo, { recursive: true, force: true });
+            await rm(sourceDir, { recursive: true, force: true });
+        }
+    });
+    it("reverts agentRules with scope repo and unregisters it", async () => {
+        const home = await makeTmpDir("ie-rules-home");
+        const repo = await makeTmpDir("ie-rules-repo");
+        try {
+            const source = path.join(repo, "source-CLAUDE.md");
+            const target = path.join(repo, "CLAUDE.md");
+            await writeFile(target, "# My Rules\n");
+            await registerDeployment(home, target, {
+                kind: "file-write",
+                source,
+                skill: "my-rules",
+                agent: "claude-code",
+            });
+            const action = {
+                kind: "file-write",
+                skill: "my-rules",
+                agent: "claude-code",
+                target,
+            };
+            const { succeeded, failed } = await executeRevert([action], false, false, home);
+            assert.equal(succeeded, 1);
+            assert.equal(failed.length, 0);
+            assert.ok(!(await exists(target)));
+            assert.equal(await lookupDeployment(home, target), null);
+        }
+        finally {
+            await rm(home, { recursive: true, force: true });
+            await rm(repo, { recursive: true, force: true });
+        }
+    });
+    it("deploys agentRules with scope workspace and registers it", async () => {
+        const home = await makeTmpDir("ie-rules-home");
+        const workspace = await makeTmpDir("ie-rules-workspace");
+        const sourceDir = await makeTmpDir("ie-rules-source");
+        try {
+            const source = path.join(sourceDir, "CLAUDE.md");
+            await writeFile(source, "# Workspace Rules\n");
+            const target = path.join(workspace, "CLAUDE.md");
+            const action = {
+                kind: "file-write",
+                skill: "my-rules",
+                agent: "claude-code",
+                source,
+                target,
+            };
+            const { succeeded, failed } = await executeDeploy([action], false, false, home);
+            assert.equal(succeeded, 1);
+            assert.equal(failed.length, 0);
+            assert.ok(await exists(target));
+            const entry = await lookupDeployment(home, target);
+            assert.ok(entry !== null);
+            assert.equal(entry?.kind, "file-write");
+        }
+        finally {
+            await rm(home, { recursive: true, force: true });
+            await rm(workspace, { recursive: true, force: true });
+            await rm(sourceDir, { recursive: true, force: true });
+        }
+    });
+    it("reverts agentRules with scope workspace and unregisters it", async () => {
+        const home = await makeTmpDir("ie-rules-home");
+        const workspace = await makeTmpDir("ie-rules-workspace");
+        try {
+            const source = path.join(workspace, "source-CLAUDE.md");
+            const target = path.join(workspace, "CLAUDE.md");
+            await writeFile(target, "# Workspace Rules\n");
+            await registerDeployment(home, target, {
+                kind: "file-write",
+                source,
+                skill: "my-rules",
+                agent: "claude-code",
+            });
+            const action = {
+                kind: "file-write",
+                skill: "my-rules",
+                agent: "claude-code",
+                target,
+            };
+            const { succeeded, failed } = await executeRevert([action], false, false, home);
+            assert.equal(succeeded, 1);
+            assert.equal(failed.length, 0);
+            assert.ok(!(await exists(target)));
+            assert.equal(await lookupDeployment(home, target), null);
+        }
+        finally {
+            await rm(home, { recursive: true, force: true });
+            await rm(workspace, { recursive: true, force: true });
+        }
+    });
+});
+describe("Antigravity frontmatter-emit (Windows)", {
+    skip: process.platform !== "win32",
+}, () => {
+    it("deploys frontmatter-emit for Antigravity and registers it", async () => {
+        const home = await makeTmpDir("ie-fm-home");
+        const repo = await makeTmpDir("ie-fm-repo");
+        try {
+            const target = path.join(repo, ".agents", "rules", "my-mcp.md");
+            const frontmatter = {
+                "mcp-servers": {
+                    "my-mcp": { command: "npx", args: ["-y", "my-mcp-server"] },
+                },
+            };
+            const action = {
+                kind: "frontmatter-emit",
+                skill: "my-mcp",
+                agent: "antigravity",
+                target,
+                frontmatter,
+            };
+            const { succeeded, failed } = await executeDeploy([action], false, false, home);
+            assert.equal(succeeded, 1);
+            assert.equal(failed.length, 0);
+            assert.ok(await exists(target));
+            const content = await readFile(target, "utf-8");
+            assert.ok(content.includes("mcp-servers:"));
+            const entry = await lookupDeployment(home, target);
+            assert.ok(entry !== null);
+            assert.equal(entry?.kind, "frontmatter-emit");
+            assert.equal(entry.created, true);
+        }
+        finally {
+            await rm(home, { recursive: true, force: true });
+            await rm(repo, { recursive: true, force: true });
+        }
+    });
+    it("reverts frontmatter-emit for Antigravity and removes file when no body", async () => {
+        const home = await makeTmpDir("ie-fm-home");
+        const repo = await makeTmpDir("ie-fm-repo");
+        try {
+            const target = path.join(repo, ".agents", "rules", "my-mcp.md");
+            const frontmatter = {
+                "mcp-servers": {
+                    "my-mcp": { command: "npx", args: ["-y", "my-mcp-server"] },
+                },
+            };
+            // Deploy first so the file and registry entry are created.
+            const deployAction = {
+                kind: "frontmatter-emit",
+                skill: "my-mcp",
+                agent: "antigravity",
+                target,
+                frontmatter,
+            };
+            await executeDeploy([deployAction], false, false, home);
+            const action = {
+                kind: "frontmatter-emit",
+                skill: "my-mcp",
+                agent: "antigravity",
+                target,
+            };
+            const { succeeded, failed } = await executeRevert([action], false, false, home);
+            assert.equal(succeeded, 1);
+            assert.equal(failed.length, 0);
+            assert.ok(!(await exists(target)));
+            assert.equal(await lookupDeployment(home, target), null);
+        }
+        finally {
+            await rm(home, { recursive: true, force: true });
+            await rm(repo, { recursive: true, force: true });
+        }
+    });
+    it("reverts frontmatter-emit for Antigravity preserving body when file had prior content", async () => {
+        const home = await makeTmpDir("ie-fm-home");
+        const repo = await makeTmpDir("ie-fm-repo");
+        try {
+            const target = path.join(repo, ".agents", "rules", "my-mcp.md");
+            await mkdir(path.dirname(target), { recursive: true });
+            await writeFile(target, "# My Rules\n");
+            const undoPatch = { "mcp-servers": null };
+            await registerDeployment(home, target, {
+                kind: "frontmatter-emit",
+                patch: {
+                    "mcp-servers": {
+                        "my-mcp": { command: "npx", args: ["-y", "my-mcp-server"] },
+                    },
+                },
+                undoPatch,
+                created: false,
+                hadFrontmatter: false,
+                skill: "my-mcp",
+                agent: "antigravity",
+            });
+            const action = {
+                kind: "frontmatter-emit",
+                skill: "my-mcp",
+                agent: "antigravity",
+                target,
+            };
+            const { succeeded, failed } = await executeRevert([action], false, false, home);
+            assert.equal(succeeded, 1);
+            assert.equal(failed.length, 0);
+            // File should still exist because it had body content.
+            assert.ok(await exists(target));
+            const content = await readFile(target, "utf-8");
+            assert.ok(!content.includes("mcp-servers:"));
+            assert.ok(content.includes("My Rules"));
+            assert.equal(await lookupDeployment(home, target), null);
+        }
+        finally {
+            await rm(home, { recursive: true, force: true });
+            await rm(repo, { recursive: true, force: true });
+        }
+    });
+});

package/dist/test/unit/adapters.test.js

@@ -910,6 +910,76 @@ describe("compileAgentDefinitionActions", () => {
             await rm(dir, { recursive: true });
         }
     });
+    it("accepts github-copilot tools as empty array", async () => {
+        const compile = await getAdapter();
+        const dir = await makeTmpDir();
+        try {
+            await writeFile(path.join(dir, "agent.md"), "---\nname: test\ndescription: test\ntools: []\n---\n# Agent");
+            const realRoot = await realpath(dir);
+            const result = await compile({
+                name: "agent",
+                agents: ["github-copilot"],
+                path: "agent.md",
+                scope: "repo",
+            }, dir, dir, realRoot, ["github-copilot"], "/home/test", "/repo/test");
+            assert.ok(result.actions.length > 0, "expected at least one action");
+        }
+        finally {
+            await rm(dir, { recursive: true });
+        }
+    });
+    it("accepts github-copilot tools as array of strings", async () => {
+        const compile = await getAdapter();
+        const dir = await makeTmpDir();
+        try {
+            await writeFile(path.join(dir, "agent.md"), "---\nname: test\ndescription: test\ntools:\n  - github\n  - codebase\n---\n# Agent");
+            const realRoot = await realpath(dir);
+            const result = await compile({
+                name: "agent",
+                agents: ["github-copilot"],
+                path: "agent.md",
+                scope: "repo",
+            }, dir, dir, realRoot, ["github-copilot"], "/home/test", "/repo/test");
+            assert.ok(result.actions.length > 0, "expected at least one action");
+        }
+        finally {
+            await rm(dir, { recursive: true });
+        }
+    });
+    it("throws for github-copilot when tools is not an array", async () => {
+        const compile = await getAdapter();
+        const dir = await makeTmpDir();
+        try {
+            await writeFile(path.join(dir, "bad-tools.md"), "---\nname: test\ndescription: test\ntools: not-an-array\n---\n# Bad");
+            const realRoot = await realpath(dir);
+            await assert.rejects(compile({
+                name: "bad",
+                agents: ["github-copilot"],
+                path: "bad-tools.md",
+                scope: "repo",
+            }, dir, dir, realRoot, ["github-copilot"], "/home/test", "/repo/test"), /"tools" field that must be an array/);
+        }
+        finally {
+            await rm(dir, { recursive: true });
+        }
+    });
+    it("throws for github-copilot when tools contains a non-string entry", async () => {
+        const compile = await getAdapter();
+        const dir = await makeTmpDir();
+        try {
+            await writeFile(path.join(dir, "bad-tools.md"), "---\nname: test\ndescription: test\ntools:\n  - github\n  - 123\n---\n# Bad");
+            const realRoot = await realpath(dir);
+            await assert.rejects(compile({
+                name: "bad",
+                agents: ["github-copilot"],
+                path: "bad-tools.md",
+                scope: "repo",
+            }, dir, dir, realRoot, ["github-copilot"], "/home/test", "/repo/test"), /"tools" entry that must be a string/);
+        }
+        finally {
+            await rm(dir, { recursive: true });
+        }
+    });
     it("throws for antigravity when mcp-servers is malformed", async () => {
         const compile = await getAdapter();
         const dir = await makeTmpDir();

package/dist/test/unit/init-fixture.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/unit/init-fixture.test.js

@@ -0,0 +1,153 @@
+import assert from "node:assert/strict";
+import { cp, readFile, rm } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { describe, it } from "node:test";
+import { makeTmpDir } from "../helpers/fs.js";
+import { assertPathEndsWith, normalizeSlashes } from "../helpers/path.js";
+const PROJECT_ROOT = path.resolve(import.meta.dirname, "..", "..");
+const FIXTURE_DIR = path.join(PROJECT_ROOT, "test", "fixtures", "readme-sample");
+function run(args, env) {
+    return new Promise((resolve) => {
+        const child = spawn(process.execPath, [path.join(PROJECT_ROOT, "src", "index.ts"), ...args], {
+            cwd: PROJECT_ROOT,
+            env: { ...process.env, ...env },
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (d) => {
+            stdout += d.toString();
+        });
+        child.stderr.on("data", (d) => {
+            stderr += d.toString();
+        });
+        child.on("close", (code) => {
+            resolve({ stdout, stderr, code: code ?? 1 });
+        });
+    });
+}
+/**
+ * Extract the JSON manifest object from `init --plan` stdout.
+ * The output format is:
+ *   [plan] Would write /path/inception.json with N skill(s), ...:
+ *   <blank line>
+ *   { ...json... }
+ * The [plan] prefix may include ANSI escape codes; the first `{` is
+ * reliably the start of the JSON object.
+ */
+function extractPlanJson(stdout) {
+    const jsonStart = stdout.indexOf("{");
+    assert.ok(jsonStart !== -1, `Could not find JSON object in --plan stdout:\n${stdout}`);
+    return JSON.parse(stdout.slice(jsonStart));
+}
+// ---------------------------------------------------------------------------
+// Block 1: init --plan against the real limbo/ tree (read-only)
+// ---------------------------------------------------------------------------
+describe("init --plan against real limbo/ tree", () => {
+    it("emits the 4 limbo skills with all 5 agents and empty other sections", async () => {
+        const limboDir = path.join(PROJECT_ROOT, "limbo");
+        const { stdout, code } = await run(["init", limboDir, "--plan"]);
+        assert.equal(code, 0, `init --plan exited non-zero.\nstdout: ${stdout}`);
+        assert.ok(stdout.includes("[plan]"), `missing [plan] prefix:\n${stdout}`);
+        const manifest = extractPlanJson(stdout);
+        // Exactly 4 skills
+        assert.equal(manifest.skills.length, 4, `expected 4 skills, got ${manifest.skills.length}: ${JSON.stringify(manifest.skills.map((s) => s.name))}`);
+        // Names sorted alphabetically (sort before comparing - filesystem order not guaranteed)
+        const names = manifest.skills.map((s) => s.name).sort();
+        assert.deepEqual(names, [
+            "inception",
+            "interstellar",
+            "tenet",
+            "the-prestige",
+        ]);
+        // Each skill has exactly the 5 portability agents (github-copilot excluded)
+        const expectedAgents = [
+            "antigravity",
+            "claude-code",
+            "codex",
+            "gemini-cli",
+            "opencode",
+        ];
+        for (const skill of manifest.skills) {
+            assert.deepEqual(skill.agents.slice().sort(), expectedAgents, `skill "${skill.name}" agents mismatch: ${JSON.stringify(skill.agents)}`);
+            assertPathEndsWith(skill.path, `skills/${skill.name}`, `skill "${skill.name}" path should end with skills/${skill.name}`);
+        }
+        // All other sections are empty arrays
+        assert.deepEqual(manifest.mcpServers, [], "mcpServers should be []");
+        assert.deepEqual(manifest.agentRules, [], "agentRules should be []");
+        assert.deepEqual(manifest.agentDefinitions, [], "agentDefinitions should be []");
+        assert.deepEqual(manifest.files, [], "files should be []");
+        assert.deepEqual(manifest.configs, [], "configs should be []");
+    });
+});
+// ---------------------------------------------------------------------------
+// Block 2: init against README-shaped fixture (copied to temp dir)
+// ---------------------------------------------------------------------------
+describe("init against readme-sample fixture", () => {
+    it("generates a manifest covering all README-documented init discovery paths", async () => {
+        const tmpDir = await makeTmpDir("ie-fixture-readme");
+        try {
+            // Copy the static fixture tree (including .claude/ hidden dir) into tmpDir
+            await cp(FIXTURE_DIR, tmpDir, { recursive: true });
+            const { stdout, code } = await run(["init", tmpDir]);
+            assert.equal(code, 0, `init exited non-zero.\nstdout: ${stdout}`);
+            const manifest = JSON.parse(await readFile(path.join(tmpDir, "inception.json"), "utf-8"));
+            // --- skills: 2 entries, github-copilot excluded per portability rules ---
+            assert.equal(manifest.skills.length, 2, `expected 2 skills, got ${manifest.skills.length}: ${JSON.stringify(manifest.skills.map((s) => s.name))}`);
+            const skillNames = manifest.skills.map((s) => s.name).sort();
+            assert.deepEqual(skillNames, ["my-skill", "other-skill"]);
+            const expectedSkillAgents = [
+                "antigravity",
+                "claude-code",
+                "codex",
+                "gemini-cli",
+                "opencode",
+            ];
+            for (const skill of manifest.skills) {
+                assert.deepEqual(skill.agents.slice().sort(), expectedSkillAgents, `skill "${skill.name}" should have all 5 agents (not github-copilot): ${JSON.stringify(skill.agents)}`);
+                assertPathEndsWith(skill.path, `skills/${skill.name}`, `skill "${skill.name}" path should end with skills/${skill.name}`);
+            }
+            // --- agentRules: 3 entries for CLAUDE.md, AGENTS.md, GEMINI.md ---
+            assert.equal(manifest.agentRules.length, 3, `expected 3 agentRules, got ${manifest.agentRules.length}: ${JSON.stringify(manifest.agentRules.map((r) => r.name))}`);
+            const claudeRule = manifest.agentRules.find((r) => normalizeSlashes(r.path).endsWith("CLAUDE.md"));
+            assert.ok(claudeRule, "should have an agentRules entry for CLAUDE.md");
+            assert.deepEqual(claudeRule?.agents.slice().sort(), ["claude-code"], `CLAUDE.md agents: ${JSON.stringify(claudeRule?.agents)}`);
+            assert.equal(claudeRule?.scope, "global");
+            const agentsRule = manifest.agentRules.find((r) => normalizeSlashes(r.path).endsWith("AGENTS.md"));
+            assert.ok(agentsRule, "should have an agentRules entry for AGENTS.md");
+            assert.deepEqual(agentsRule?.agents.slice().sort(), ["codex", "opencode"], `AGENTS.md agents: ${JSON.stringify(agentsRule?.agents)}`);
+            assert.equal(agentsRule?.scope, "global");
+            const geminiRule = manifest.agentRules.find((r) => normalizeSlashes(r.path).endsWith("GEMINI.md"));
+            assert.ok(geminiRule, "should have an agentRules entry for GEMINI.md");
+            assert.deepEqual(geminiRule?.agents.slice().sort(), ["gemini-cli"], 
+            // antigravity is shared-via gemini-cli and excluded from init defaults
+            `GEMINI.md agents should be [gemini-cli] only: ${JSON.stringify(geminiRule?.agents)}`);
+            assert.equal(geminiRule?.scope, "global");
+            // --- mcpServers: 1 entry round-tripped from mcp-servers.json sidecar ---
+            assert.equal(manifest.mcpServers.length, 1, `expected 1 mcpServer, got ${manifest.mcpServers.length}`);
+            const mcp = manifest.mcpServers[0];
+            assert.equal(mcp.name, "my-mcp-server");
+            assert.deepEqual(mcp.agents.slice().sort(), [
+                "claude-code",
+                "codex",
+                "gemini-cli",
+                "opencode",
+            ]);
+            assert.equal(mcp.config.command, "npx");
+            assert.deepEqual(mcp.config.args, ["-y", "@example/mcp-server"]);
+            // --- agentDefinitions: 1 entry from .claude/agents/ -> claude-code ---
+            assert.equal(manifest.agentDefinitions.length, 1, `expected 1 agentDefinition, got ${manifest.agentDefinitions.length}`);
+            const def = manifest.agentDefinitions[0];
+            assert.equal(def.name, "code-reviewer");
+            assert.deepEqual(def.agents, ["claude-code"]);
+            assert.equal(def.scope, "repo");
+            assertPathEndsWith(def.path, ".claude/agents/code-reviewer.md", "code-reviewer path should end with .claude/agents/code-reviewer.md");
+            // --- files and configs stay empty (no sidecar manifests for them) ---
+            assert.deepEqual(manifest.files, [], "files should be []");
+            assert.deepEqual(manifest.configs, [], "configs should be []");
+        }
+        finally {
+            await rm(tmpDir, { recursive: true });
+        }
+    });
+});

package/dist/test/unit/preflight.test.js

@@ -125,6 +125,26 @@ describe("runPreflight", () => {
         assert.equal(implementationOnlyWarning, undefined, `expected no implementation-only warning, got: ${implementationOnlyWarning?.message}`);
     });
 });
+describe("github-copilot planned surfaces", () => {
+    it("emits a planned surface info notice for devcontainer MCP when Copilot is detected and MCP is targeted", async () => {
+        const manifestWithMcp = {
+            ...emptyManifest,
+            mcpServers: [
+                {
+                    name: "test-mcp",
+                    scope: "repo",
+                    agents: ["github-copilot"],
+                    config: { command: "node", args: ["server.js"] },
+                },
+            ],
+        };
+        const warnings = await runPreflight(baseOptions, manifestWithMcp, "/home/test", ["github-copilot"]);
+        const plannedWarning = warnings.find((w) => w.kind === "info" &&
+            /devcontainer\.json MCP support is planned/.test(w.message));
+        assert.ok(plannedWarning, "expected a planned surface warning for Copilot devcontainer when MCP is targeted");
+        assert.match(plannedWarning.message, /planned/);
+    });
+});
 describe("instruction precedence warnings", () => {
     it("emits duplicate-content precedence warning when same source used in both global and repo scope for an agent", async () => {
         const sourceDir = await makeTmpDir();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuznai/inception-engine",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Deploy AI agent skills from a git repo to user home directories",
   "license": "MIT",
   "author": "Damian Piątkowski",