@kuznai/inception-engine 0.7.0 → 0.9.0

package/README.md

@@ -2,7 +2,7 @@
 
 Plant skills directly into the minds of your installed AI coding agents — Claude Code, Codex, Gemini CLI, Antigravity, OpenCode, and GitHub Copilot. One command. They'll think they thought of it themselves.
 
-Today, inception-engine is a skills deployer. The public manifest and CLI planner currently deploy and revert skill directories only. The core executor also has internal support for single-file write and JSON config patch actions, but the manifest format does not expose them yet. MCP configuration and agent-specific config patching remain unimplemented at the manifest level.
+Today, inception-engine deploys skills, single files, JSON config patches, MCP server registrations, and agent instruction files to AI coding agents.
 
 ## Quick Start
 
@@ -38,13 +38,13 @@ Managed skills overwrite their previous version. If a target exists but was not
 
 ### Feature Support
 
-| Feature | Status |
-|---|---|
-| Skills (SKILL.md) | Supported via manifest and CLI |
-| File write | Internal executor support only; not exposed in manifest or CLI planning |
-| Config patch (JSON merge) | Internal executor support only; not exposed in manifest or CLI planning |
-| MCP Servers | Accepted in manifest for forward compatibility, not implemented |
-| Agent Rules | Accepted in manifest for forward compatibility, not implemented |
+| Feature | Deploy | Revert |
+|---|---|---|
+| Skills (SKILL.md) | All agents via manifest and CLI | All agents |
+| File write | All agents via manifest and CLI | All agents |
+| Config patch (JSON merge) | All agents via manifest and CLI | All agents |
+| MCP Servers | claude-code, gemini-cli; stub warning for other agents | claude-code, gemini-cli |
+| Agent Rules | claude-code, codex, gemini-cli, opencode; stub warning for other agents | claude-code, codex, gemini-cli, opencode |
 
 ## Manifest Format
 
@@ -59,18 +59,76 @@ Create an `inception.json` file at the root of your skills directory:
       "agents": ["claude-code", "codex", "gemini-cli", "antigravity", "opencode", "github-copilot"]
     }
   ],
-  "mcpServers": [],
-  "agentRules": []
+  "files": [
+    {
+      "name": "my-settings",
+      "path": "files/settings.json",
+      "target": "{home}/.claude/settings.json",
+      "agents": ["claude-code"]
+    }
+  ],
+  "configs": [
+    {
+      "name": "enable-feature",
+      "target": "{home}/.claude/settings.json",
+      "patch": { "someFeature": true },
+      "agents": ["claude-code"]
+    }
+  ],
+  "mcpServers": [
+    {
+      "name": "my-server",
+      "agents": ["claude-code", "gemini-cli"],
+      "config": { "command": "npx", "args": ["-y", "my-mcp-server"] }
+    }
+  ],
+  "agentRules": [
+    {
+      "name": "my-rules",
+      "path": "rules/CLAUDE.md",
+      "agents": ["claude-code"]
+    }
+  ]
 }
 ```
 
-Each skill entry has:
+Each **skill** entry has:
 
-- **name** - Unique skill identifier using letters, digits, dots, underscores, or hyphens; it must not start with a dot
+- **name** - Unique identifier using letters, digits, dots, underscores, or hyphens; must not start with a dot
 - **path** - Relative path to the skill directory within the repo
 - **agents** - Array of agent IDs to deploy this skill to. If an agent isn't installed, it's skipped.
 
-`mcpServers` and `agentRules` are currently parsed for forward compatibility, but the deployment engine ignores them today. The manifest-driven planner and revert flow currently derive actions from `skills` entries only.
+Each **file** entry deploys a single file to an agent's configuration location:
+
+- **name** - Unique identifier (same format as skill names)
+- **path** - Relative path to the source file within the repo
+- **target** - Destination path using a placeholder prefix: `{home}`, `{appdata}` (Windows), or `{xdg_config}` (Linux). For example: `{home}/.claude/settings.json`
+- **agents** - Array of agent IDs to deploy this file to
+
+Each **config** entry applies a [JSON merge patch (RFC 7386)](https://datatracker.ietf.org/doc/html/rfc7386) to an existing agent config file:
+
+- **name** - Unique identifier (same format as skill names)
+- **target** - Config file to patch, using the same placeholder prefix as file entries
+- **patch** - JSON object of keys to set. A `null` value removes the key from the target file. Non-null values are set directly (deep merge is not applied).
+- **agents** - Array of agent IDs to apply this patch to
+
+The engine records an undo-patch for each config-patch deployment so that `revert` can restore the original values.
+
+Each **mcpServer** entry registers an MCP server into the agent's config file by applying a JSON merge patch under the `mcpServers` key:
+
+- **name** - Unique identifier (same format as skill names); used as the server's key in the config
+- **agents** - Array of agent IDs to register this server with
+- **config** - Raw server descriptor object (e.g. `{ "command": "...", "args": [...] }` for stdio transport). The exact shape is passed through verbatim; agent adapters handle agent-specific requirements.
+
+MCP server registration is currently supported for `claude-code` (`~/.claude.json`) and `gemini-cli` (`~/.gemini/settings.json`). Other agents emit a warning and are skipped. Revert removes the registered server entry from the config file.
+
+Each **agentRules** entry deploys a Markdown instruction file to the agent's global rules location:
+
+- **name** - Unique identifier (same format as skill names)
+- **path** - Relative path to the source Markdown file within the repo
+- **agents** - Array of agent IDs to deploy this file to
+
+Agent rules deployment is currently supported for `claude-code` (`~/.claude/CLAUDE.md`), `codex` (`~/.codex/AGENTS.md`), `gemini-cli` (`~/.gemini/GEMINI.md`), and `opencode` (`~/.config/opencode/AGENTS.md`). Other agents emit a warning and are skipped. Revert removes the deployed rules file.
 
 ## Creating Skills
 
@@ -87,7 +145,7 @@ description: What this skill does and when to use it
 Instructions for the AI agent...
 ```
 
-The `name` and `description` fields in the frontmatter are required by most agents. The description determines when the agent activates the skill.
+The `name` and `description` fields in the frontmatter are used by most agents. The description determines when the agent activates the skill. inception-engine does not currently validate the frontmatter — missing or malformed fields may cause the skill to be ignored or misbehave at the agent level.
 
 ## CLI Reference
 
