@kuznai/inception-engine 0.8.0 → 0.10.1

package/README.md

@@ -2,7 +2,9 @@
 
 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 deploys skills, single files, and JSON config patches to AI coding agents. MCP configuration and agent rules remain unimplemented at the manifest level.
+Today, inception-engine works as a cross-agent deployer for skills on all listed agents, plus single-file writes and JSON config patches. It also supports MCP server registration and global rules-file deployment for the subset of agents whose config surfaces are implemented and validated today.
+
+The broader portability layer is the roadmap direction, but this README focuses on what is working now.
 
 ## Quick Start
 
@@ -38,13 +40,15 @@ 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 | Supported via manifest and CLI |
-| Config patch (JSON merge) | Supported via manifest and CLI |
-| 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; other agents are warned and skipped | claude-code, gemini-cli |
+| Global Rules Files | claude-code, codex, gemini-cli, opencode; other agents are warned and skipped | claude-code, codex, gemini-cli, opencode |
+
+Features that depend on agent-specific config surfaces are intentionally conservative: if a target path or schema is not implemented with enough confidence, inception-engine warns and skips it rather than guessing.
 
 ## Manifest Format
 
@@ -75,8 +79,20 @@ Create an `inception.json` file at the root of your skills directory:
       "agents": ["claude-code"]
     }
   ],
-  "mcpServers": [],
-  "agentRules": []
+  "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"]
+    }
+  ]
 }
 ```
 
@@ -97,12 +113,26 @@ Each **config** entry applies a [JSON merge patch (RFC 7386)](https://datatracke
 
 - **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).
+- **patch** - JSON object of keys to set. A `null` value removes the key from the target file. Nested object values are merged recursively; non-object values replace the existing value directly.
 - **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.
 
-`mcpServers` and `agentRules` are currently parsed for forward compatibility, but the deployment engine ignores them today.
+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 an agent's supported global rules file 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
+
+Global rules-file 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 because their instruction surfaces are different, repo-scoped, or not implemented here yet. Revert removes the deployed rules file.
 
 ## Creating Skills
 
@@ -119,7 +149,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
 
@@ -149,19 +179,19 @@ inception-engine revert <directory> [options]
 
 ```bash
 # Deploy all skills to all detected agents
-npx inception-engine ./my-skills-repo
+npx @kuznai/inception-engine ./my-skills-repo
 
 # Preview what would be deployed
-npx inception-engine ./my-skills-repo --dry-run
+npx @kuznai/inception-engine ./my-skills-repo --dry-run
 
 # Deploy only to Claude Code and Codex
-npx inception-engine ./my-skills-repo --agents claude-code,codex
+npx @kuznai/inception-engine ./my-skills-repo --agents claude-code,codex
 
 # Remove deployed skills
-npx inception-engine revert ./my-skills-repo
+npx @kuznai/inception-engine revert ./my-skills-repo
 
 # Preview what would be removed
-npx inception-engine revert ./my-skills-repo --dry-run
+npx @kuznai/inception-engine revert ./my-skills-repo --dry-run
 ```
 
 ## Sample Skills
@@ -171,7 +201,7 @@ The `limbo/` directory contains exceptional sample skills for testing purposes o
 Try them out:
 
 ```bash
-npx inception-engine limbo --dry-run
+npx @kuznai/inception-engine limbo --dry-run
 ```
 
 ## Agent Detection
@@ -195,13 +225,13 @@ Revert targets all agents listed in the manifest by default (regardless of detec
 
 ### Ownership Tracking and Safe Revert
 
-inception-engine maintains a centralized deployment registry at `~/.inception-engine/registry.json`. Each deploy records the target path, source path, skill name, agent ID, deploy method, and timestamp. No files are written to the source repository.
+inception-engine maintains a centralized deployment registry at `~/.inception-engine/registry.json`. Each deploy records the target path, skill name, agent ID, action-specific provenance (`source`/`method` for skill-dir, `source` for file-write, `patch`/`undoPatch` for config-patch), and timestamp. No files are written to the source repository.
 
 - **Registry-based ownership**: On revert, the registry is checked before removing any target. Only targets with a valid registry entry are removed. On redeploy, unmanaged targets are never replaced.
 
-- **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.
+- **Strong binding**: Each registry entry binds a specific target path to its skill, agent, and action kind. For `skill-dir` and `file-write`, ownership checks also require the recorded `source` to match before an existing target is treated as managed. For `config-patch`, overwrite protection is keyed by target path, kind, skill, and agent; the stored `patch` and `undoPatch` are used for revert bookkeeping rather than deploy-time identity checks.
 
-- **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,7 @@ 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.",
     },
 ];

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

@@ -0,0 +1,11 @@
+import type { AgentRuleEntry, McpServerEntry } from "../../schemas/manifest.ts";
+import type { AgentId, ConfigPatchDeployAction, FileWriteDeployAction, PlanWarning } from "../../types.ts";
+import { compileMcpServerReverts } from "./mcp.ts";
+import { compileAgentRuleReverts } from "./rules.ts";
+export { compileAgentRuleReverts, compileMcpServerReverts };
+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 { compileAgentRuleReverts, compileMcpServerReverts };
+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,56 @@
+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();
+    const targetAgents = entry.agents.filter((agentId) => detectedAgents.includes(agentId));
+    if (targetAgents.length === 0) {
+        return { actions, warnings };
+    }
+    // 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 targetAgents) {
+        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.d.ts

@@ -1,9 +1,10 @@
-import type { AgentId, DeployAction, Manifest, PlannedChange, PlanWarning } from "../types.ts";
+import type { AgentId, DeployAction, Manifest, PlannedChange, PlanWarning, SkillDirDeployAction } from "../types.ts";
+import { type RegistryPersistence } from "./ownership.ts";
 export declare function planDeploy(manifest: Manifest, sourceDir: string, detectedAgents: AgentId[], home: string): Promise<{
     actions: DeployAction[];
     warnings: PlanWarning[];
 }>;
-export declare function executeDeploy(actions: DeployAction[], dryRun: boolean, verbose: boolean, home: string): Promise<{
+export declare function executeDeploy(actions: DeployAction[], dryRun: boolean, verbose: boolean, home: string, deps?: DeployDependencies): Promise<{
     succeeded: number;
     failed: Array<{
         action: DeployAction;
@@ -11,3 +12,22 @@ export declare function executeDeploy(actions: DeployAction[], dryRun: boolean,
     }>;
     planned: PlannedChange[];
 }>;
+interface SkillDirOps {
+    createTarget(action: SkillDirDeployAction): Promise<void>;
+    removeTarget(targetPath: string): Promise<void>;
+}
+interface DeployFileOps {
+    copyFile(source: string, target: string): Promise<void>;
+    rename(source: string, target: string): Promise<void>;
+    rm(targetPath: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    writeFile(filePath: string, content: string, encoding: BufferEncoding): Promise<void>;
+}
+interface DeployDependencies {
+    registry?: RegistryPersistence;
+    skillDirOps?: SkillDirOps;
+    fileOps?: DeployFileOps;
+}
+export {};