@@ -169,7 +227,7 @@ inception-engine maintains a centralized deployment registry at `~/.inception-en
 
 - **Strong binding**: Each registry entry binds a specific target path to its skill, agent, and action kind, with action-specific provenance fields (`source` and `method` for skill-dir and file-write; `patch` and `undoPatch` for config-patch). A target is only considered managed if all relevant fields match — a stray entry or a different deployment cannot satisfy the check.
 
-- **Atomic redeploy**: When overwriting an existing managed target, the engine renames the old target to a backup, creates the new deployment, and only removes the backup on success. If the new deployment fails, the backup is restored.
+- **Atomic redeploy**: When overwriting an existing managed `skill-dir` target, the engine renames the old target to a backup, creates the new deployment, and only removes the backup on success. If the new deployment fails, the backup is restored. `file-write` and `config-patch` deployments write directly to the target without this backup/rollback model.
 
 - **Cross-platform**: The registry uses the same resolved home directory as the rest of the tool, including sudo scenarios on POSIX and elevated PowerShell on Windows.
 

package/dist/config/agents.js

@@ -15,6 +15,16 @@ export const AGENT_REGISTRY = [
             skills: "documented",
             detectPaths: "documented",
             detectBinary: "documented",
+            mcpConfig: "documented",
+            agentRules: "documented",
+        },
+        mcpConfigPath: {
+            posix: ["{home}", ".claude.json"],
+            windows: ["{home}", ".claude.json"],
+        },
+        agentRulesPath: {
+            posix: ["{home}", ".claude", "CLAUDE.md"],
+            windows: ["{home}", ".claude", "CLAUDE.md"],
         },
     },
     {
@@ -33,6 +43,12 @@ export const AGENT_REGISTRY = [
             skills: "documented",
             detectPaths: "documented",
             detectBinary: "documented",
+            agentRules: "documented",
+        },
+        // mcpConfigPath omitted: Codex uses TOML config, not JSON — not supported by config-patch
+        agentRulesPath: {
+            posix: ["{home}", ".codex", "AGENTS.md"],
+            windows: ["{home}", ".codex", "AGENTS.md"],
         },
     },
     {
@@ -51,6 +67,16 @@ export const AGENT_REGISTRY = [
             skills: "documented",
             detectPaths: "documented",
             detectBinary: "documented",
+            mcpConfig: "documented",
+            agentRules: "documented",
+        },
+        mcpConfigPath: {
+            posix: ["{home}", ".gemini", "settings.json"],
+            windows: ["{home}", ".gemini", "settings.json"],
+        },
+        agentRulesPath: {
+            posix: ["{home}", ".gemini", "GEMINI.md"],
+            windows: ["{home}", ".gemini", "GEMINI.md"],
         },
     },
     {
@@ -70,6 +96,7 @@ export const AGENT_REGISTRY = [
             detectPaths: "implementation-only",
             detectBinary: "provisional",
         },
+        // mcpConfigPath and agentRulesPath omitted: paths not documented strongly enough for this release
     },
     {
         id: "opencode",
@@ -87,6 +114,12 @@ export const AGENT_REGISTRY = [
             skills: "documented",
             detectPaths: "documented",
             detectBinary: "documented",
+            agentRules: "documented",
+        },
+        // mcpConfigPath omitted: OpenCode uses opencode.json (TOML-adjacent format), not plain JSON
+        agentRulesPath: {
+            posix: ["{xdg_config}", "opencode", "AGENTS.md"],
+            windows: ["{appdata}", "opencode", "AGENTS.md"],
         },
     },
     {
@@ -106,6 +139,8 @@ export const AGENT_REGISTRY = [
             detectPaths: "documented",
             detectBinary: "documented",
         },
+        // mcpConfigPath and agentRulesPath omitted: rules live in repo, not home dir; MCP config unclear
+        policyNote: "Organization policies may override locally deployed skills. Verify with your GitHub org admin if deployed skills are not active.",
     },
 ];
 export const AGENT_REGISTRY_BY_ID = Object.fromEntries(AGENT_REGISTRY.map((a) => [a.id, a]));

package/dist/config/manifest.js

@@ -38,9 +38,12 @@ function validateManifest(data, filePath) {
         if (issuePath.length === 1 && issuePath[0] === "skills") {
             throw new UserError("MANIFEST_INVALID", `${filePath}: "skills" must be an array`);
         }
-        // Top-level "mcpServers" or "agentRules": wrong type → uniform message
+        // Top-level array fields with wrong type → uniform message
         if (issuePath.length === 1 &&
-            (issuePath[0] === "mcpServers" || issuePath[0] === "agentRules")) {
+            (issuePath[0] === "mcpServers" ||
+                issuePath[0] === "agentRules" ||
+                issuePath[0] === "files" ||
+                issuePath[0] === "configs")) {
             throw new UserError("MANIFEST_INVALID", `${filePath}: "${issuePath[0]}" must be an array`);
         }
         throw new UserError("MANIFEST_INVALID", `${filePath}: ${formatZodPath(issuePath)}${issue.message}`);

package/dist/core/adapters/index.d.ts

@@ -0,0 +1,11 @@
+import type { McpServerEntry, AgentRuleEntry } from "../../schemas/manifest.ts";
+import type { AgentId, ConfigPatchDeployAction, FileWriteDeployAction, PlanWarning } from "../../types.ts";
+import { compileMcpServerReverts } from "./mcp.ts";
+import { compileAgentRuleReverts } from "./rules.ts";
+export { compileMcpServerReverts, compileAgentRuleReverts };
+export type AdapterAction = ConfigPatchDeployAction | FileWriteDeployAction;
+export interface AdapterResult {
+    actions: AdapterAction[];
+    warnings: PlanWarning[];
+}
+export declare function compileAdapterActions(mcpServers: McpServerEntry[], agentRules: AgentRuleEntry[], sourceDir: string, resolvedSourceDir: string, realRoot: string, detectedAgents: AgentId[], home: string): Promise<AdapterResult>;

package/dist/core/adapters/index.js

@@ -0,0 +1,18 @@
+import { compileMcpServerActions, compileMcpServerReverts } from "./mcp.js";
+import { compileAgentRuleActions, compileAgentRuleReverts } from "./rules.js";
+export { compileMcpServerReverts, compileAgentRuleReverts };
+export async function compileAdapterActions(mcpServers, agentRules, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home) {
+    const actions = [];
+    const warnings = [];
+    for (const entry of mcpServers) {
+        const r = compileMcpServerActions(entry, detectedAgents, home);
+        actions.push(...r.actions);
+        warnings.push(...r.warnings);
+    }
+    for (const entry of agentRules) {
+        const r = await compileAgentRuleActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home);
+        actions.push(...r.actions);
+        warnings.push(...r.warnings);
+    }
+    return { actions, warnings };
+}

package/dist/core/adapters/mcp.d.ts

@@ -0,0 +1,8 @@
+import type { McpServerEntry } from "../../schemas/manifest.ts";
+import type { AgentId, ConfigPatchDeployAction, ConfigPatchRevertAction, PlanWarning } from "../../types.ts";
+export interface McpAdapterResult {
+    actions: ConfigPatchDeployAction[];
+    warnings: PlanWarning[];
+}
+export declare function compileMcpServerActions(entry: McpServerEntry, detectedAgents: AgentId[], home: string): McpAdapterResult;
+export declare function compileMcpServerReverts(entry: McpServerEntry, agentFilter: AgentId[] | null, home: string): ConfigPatchRevertAction[];

package/dist/core/adapters/mcp.js

@@ -0,0 +1,51 @@
+import path from "node:path";
+import { AGENT_REGISTRY_BY_ID } from "../../config/agents.js";
+import { getPlatformKey, resolvePlaceholders } from "../resolve.js";
+export function compileMcpServerActions(entry, detectedAgents, home) {
+    const actions = [];
+    const warnings = [];
+    const platform = getPlatformKey();
+    for (const agentId of entry.agents) {
+        if (!detectedAgents.includes(agentId))
+            continue;
+        const agent = AGENT_REGISTRY_BY_ID[agentId];
+        if (!agent?.mcpConfigPath) {
+            warnings.push({
+                kind: "confidence",
+                message: `mcpServers: agent "${agentId}" does not have a documented MCP config path — skipping "${entry.name}"`,
+            });
+            continue;
+        }
+        const target = resolvePlaceholders(agent.mcpConfigPath[platform], "", home);
+        // Ensure no stray empty segments collapse the path unexpectedly
+        const resolvedTarget = path.resolve(target);
+        actions.push({
+            kind: "config-patch",
+            skill: entry.name,
+            agent: agentId,
+            target: resolvedTarget,
+            patch: { mcpServers: { [entry.name]: entry.config } },
+            confidence: agent.provenance.mcpConfig ?? "provisional",
+        });
+    }
+    return { actions, warnings };
+}
+export function compileMcpServerReverts(entry, agentFilter, home) {
+    const actions = [];
+    const platform = getPlatformKey();
+    for (const agentId of entry.agents) {
+        if (agentFilter && !agentFilter.includes(agentId))
+            continue;
+        const agent = AGENT_REGISTRY_BY_ID[agentId];
+        if (!agent?.mcpConfigPath)
+            continue;
+        const target = path.resolve(resolvePlaceholders(agent.mcpConfigPath[platform], "", home));
+        actions.push({
+            kind: "config-patch",
+            skill: entry.name,
+            agent: agentId,
+            target,
+        });
+    }
+    return actions;
+}

package/dist/core/adapters/rules.d.ts

@@ -0,0 +1,8 @@
+import type { AgentRuleEntry } from "../../schemas/manifest.ts";
+import type { AgentId, FileWriteDeployAction, FileWriteRevertAction, PlanWarning } from "../../types.ts";
+export interface RulesAdapterResult {
+    actions: FileWriteDeployAction[];
+    warnings: PlanWarning[];
+}
+export declare function compileAgentRuleActions(entry: AgentRuleEntry, sourceDir: string, resolvedSourceDir: string, realRoot: string, detectedAgents: AgentId[], home: string): Promise<RulesAdapterResult>;
+export declare function compileAgentRuleReverts(entry: AgentRuleEntry, agentFilter: AgentId[] | null, home: string): FileWriteRevertAction[];

package/dist/core/adapters/rules.js

@@ -0,0 +1,54 @@
+import path from "node:path";
+import { AGENT_REGISTRY_BY_ID } from "../../config/agents.js";
+import { getPlatformKey, resolvePlaceholders } from "../resolve.js";
+import { validateSourceFile, validateSourcePath } from "../validation.js";
+export async function compileAgentRuleActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home) {
+    const actions = [];
+    const warnings = [];
+    const platform = getPlatformKey();
+    // Validate the source file once (before iterating agents) since it is shared.
+    const source = path.resolve(sourceDir, entry.path);
+    await validateSourcePath(source, entry.path, resolvedSourceDir, realRoot);
+    await validateSourceFile(source, entry.path);
+    for (const agentId of entry.agents) {
+        if (!detectedAgents.includes(agentId))
+            continue;
+        const agent = AGENT_REGISTRY_BY_ID[agentId];
+        if (!agent?.agentRulesPath) {
+            warnings.push({
+                kind: "confidence",
+                message: `agentRules: agent "${agentId}" does not have a documented rules file path — skipping "${entry.name}"`,
+            });
+            continue;
+        }
+        const target = resolvePlaceholders(agent.agentRulesPath[platform], "", home);
+        actions.push({
+            kind: "file-write",
+            skill: entry.name,
+            agent: agentId,
+            source,
+            target,
+            confidence: agent.provenance.agentRules ?? "provisional",
+        });
+    }
+    return { actions, warnings };
+}
+export function compileAgentRuleReverts(entry, agentFilter, home) {
+    const actions = [];
+    const platform = getPlatformKey();
+    for (const agentId of entry.agents) {
+        if (agentFilter && !agentFilter.includes(agentId))
+            continue;
+        const agent = AGENT_REGISTRY_BY_ID[agentId];
+        if (!agent?.agentRulesPath)
+            continue;
+        const target = resolvePlaceholders(agent.agentRulesPath[platform], "", home);
+        actions.push({
+            kind: "file-write",
+            skill: entry.name,
+            agent: agentId,
+            target,
+        });
+    }
+    return actions;
+}

package/dist/core/deploy.js

@@ -1,10 +1,13 @@
+import { constants } from "node:fs";
 import { access, copyFile, cp, lstat, mkdir, readFile, realpath, rename, rm, symlink, unlink, writeFile, } from "node:fs/promises";
 import path from "node:path";
 import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
 import { UserError } from "../errors.js";
 import { logger } from "../logger.js";
 import { lookupDeployment, registerDeployment, verifyDeployment, } from "./ownership.js";
+import { compileAdapterActions } from "./adapters/index.js";
 import { getDeployMethod, resolveAgentSkillPath } from "./resolve.js";
+import { sourceAccessError, validateSourceFile, validateSourcePath, } from "./validation.js";
 function isPlainObject(v) {
     return typeof v === "object" && v !== null && !Array.isArray(v);
 }
@@ -34,7 +37,13 @@ async function readJsonConfig(filePath) {
 function computeUndoPatch(original, patch) {
     const undoPatch = {};
     for (const key of Object.keys(patch)) {
-        undoPatch[key] = key in original ? original[key] : null;
+        const patchVal = patch[key];
+        if (isPlainObject(patchVal) && isPlainObject(original[key])) {
+            undoPatch[key] = computeUndoPatch(original[key], patchVal);
+        }
+        else {
+            undoPatch[key] = key in original ? original[key] : null;
+        }
     }
     return undoPatch;
 }
@@ -44,20 +53,23 @@ function applyMergePatch(original, patch) {
         if (value === null) {
             delete patched[key];
         }
+        else if (isPlainObject(value) && isPlainObject(patched[key])) {
+            patched[key] = applyMergePatch(patched[key], value);
+        }
         else {
             patched[key] = value;
         }
     }
     return patched;
 }
-function sourceAccessError(err, sourcePath) {
-    const code = err.code;
-    if (code === "ENOENT")
-        return `Source not found: ${sourcePath}`;
-    if (code === "EACCES" || code === "EPERM")
-        return `Permission denied accessing source: ${sourcePath}`;
-    const detail = err instanceof Error ? err.message : String(err);
-    return `Failed to access source ${sourcePath}: ${detail}`;
+function resolveTargetTemplate(template, home) {
+    const appdata = process.env.APPDATA ?? path.join(home, "AppData", "Roaming");
+    const xdgRaw = process.env.XDG_CONFIG_HOME;
+    const xdgConfig = xdgRaw && path.isAbsolute(xdgRaw) ? xdgRaw : path.join(home, ".config");
+    return template
+        .replace("{home}", home)
+        .replace("{appdata}", appdata)
+        .replace("{xdg_config}", xdgConfig);
 }
 function detectCollisions(actions) {
     const seen = new Map();
@@ -87,17 +99,9 @@ function detectAmbiguities(detectedAgents) {
     }
     return warnings;
 }
-export async function planDeploy(manifest, sourceDir, detectedAgents, home) {
+async function planSkillDirActions(manifest, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home) {
     const method = getDeployMethod();
     const actions = [];
-    const resolvedSourceDir = path.resolve(sourceDir);
-    let realRoot;
-    try {
-        realRoot = await realpath(resolvedSourceDir);
-    }
-    catch {
-        realRoot = resolvedSourceDir;
-    }
     for (const skill of manifest.skills) {
         const source = path.resolve(sourceDir, skill.path);
         await validateSourcePath(source, skill.path, resolvedSourceDir, realRoot);
@@ -108,21 +112,84 @@ export async function planDeploy(manifest, sourceDir, detectedAgents, home) {
             const agent = AGENT_REGISTRY_BY_ID[agentId];
             if (!agent)
                 continue;
-            const target = resolveAgentSkillPath(agent, skill.name, home);
             actions.push({
                 kind: "skill-dir",
                 skill: skill.name,
                 agent: agentId,
                 source,
-                target,
+                target: resolveAgentSkillPath(agent, skill.name, home),
                 method,
                 confidence: agent.provenance.skills,
             });
         }
     }
+    return actions;
+}
+async function planFileWriteActions(manifest, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home) {
+    const actions = [];
+    for (const fileEntry of manifest.files ?? []) {
+        const source = path.resolve(sourceDir, fileEntry.path);
+        await validateSourcePath(source, fileEntry.path, resolvedSourceDir, realRoot);
+        await validateSourceFile(source, fileEntry.path);
+        for (const agentId of fileEntry.agents) {
+            if (!detectedAgents.includes(agentId))
+                continue;
+            const agent = AGENT_REGISTRY_BY_ID[agentId];
+            if (!agent)
+                continue;
+            actions.push({
+                kind: "file-write",
+                skill: fileEntry.name,
+                agent: agentId,
+                source,
+                target: resolveTargetTemplate(fileEntry.target, home),
+                confidence: agent.provenance.skills,
+            });
+        }
+    }
+    return actions;
+}
+function planConfigPatchActions(manifest, detectedAgents, home) {
+    const actions = [];
+    for (const configEntry of manifest.configs ?? []) {
+        for (const agentId of configEntry.agents) {
+            if (!detectedAgents.includes(agentId))
+                continue;
+            const agent = AGENT_REGISTRY_BY_ID[agentId];
+            if (!agent)
+                continue;
+            actions.push({
+                kind: "config-patch",
+                skill: configEntry.name,
+                agent: agentId,
+                target: resolveTargetTemplate(configEntry.target, home),
+                patch: configEntry.patch,
+                confidence: agent.provenance.skills,
+            });
+        }
+    }
+    return actions;
+}
+export async function planDeploy(manifest, sourceDir, detectedAgents, home) {
+    const resolvedSourceDir = path.resolve(sourceDir);
+    let realRoot;
+    try {
+        realRoot = await realpath(resolvedSourceDir);
+    }
+    catch {
+        realRoot = resolvedSourceDir;
+    }
+    const actions = [
+        ...(await planSkillDirActions(manifest, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home)),
+        ...(await planFileWriteActions(manifest, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home)),
+        ...planConfigPatchActions(manifest, detectedAgents, home),
+    ];
+    const adapterResult = await compileAdapterActions(manifest.mcpServers, manifest.agentRules, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home);
+    actions.push(...adapterResult.actions);
     const warnings = [
         ...detectAmbiguities(detectedAgents),
         ...detectCollisions(actions),
+        ...adapterResult.warnings,
     ];
     return { actions, warnings };
 }
@@ -180,8 +247,6 @@ async function deploySkillDir(action, dryRun, verbose, home, planned) {
         return { error: msg };
     }
     if (dryRun) {
-        logger.plan(label);
-        logger.detail(`${action.method}: ${action.source} -> ${action.target}`);
         planned.push({
             verb: action.method === "symlink" ? "create-symlink" : "copy-dir",
             kind: "skill-dir",
@@ -215,8 +280,6 @@ async function deployFileWrite(action, dryRun, verbose, home, planned) {
         return { error: msg };
     }
     if (dryRun) {
-        logger.plan(label);
-        logger.detail(`write-file: ${action.source} -> ${action.target}`);
         planned.push({
             verb: "write-file",
             kind: "file-write",
@@ -275,8 +338,6 @@ async function deployConfigPatch(action, dryRun, verbose, home, planned) {
     }
     const patch = action.patch;
     if (dryRun) {
-        logger.plan(label);
-        logger.detail(`patch-config: ${JSON.stringify(patch)} -> ${action.target}`);
         planned.push({
             verb: "patch-config",
             kind: "config-patch",
@@ -318,23 +379,6 @@ async function deployConfigPatch(action, dryRun, verbose, home, planned) {
         return { error: msg };
     }
 }
-async function validateSourcePath(source, skillPath, resolvedSourceDir, realRoot) {
-    if (!source.startsWith(resolvedSourceDir + path.sep)) {
-        throw new UserError("DEPLOY_FAILED", `Skill path "${skillPath}" resolves outside the repository root: ${source}`);
-    }
-    try {
-        const realSource = await realpath(source);
-        if (realSource !== realRoot &&
-            !realSource.startsWith(realRoot + path.sep)) {
-            throw new UserError("DEPLOY_FAILED", `Skill path "${skillPath}" resolves outside the repository root via symlink: ${source} -> ${realSource}`);
-        }
-    }
-    catch (err) {
-        if (err instanceof UserError)
-            throw err;
-        // Source doesn't exist yet — will be caught during execute
-    }
-}
 async function validateSkillContract(source, skillPath) {
     let stat;
     try {
@@ -354,9 +398,23 @@ async function validateSkillContract(source, skillPath) {
         throw new UserError("DEPLOY_FAILED", `Skill "${skillPath}" source is not a directory: ${source}`);
     }
     try {
-        await access(path.join(source, "SKILL.md"));
+        await access(source, constants.R_OK);
     }
-    catch {
+    catch (err) {
+        const code = err.code;
+        if (code === "EACCES" || code === "EPERM") {
+            throw new UserError("DEPLOY_FAILED", `Permission denied reading skill directory "${skillPath}": ${source}`);
+        }
+        throw new UserError("DEPLOY_FAILED", `Cannot read skill directory "${skillPath}": ${source}`);
+    }
+    try {
+        await access(path.join(source, "SKILL.md"), constants.R_OK);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "EACCES" || code === "EPERM") {
+            throw new UserError("DEPLOY_FAILED", `Permission denied reading SKILL.md in skill "${skillPath}": ${source}`);
+        }
         throw new UserError("DEPLOY_FAILED", `Skill "${skillPath}" source is missing SKILL.md: ${source}`);
     }
 }
@@ -437,17 +495,15 @@ async function backupExisting(targetPath, verbose, home, expected) {
         throw new Error(`Target "${targetPath}" exists but is not managed by inception-engine — refusing to overwrite`);
     }
     const backupPath = `${targetPath}.inception-backup`;
-    // Clean up any stale backup from a previous failed attempt
-    try {
-        await lstat(backupPath);
-        await removeTarget(backupPath);
-    }
-    catch {
-        // No stale backup — expected
-    }
     if (verbose) {
         logger.detail(`backing up existing target: ${targetPath}`);
     }
+    // Remove any stale backup from a previous failed attempt. Using rm with
+    // { force: true } avoids a separate lstat existence check and handles
+    // the case where the stale backup is a directory (which rename cannot
+    // atomically replace on POSIX). This reduces the window between the
+    // stale-backup removal and the rename to a single step.
+    await rm(backupPath, { recursive: true, force: true });
     await rename(targetPath, backupPath);
     return backupPath;
 }

package/dist/core/preflight.js

@@ -17,6 +17,12 @@ export async function runPreflight(_options, _manifest, _home, detectedAgents) {
                 message: `Agent "${agentId}" skill support is provisional: behavior has not been independently verified.`,
             });
         }
+        if (agent.policyNote) {
+            warnings.push({
+                kind: "policy",
+                message: `Agent "${agentId}": ${agent.policyNote}`,
+            });
+        }
     }
     return warnings;
 }

package/dist/core/resolve.d.ts

@@ -9,3 +9,4 @@ export declare function resolveAgentSkillPathFor(agent: AgentConfig, skillName:
 export declare function resolveAgentDetectPathFor(agent: AgentConfig, home: string, platform: "posix" | "windows"): string;
 export declare function resolveAgentSkillPath(agent: AgentConfig, skillName: string, home: string): string;
 export declare function resolveAgentDetectPath(agent: AgentConfig, home: string): string;
+export declare function resolvePlaceholders(segments: string[], skillName: string, home: string): string;

package/dist/core/resolve.js

@@ -96,7 +96,7 @@ export function resolveAgentSkillPath(agent, skillName, home) {
 export function resolveAgentDetectPath(agent, home) {
     return resolveAgentDetectPathFor(agent, home, getPlatformKey());
 }
-function resolvePlaceholders(segments, skillName, home) {
+export function resolvePlaceholders(segments, skillName, home) {
     const appdata = process.env.APPDATA ?? path.join(home, "AppData", "Roaming");
     const xdgRaw = process.env.XDG_CONFIG_HOME;
     const xdgConfig = xdgRaw && path.isAbsolute(xdgRaw) ? xdgRaw : path.join(home, ".config");

package/dist/core/revert.js

@@ -1,46 +1,94 @@
 import { lstat, readFile, rm, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
 import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
 import { logger } from "../logger.js";
+import { compileMcpServerReverts, compileAgentRuleReverts, } from "./adapters/index.js";
 import { lookupDeployment, unregisterDeployment } from "./ownership.js";
 import { resolveAgentSkillPath } from "./resolve.js";
-export function planRevert(manifest, detectedAgents, home) {
+function resolveTargetTemplate(template, home) {
+    const appdata = process.env.APPDATA ?? path.join(home, "AppData", "Roaming");
+    const xdgRaw = process.env.XDG_CONFIG_HOME;
+    const xdgConfig = xdgRaw && path.isAbsolute(xdgRaw) ? xdgRaw : path.join(home, ".config");
+    return template
+        .replace("{home}", home)
+        .replace("{appdata}", appdata)
+        .replace("{xdg_config}", xdgConfig);
+}
+function buildSkillDirReverts(manifest, home, agentFilter) {
     const actions = [];
     for (const skill of manifest.skills) {
         for (const agentId of skill.agents) {
-            if (!detectedAgents.includes(agentId))
+            if (agentFilter && !agentFilter.includes(agentId))
                 continue;
             const agent = AGENT_REGISTRY_BY_ID[agentId];
             if (!agent)
                 continue;
-            const target = resolveAgentSkillPath(agent, skill.name, home);
             actions.push({
                 kind: "skill-dir",
                 skill: skill.name,
                 agent: agentId,
-                target,
+                target: resolveAgentSkillPath(agent, skill.name, home),
             });
         }
     }
     return actions;
 }
-export function planRevertAll(manifest, home) {
+function buildFileWriteReverts(manifest, home, agentFilter) {
     const actions = [];
-    for (const skill of manifest.skills) {
-        for (const agentId of skill.agents) {
+    for (const fileEntry of manifest.files ?? []) {
+        for (const agentId of fileEntry.agents) {
+            if (agentFilter && !agentFilter.includes(agentId))
+                continue;
             const agent = AGENT_REGISTRY_BY_ID[agentId];
             if (!agent)
                 continue;
-            const target = resolveAgentSkillPath(agent, skill.name, home);
             actions.push({
-                kind: "skill-dir",
-                skill: skill.name,
+                kind: "file-write",
+                skill: fileEntry.name,
+                agent: agentId,
+                target: resolveTargetTemplate(fileEntry.target, home),
+            });
+        }
+    }
+    return actions;
+}
+function buildConfigPatchReverts(manifest, home, agentFilter) {
+    const actions = [];
+    for (const configEntry of manifest.configs ?? []) {
+        for (const agentId of configEntry.agents) {
+            if (agentFilter && !agentFilter.includes(agentId))
+                continue;
+            const agent = AGENT_REGISTRY_BY_ID[agentId];
+            if (!agent)
+                continue;
+            actions.push({
+                kind: "config-patch",
+                skill: configEntry.name,
                 agent: agentId,
-                target,
+                target: resolveTargetTemplate(configEntry.target, home),
             });
         }
     }
     return actions;
 }
+export function planRevert(manifest, detectedAgents, home) {
+    return [
+        ...buildSkillDirReverts(manifest, home, detectedAgents),
+        ...buildFileWriteReverts(manifest, home, detectedAgents),
+        ...buildConfigPatchReverts(manifest, home, detectedAgents),
+        ...(manifest.mcpServers ?? []).flatMap((e) => compileMcpServerReverts(e, detectedAgents, home)),
+        ...(manifest.agentRules ?? []).flatMap((e) => compileAgentRuleReverts(e, detectedAgents, home)),
+    ];
+}
+export function planRevertAll(manifest, home) {
+    return [
+        ...buildSkillDirReverts(manifest, home, null),
+        ...buildFileWriteReverts(manifest, home, null),
+        ...buildConfigPatchReverts(manifest, home, null),
+        ...(manifest.mcpServers ?? []).flatMap((e) => compileMcpServerReverts(e, null, home)),
+        ...(manifest.agentRules ?? []).flatMap((e) => compileAgentRuleReverts(e, null, home)),
+    ];
+}
 function recordOutcome(result, action, counts, failed) {
     if (result.outcome === "fail") {
         failed.push({ action, error: result.error });
@@ -66,12 +114,18 @@ 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;
         }
@@ -114,9 +168,8 @@ export async function executeRevert(actions, dryRun, verbose, home) {
 }
 async function executeRevertAction(action, dryRun, verbose, home, planned) {
     const label = `${action.skill} -> ${action.agent}`;
-    let stat;
     try {
-        stat = await lstat(action.target);
+        await lstat(action.target);
     }
     catch (err) {
         const result = lstatOutcome(err);
@@ -133,8 +186,6 @@ async function executeRevertAction(action, dryRun, verbose, home, planned) {
         return { outcome: "skip" };
     }
     if (dryRun) {
-        logger.plan(label);
-        logger.detail(`would remove: ${action.target}`);
         planned.push({
             verb: "remove",
             kind: "skill-dir",
@@ -145,7 +196,10 @@ async function executeRevertAction(action, dryRun, verbose, home, planned) {
         return { outcome: "ok" };
     }
     try {
-        if (stat.isSymbolicLink()) {
+        // Re-stat immediately before deletion to minimise the window between the
+        // type-check and the removal syscall.
+        const currentStat = await lstat(action.target);
+        if (currentStat.isSymbolicLink()) {
             await unlink(action.target);
         }
         else {
@@ -159,6 +213,11 @@ async function executeRevertAction(action, dryRun, verbose, home, planned) {
         return { outcome: "ok" };
     }
     catch (err) {
+        if (err.code === "ENOENT") {
+            // Target disappeared between ownership check and removal — treat as skip.
+            logger.skip(label, "(disappeared before removal, skipping)");
+            return { outcome: "skip" };
+        }
         const msg = err instanceof Error ? err.message : String(err);
         logger.fail(label, msg);
         return { outcome: "fail", error: msg };
@@ -184,8 +243,6 @@ async function revertFileWrite(action, dryRun, verbose, home, planned) {
         return { outcome: "skip" };
     }
     if (dryRun) {
-        logger.plan(label);
-        logger.detail(`would remove: ${action.target}`);
         planned.push({
             verb: "remove",
             kind: "file-write",
@@ -196,6 +253,9 @@ async function revertFileWrite(action, dryRun, verbose, home, planned) {
         return { outcome: "ok" };
     }
     try {
+        // Re-stat immediately before deletion to minimise the type-check to
+        // removal window; handle the case where the file has since disappeared.
+        await lstat(action.target);
         await unlink(action.target);
         await unregisterDeployment(home, action.target);
         logger.ok(label);
@@ -205,6 +265,10 @@ async function revertFileWrite(action, dryRun, verbose, home, planned) {
         return { outcome: "ok" };
     }
     catch (err) {
+        if (err.code === "ENOENT") {
+            logger.skip(label, "(disappeared before removal, skipping)");
+            return { outcome: "skip" };
+        }
         const msg = err instanceof Error ? err.message : String(err);
         logger.fail(label, msg);
         return { outcome: "fail", error: msg };
@@ -234,8 +298,6 @@ async function revertConfigPatch(action, dryRun, verbose, home, planned) {
     }
     const configPatchEntry = entry;
     if (dryRun) {
-        logger.plan(label);
-        logger.detail(`would unapply patch: ${JSON.stringify(configPatchEntry.undoPatch)} -> ${action.target}`);
         planned.push({
             verb: "unapply-patch",
             kind: "config-patch",

package/dist/core/validation.d.ts

@@ -0,0 +1,3 @@
+export declare function sourceAccessError(err: unknown, sourcePath: string): string;
+export declare function validateSourcePath(source: string, skillPath: string, resolvedSourceDir: string, realRoot: string): Promise<void>;
+export declare function validateSourceFile(sourcePath: string, manifestPath: string): Promise<void>;

package/dist/core/validation.js

@@ -0,0 +1,41 @@
+import { lstat, realpath } from "node:fs/promises";
+import path from "node:path";
+import { UserError } from "../errors.js";
+export function sourceAccessError(err, sourcePath) {
+    const code = err.code;
+    if (code === "ENOENT")
+        return `Source not found: ${sourcePath}`;
+    if (code === "EACCES" || code === "EPERM")
+        return `Permission denied accessing source: ${sourcePath}`;
+    const detail = err instanceof Error ? err.message : String(err);
+    return `Failed to access source ${sourcePath}: ${detail}`;
+}
+export async function validateSourcePath(source, skillPath, resolvedSourceDir, realRoot) {
+    if (!source.startsWith(resolvedSourceDir + path.sep)) {
+        throw new UserError("DEPLOY_FAILED", `Skill path "${skillPath}" resolves outside the repository root: ${source}`);
+    }
+    try {
+        const realSource = await realpath(source);
+        if (realSource !== realRoot &&
+            !realSource.startsWith(realRoot + path.sep)) {
+            throw new UserError("DEPLOY_FAILED", `Skill path "${skillPath}" resolves outside the repository root via symlink: ${source} -> ${realSource}`);
+        }
+    }
+    catch (err) {
+        if (err instanceof UserError)
+            throw err;
+        // Source doesn't exist yet — will be caught during execute
+    }
+}
+export async function validateSourceFile(sourcePath, manifestPath) {
+    let stat;
+    try {
+        stat = await lstat(sourcePath);
+    }
+    catch (err) {
+        throw new UserError("DEPLOY_FAILED", sourceAccessError(err, manifestPath));
+    }
+    if (!stat.isFile()) {
+        throw new UserError("DEPLOY_FAILED", `Source is not a file: ${manifestPath}`);
+    }
+}

package/dist/index.js

@@ -111,6 +111,21 @@ async function main() {
     }
     return runRevert(options, manifest, home);
 }
+function renderDryRunPlan(planned) {
+    for (const change of planned) {
+        logger.plan(`[${change.agent}] ${change.verb}  ${change.skill}`);
+        if (change.source !== undefined) {
+            logger.detail(`source: ${change.source}`);
+        }
+        logger.detail(`target: ${change.target}`);
+        if (change.verb === "patch-config" && change.patch !== undefined) {
+            logger.detail(`patch:  ${JSON.stringify(change.patch)}`);
+        }
+        else if (change.verb === "unapply-patch" && change.patch !== undefined) {
+            logger.detail(`undo:   ${JSON.stringify(change.patch)}`);
+        }
+    }
+}
 async function runDeploy(options, manifest, home) {
     let detectedAgents;
     if (options.agents) {
@@ -132,7 +147,8 @@ async function runDeploy(options, manifest, home) {
     }
     const preflightWarnings = await runPreflight(options, manifest, home, detectedAgents);
     for (const w of preflightWarnings) {
-        logger.warn("preflight", w.message);
+        const label = w.kind === "policy" ? "policy" : "preflight";
+        logger.warn(label, w.message);
     }
     const { actions, warnings: planWarnings } = await planDeploy(manifest, options.directory, detectedAgents, home);
     for (const w of planWarnings) {
@@ -142,14 +158,21 @@ async function runDeploy(options, manifest, home) {
         logger.info("No skills to deploy for detected agents.");
         return 0;
     }
-    logger.info(`${dryRunPrefix(options.dryRun)}Deploying ${actions.length} skill(s):`);
-    const { succeeded, failed } = await executeDeploy(actions, options.dryRun, options.verbose, home);
+    logger.info(`${dryRunPrefix(options.dryRun)}Deploying ${actions.length} action(s):`);
+    const { succeeded, failed, planned } = await executeDeploy(actions, options.dryRun, options.verbose, home);
+    if (options.dryRun) {
+        logger.info("");
+        renderDryRunPlan(planned);
+        logger.info("");
+        logger.info(`${planned.length} action(s) would be applied (dry-run)`);
+        return 0;
+    }
     logger.info("");
     if (failed.length > 0) {
         logger.info(`${succeeded} succeeded, ${failed.length} failed`);
         return 1;
     }
-    logger.info(`${succeeded} skill(s) deployed${options.dryRun ? " (dry-run)" : ""}`);
+    logger.info(`${succeeded} action(s) deployed`);
     return 0;
 }
 async function runRevert(options, manifest, home) {
@@ -160,21 +183,28 @@ async function runRevert(options, manifest, home) {
         logger.info("No skills to revert.");
         return 0;
     }
-    logger.info(`${dryRunPrefix(options.dryRun)}Reverting ${actions.length} skill(s):`);
-    const { succeeded, skipped, failed } = await executeRevert(actions, options.dryRun, options.verbose, home);
+    logger.info(`${dryRunPrefix(options.dryRun)}Reverting ${actions.length} action(s):`);
+    const { succeeded, skipped, failed, planned } = await executeRevert(actions, options.dryRun, options.verbose, home);
+    if (options.dryRun) {
+        logger.info("");
+        renderDryRunPlan(planned);
+        logger.info("");
+        logger.info(`${planned.length} action(s) would be removed (dry-run)`);
+        return 0;
+    }
     logger.info("");
     if (failed.length > 0) {
         const parts = [`${succeeded} removed`];
         if (skipped > 0)
             parts.push(`${skipped} skipped`);
         parts.push(`${failed.length} failed`);
-        logger.info(`${parts.join(", ")}${options.dryRun ? " (dry-run)" : ""}`);
+        logger.info(parts.join(", "));
         return 1;
     }
     const parts = [`${succeeded} removed`];
     if (skipped > 0)
         parts.push(`${skipped} skipped`);
-    logger.info(`${parts.join(", ")}${options.dryRun ? " (dry-run)" : ""}`);
+    logger.info(parts.join(", "));
     return 0;
 }
 const USER_ERROR_EXIT = {

package/dist/schemas/manifest.d.ts

@@ -22,6 +22,56 @@ export declare const SkillEntrySchema: 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")[]>>;
 }, z.core.$strip>;
+export declare const FileEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    path: z.ZodString;
+    target: z.ZodString;
+    agents: z.ZodPipe<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodEnum<{
+        "claude-code": "claude-code";
+        codex: "codex";
+        "gemini-cli": "gemini-cli";
+        antigravity: "antigravity";
+        opencode: "opencode";
+        "github-copilot": "github-copilot";
+    }>>>, z.ZodTransform<("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[], ("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[]>>;
+}, z.core.$strip>;
+export declare const ConfigEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    target: z.ZodString;
+    patch: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    agents: z.ZodPipe<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodEnum<{
+        "claude-code": "claude-code";
+        codex: "codex";
+        "gemini-cli": "gemini-cli";
+        antigravity: "antigravity";
+        opencode: "opencode";
+        "github-copilot": "github-copilot";
+    }>>>, z.ZodTransform<("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[], ("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[]>>;
+}, z.core.$strip>;
+export declare const McpServerEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    agents: z.ZodPipe<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodEnum<{
+        "claude-code": "claude-code";
+        codex: "codex";
+        "gemini-cli": "gemini-cli";
+        antigravity: "antigravity";
+        opencode: "opencode";
+        "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>;
+}, z.core.$strip>;
+export declare const AgentRuleEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    agents: z.ZodPipe<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodEnum<{
+        "claude-code": "claude-code";
+        codex: "codex";
+        "gemini-cli": "gemini-cli";
+        antigravity: "antigravity";
+        opencode: "opencode";
+        "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;
+}, z.core.$strip>;
 export declare const ManifestSchema: z.ZodObject<{
     skills: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -35,10 +85,62 @@ 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")[]>>;
     }, z.core.$strip>>;
-    mcpServers: z.ZodDefault<z.ZodArray<z.ZodUnknown>>;
-    agentRules: z.ZodDefault<z.ZodArray<z.ZodUnknown>>;
+    files: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        path: z.ZodString;
+        target: z.ZodString;
+        agents: z.ZodPipe<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodEnum<{
+            "claude-code": "claude-code";
+            codex: "codex";
+            "gemini-cli": "gemini-cli";
+            antigravity: "antigravity";
+            opencode: "opencode";
+            "github-copilot": "github-copilot";
+        }>>>, z.ZodTransform<("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[], ("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[]>>;
+    }, z.core.$strip>>>;
+    configs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        target: z.ZodString;
+        patch: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        agents: z.ZodPipe<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodEnum<{
+            "claude-code": "claude-code";
+            codex: "codex";
+            "gemini-cli": "gemini-cli";
+            antigravity: "antigravity";
+            opencode: "opencode";
+            "github-copilot": "github-copilot";
+        }>>>, z.ZodTransform<("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[], ("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[]>>;
+    }, z.core.$strip>>>;
+    mcpServers: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        agents: z.ZodPipe<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodEnum<{
+            "claude-code": "claude-code";
+            codex: "codex";
+            "gemini-cli": "gemini-cli";
+            antigravity: "antigravity";
+            opencode: "opencode";
+            "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>;
+    }, z.core.$strip>>>;
+    agentRules: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        agents: z.ZodPipe<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodEnum<{
+            "claude-code": "claude-code";
+            codex: "codex";
+            "gemini-cli": "gemini-cli";
+            antigravity: "antigravity";
+            opencode: "opencode";
+            "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;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type SkillEntry = z.infer<typeof SkillEntrySchema>;
+export type FileEntry = z.infer<typeof FileEntrySchema>;
+export type ConfigEntry = z.infer<typeof ConfigEntrySchema>;
+export type McpServerEntry = z.infer<typeof McpServerEntrySchema>;
+export type AgentRuleEntry = z.infer<typeof AgentRuleEntrySchema>;
 export type Manifest = z.infer<typeof ManifestSchema>;
 export declare const AgentListSchema: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>, z.ZodArray<z.ZodPipe<z.ZodString, z.ZodEnum<{
     "claude-code": "claude-code";

package/dist/schemas/manifest.js

@@ -10,6 +10,9 @@ const AGENT_IDS = [
 ];
 export { AGENT_IDS };
 const SAFE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+// Target templates must start with a known placeholder to prevent raw absolute
+// paths or directory traversal. e.g. "{home}/.claude/settings.json" is valid.
+const TARGET_TEMPLATE_RE = /^\{(home|appdata|xdg_config)\}/;
 // Standalone schema used for type derivation and single-ID validation (e.g. index.ts).
 export const AgentIdSchema = z.enum(AGENT_IDS);
 // Used inside SkillEntrySchema.agents so that enum failures embed the received
@@ -26,26 +29,60 @@ const agentIdElement = z
     }
 })
     .pipe(AgentIdSchema);
+const nameField = z
+    .string({ message: "name must be a non-empty string" })
+    .min(1, { message: "name must be a non-empty string" })
+    .regex(SAFE_NAME_RE, {
+    message: "name must contain only letters, digits, hyphens, underscores, and dots, and must not start with a dot",
+});
+const agentsField = z
+    .array(agentIdElement, { message: "agents must be a non-empty array" })
+    .min(1, { message: "agents must be a non-empty array" })
+    .transform((arr) => [...new Set(arr)]);
+const sourcePathField = z
+    .string({ message: "path must be a non-empty string" })
+    .min(1, { message: "path must be a non-empty string" })
+    .refine((p) => !nodePath.isAbsolute(p), {
+    message: "path must be a relative path",
+})
+    .refine((p) => !nodePath.normalize(p).startsWith(".."), {
+    message: "path must not escape the repository root",
+});
+const targetTemplateField = z
+    .string({ message: "target must be a non-empty string" })
+    .min(1, { message: "target must be a non-empty string" })
+    .refine((t) => TARGET_TEMPLATE_RE.test(t), {
+    message: "target must start with a known placeholder: {home}, {appdata}, or {xdg_config}",
+});
 export const SkillEntrySchema = z.object({
-    name: z
-        .string({ message: "name must be a non-empty string" })
-        .min(1, { message: "name must be a non-empty string" })
-        .regex(SAFE_NAME_RE, {
-        message: "name must contain only letters, digits, hyphens, underscores, and dots, and must not start with a dot",
-    }),
-    path: z
-        .string({ message: "path must be a non-empty string" })
-        .min(1, { message: "path must be a non-empty string" })
-        .refine((p) => !nodePath.isAbsolute(p), {
-        message: "path must be a relative path",
-    })
-        .refine((p) => !nodePath.normalize(p).startsWith(".."), {
-        message: "path must not escape the repository root",
-    }),
-    agents: z
-        .array(agentIdElement, { message: "agents must be a non-empty array" })
-        .min(1, { message: "agents must be a non-empty array" })
-        .transform((arr) => [...new Set(arr)]),
+    name: nameField,
+    path: sourcePathField,
+    agents: agentsField,
+});
+export const FileEntrySchema = z.object({
+    name: nameField,
+    path: sourcePathField,
+    target: targetTemplateField,
+    agents: agentsField,
+});
+export const ConfigEntrySchema = z.object({
+    name: nameField,
+    target: targetTemplateField,
+    patch: z.record(z.string(), z.unknown()),
+    agents: agentsField,
+});
+export const McpServerEntrySchema = z.object({
+    name: nameField,
+    agents: agentsField,
+    // 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()),
+});
+export const AgentRuleEntrySchema = z.object({
+    name: nameField,
+    agents: agentsField,
+    // Relative path to the rules/instruction file within the source bundle.
+    path: sourcePathField,
 });
 export const ManifestSchema = z.object({
     skills: z.array(SkillEntrySchema).superRefine((skills, ctx) => {
@@ -61,8 +98,10 @@ export const ManifestSchema = z.object({
             seen.add(skill.name);
         }
     }),
-    mcpServers: z.array(z.unknown()).default([]),
-    agentRules: z.array(z.unknown()).default([]),
+    files: z.array(FileEntrySchema).default([]),
+    configs: z.array(ConfigEntrySchema).default([]),
+    mcpServers: z.array(McpServerEntrySchema).default([]),
+    agentRules: z.array(AgentRuleEntrySchema).default([]),
 });
 // Parses the --agents CLI flag: comma-separated agent IDs → AgentId[]
 export const AgentListSchema = z

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 import type { AgentId } from "./schemas/manifest.ts";
-export type { AgentId, Manifest, SkillEntry } from "./schemas/manifest.ts";
+export type { AgentId, ConfigEntry, FileEntry, Manifest, SkillEntry, } from "./schemas/manifest.ts";
 export interface AgentPaths {
     posix: string[];
     windows: string[];
@@ -9,6 +9,8 @@ export interface AgentProvenance {
     skills: Confidence;
     detectPaths: Confidence;
     detectBinary: Confidence;
+    mcpConfig?: Confidence;
+    agentRules?: Confidence;
 }
 export interface AgentConfig {
     id: AgentId;
@@ -17,6 +19,9 @@ export interface AgentConfig {
     detectPaths: AgentPaths;
     detectBinary: string | null;
     provenance: AgentProvenance;
+    mcpConfigPath?: AgentPaths;
+    agentRulesPath?: AgentPaths;
+    policyNote?: string;
 }
 export interface PlanWarning {
     kind: "confidence" | "collision" | "ambiguity";

package/package.json

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