@kuznai/inception-engine 0.9.0 → 0.11.0

package/README.md

@@ -1,8 +1,14 @@
 # inception-engine
 
-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.
+Plant skills directly into the minds of your installed AI coding agents — Claude Code, Codex, Gemini CLI, Antigravity, and OpenCode. One command. They'll think they thought of it themselves.
 
-Today, inception-engine deploys skills, single files, JSON config patches, MCP server registrations, and agent instruction files to AI coding agents.
+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.
+
+GitHub Copilot is no longer treated as a separate instruction or skill target in the product direction when it can consume Claude-native artifacts directly. If Copilot uses `CLAUDE.md` or Claude-style skill layouts without translation, inception-engine should rely on the Claude deployment path instead of maintaining duplicate Copilot-specific surfaces. Dedicated Copilot customization remains justified only where Copilot exposes a materially different interface, such as MCP-related configuration.
+
+The broader portability layer is the roadmap direction, but this README focuses on what is working now.
+
+`init` is available as a bootstrap command, but what works today is intentionally narrow: it scans for directories containing `SKILL.md` and generates starter `skills` entries plus empty `mcpServers` and `agentRules` arrays. It does not infer `files`, `configs`, MCP server definitions, or rules files from the repository yet.
 
 ## Quick Start
 
@@ -30,7 +36,6 @@ Managed skills overwrite their previous version. If a target exists but was not
 | Gemini CLI | `gemini-cli` | `~/.gemini/skills/` | Yes | Yes | Yes |
 | Antigravity | `antigravity` | `~/.gemini/antigravity/skills/` | Yes* | Yes* | Yes* |
 | OpenCode | `opencode` | `~/.config/opencode/skills/` | Yes | Yes | Yes* |
-| GitHub Copilot | `github-copilot` | `~/.copilot/skills/` | Yes | Yes | Yes |
 
 \* Antigravity support is currently based on the implementation's registry path assumptions and local validation, not a strong official doc set equivalent to the other agents.
 
@@ -43,8 +48,13 @@ Managed skills overwrite their previous version. If a target exists but was not
 | 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 |
+| 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 |
+| `init` manifest generation | Scans `SKILL.md` directories and writes starter `skills` entries | N/A |
+
+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.
+
+For GitHub Copilot specifically, the portability rule is Claude-first: if Copilot accepts the same Claude-native instruction or skill artifact, inception-engine should not add a separate Copilot deployment feature for it.
 
 ## Manifest Format
 
@@ -56,7 +66,7 @@ Create an `inception.json` file at the root of your skills directory:
     {
       "name": "my-skill",
       "path": "skills/my-skill",
-      "agents": ["claude-code", "codex", "gemini-cli", "antigravity", "opencode", "github-copilot"]
+      "agents": ["claude-code", "codex", "gemini-cli", "antigravity", "opencode"]
     }
   ],
   "files": [
@@ -109,7 +119,7 @@ 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.
@@ -122,13 +132,13 @@ Each **mcpServer** entry registers an MCP server into the agent's config file by
 
 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:
+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
 
-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.
+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
 
@@ -147,11 +157,30 @@ Instructions for the AI agent...
 
 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.
 
+## `init` Command
+
+`init` is meant to bootstrap a repository that already has skill folders. It recursively scans the target directory, treats any directory containing `SKILL.md` as a skill, and writes a starter `inception.json`.
+
+Current `init` behavior:
+
+- Generates `skills` entries using the discovered relative paths
+- Uses the directory name as the manifest skill name
+- Applies either the `--agents` list or all currently known agent IDs
+- Refuses to overwrite an existing `inception.json` unless `--force` is provided
+- Supports `--dry-run` so you can inspect the generated manifest before writing it
+
+Current `init` limitations:
+
+- It does not read or validate YAML frontmatter inside `SKILL.md`
+- It does not infer `files`, `configs`, `mcpServers`, or `agentRules`
+- It does not reconcile generated output with the longer-term Claude-first portability direction
+
 ## CLI Reference
 
 ```
 inception-engine <directory> [options]
 inception-engine revert <directory> [options]
+inception-engine init <directory> [options]
 ```
 
 ### Commands
@@ -160,6 +189,7 @@ inception-engine revert <directory> [options]
 |---|---|
 | `<directory>` | Deploy skills from the manifest in the given directory |
 | `revert <directory>` | Remove previously deployed skills declared in the manifest |
+| `init <directory>` | Scan a directory for skill folders and generate `inception.json` |
 
 ### Options
 
@@ -167,6 +197,7 @@ inception-engine revert <directory> [options]
 |---|---|
 | `--dry-run` | Show what would be done without making changes |
 | `--agents <list>` | Comma-separated list of agent IDs to target (overrides deploy detection; restricts revert) |
+| `--force` | `init` only; overwrite an existing `inception.json` |
 | `--verbose` | Show detailed output including file paths |
 | `--debug` | Show full error stack traces |
 | `--help` | Show help message |
@@ -175,19 +206,25 @@ 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
+
+# Generate a starter manifest from discovered skill folders
+npx @kuznai/inception-engine init ./my-skills-repo
+
+# Preview the generated manifest without writing it
+npx @kuznai/inception-engine init ./my-skills-repo --dry-run
 ```
 
 ## Sample Skills
@@ -197,7 +234,8 @@ 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 init limbo --dry-run
+npx @kuznai/inception-engine limbo --dry-run
 ```
 
 ## Agent Detection
@@ -221,11 +259,11 @@ 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 `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.
 

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

@@ -1,8 +1,8 @@
-import type { McpServerEntry, AgentRuleEntry } from "../../schemas/manifest.ts";
+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 { compileMcpServerReverts, compileAgentRuleReverts };
+export { compileAgentRuleReverts, compileMcpServerReverts };
 export type AdapterAction = ConfigPatchDeployAction | FileWriteDeployAction;
 export interface AdapterResult {
     actions: AdapterAction[];

package/dist/core/adapters/index.js

@@ -1,6 +1,6 @@
 import { compileMcpServerActions, compileMcpServerReverts } from "./mcp.js";
 import { compileAgentRuleActions, compileAgentRuleReverts } from "./rules.js";
-export { compileMcpServerReverts, compileAgentRuleReverts };
+export { compileAgentRuleReverts, compileMcpServerReverts };
 export async function compileAdapterActions(mcpServers, agentRules, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home) {
     const actions = [];
     const warnings = [];

package/dist/core/adapters/rules.js

@@ -6,13 +6,15 @@ export async function compileAgentRuleActions(entry, sourceDir, resolvedSourceDi
     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 entry.agents) {
-        if (!detectedAgents.includes(agentId))
-            continue;
+    for (const agentId of targetAgents) {
         const agent = AGENT_REGISTRY_BY_ID[agentId];
         if (!agent?.agentRulesPath) {
             warnings.push({

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 {};

package/dist/core/deploy.js

@@ -4,14 +4,15 @@ 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 { lookupDeployment, registerDeployment, verifyDeployment, } from "./ownership.js";
 import { getDeployMethod, resolveAgentSkillPath } from "./resolve.js";
+import { resolveTargetTemplate } from "./runtime-paths.js";
 import { sourceAccessError, validateSourceFile, validateSourcePath, } from "./validation.js";
 function isPlainObject(v) {
     return typeof v === "object" && v !== null && !Array.isArray(v);
 }
-async function readJsonConfig(filePath) {
+async function readJsonConfigFile(filePath) {
     let rawContent;
     try {
         rawContent = await readFile(filePath, "utf-8");
@@ -62,15 +63,6 @@ function applyMergePatch(original, patch) {
     }
     return patched;
 }
-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();
     const warnings = [];
@@ -103,12 +95,13 @@ async function planSkillDirActions(manifest, sourceDir, resolvedSourceDir, realR
     const method = getDeployMethod();
     const actions = [];
     for (const skill of manifest.skills) {
+        const targetAgents = skill.agents.filter((agentId) => detectedAgents.includes(agentId));
+        if (targetAgents.length === 0)
+            continue;
         const source = path.resolve(sourceDir, skill.path);
         await validateSourcePath(source, skill.path, resolvedSourceDir, realRoot);
         await validateSkillContract(source, skill.path);
-        for (const agentId of skill.agents) {
-            if (!detectedAgents.includes(agentId))
-                continue;
+        for (const agentId of targetAgents) {
             const agent = AGENT_REGISTRY_BY_ID[agentId];
             if (!agent)
                 continue;
@@ -128,12 +121,13 @@ async function planSkillDirActions(manifest, sourceDir, resolvedSourceDir, realR
 async function planFileWriteActions(manifest, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home) {
     const actions = [];
     for (const fileEntry of manifest.files ?? []) {
+        const targetAgents = fileEntry.agents.filter((agentId) => detectedAgents.includes(agentId));
+        if (targetAgents.length === 0)
+            continue;
         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;
+        for (const agentId of targetAgents) {
             const agent = AGENT_REGISTRY_BY_ID[agentId];
             if (!agent)
                 continue;
@@ -193,14 +187,14 @@ export async function planDeploy(manifest, sourceDir, detectedAgents, home) {
     ];
     return { actions, warnings };
 }
-export async function executeDeploy(actions, dryRun, verbose, home) {
+export async function executeDeploy(actions, dryRun, verbose, home, deps = {}) {
     let succeeded = 0;
     const failed = [];
     const planned = [];
     for (const action of actions) {
         switch (action.kind) {
             case "skill-dir": {
-                const result = await deploySkillDir(action, dryRun, verbose, home, planned);
+                const result = await deploySkillDir(action, dryRun, verbose, home, planned, deps);
                 if (result.error === null) {
                     succeeded++;
                 }
@@ -210,7 +204,7 @@ export async function executeDeploy(actions, dryRun, verbose, home) {
                 break;
             }
             case "file-write": {
-                const result = await deployFileWrite(action, dryRun, verbose, home, planned);
+                const result = await deployFileWrite(action, dryRun, verbose, home, planned, deps);
                 if (result.error === null) {
                     succeeded++;
                 }
@@ -220,7 +214,7 @@ export async function executeDeploy(actions, dryRun, verbose, home) {
                 break;
             }
             case "config-patch": {
-                const result = await deployConfigPatch(action, dryRun, verbose, home, planned);
+                const result = await deployConfigPatch(action, dryRun, verbose, home, planned, deps);
                 if (result.error === null) {
                     succeeded++;
                 }
@@ -236,7 +230,114 @@ export async function executeDeploy(actions, dryRun, verbose, home) {
     }
     return { succeeded, failed, planned };
 }
-async function deploySkillDir(action, dryRun, verbose, home, planned) {
+const defaultSkillDirOps = {
+    async createTarget(action) {
+        if (action.method === "symlink") {
+            await symlink(action.source, action.target, "dir");
+        }
+        else {
+            await cp(action.source, action.target, { recursive: true });
+        }
+    },
+    async removeTarget(targetPath) {
+        const stat = await lstat(targetPath);
+        if (stat.isSymbolicLink()) {
+            await unlink(targetPath);
+        }
+        else {
+            await rm(targetPath, { recursive: true });
+        }
+    },
+};
+const defaultDeployFileOps = {
+    copyFile,
+    rename,
+    rm,
+    writeFile,
+};
+async function removeFileSystemTarget(targetPath) {
+    const stat = await lstat(targetPath);
+    if (stat.isDirectory() && !stat.isSymbolicLink()) {
+        await rm(targetPath, { recursive: true });
+    }
+    else {
+        await unlink(targetPath);
+    }
+}
+async function backupManagedFileWriteTarget(action, home, deps) {
+    try {
+        await lstat(action.target);
+    }
+    catch {
+        return null;
+    }
+    const isOwned = await verifyDeployment(home, action.target, {
+        kind: "file-write",
+        source: action.source,
+        skill: action.skill,
+        agent: action.agent,
+    }, deps.registry);
+    if (!isOwned) {
+        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, {
+        recursive: true,
+        force: true,
+    });
+    await (deps.fileOps ?? defaultDeployFileOps).rename(action.target, backupPath);
+    return backupPath;
+}
+function createAtomicTempPath(targetPath) {
+    return `${targetPath}.inception-tmp-${process.pid}-${Date.now()}-${Math.random()
+        .toString(36)
+        .slice(2)}`;
+}
+async function replaceFileAtomically(targetPath, deps, stageTempFile, prepareBackup, commit) {
+    const fileOps = deps.fileOps ?? defaultDeployFileOps;
+    const tempPath = createAtomicTempPath(targetPath);
+    let backupPath = null;
+    let replacedTarget = false;
+    try {
+        await mkdir(path.dirname(targetPath), { recursive: true });
+        await stageTempFile(tempPath, fileOps);
+        backupPath = await prepareBackup();
+        await fileOps.rename(tempPath, targetPath);
+        replacedTarget = true;
+        await commit();
+    }
+    catch (writeErr) {
+        if (replacedTarget) {
+            try {
+                await removeFileSystemTarget(targetPath);
+            }
+            catch {
+                /* best-effort cleanup */
+            }
+        }
+        else {
+            try {
+                await fileOps.rm(tempPath, { recursive: true, force: true });
+            }
+            catch {
+                /* best-effort cleanup */
+            }
+        }
+        if (backupPath) {
+            try {
+                await fileOps.rename(backupPath, targetPath);
+            }
+            catch {
+                /* best-effort rollback */
+            }
+        }
+        throw writeErr;
+    }
+    if (backupPath) {
+        await fileOps.rm(backupPath, { recursive: true, force: true });
+    }
+}
+async function deploySkillDir(action, dryRun, verbose, home, planned, deps) {
     const label = `${action.skill} -> ${action.agent}`;
     try {
         await access(action.source);
@@ -260,7 +361,7 @@ async function deploySkillDir(action, dryRun, verbose, home, planned) {
         return { error: null };
     }
     try {
-        await executeDeployAction(action, verbose, home);
+        await executeDeployAction(action, verbose, home, deps);
         return { error: null };
     }
     catch (err) {
@@ -269,7 +370,7 @@ async function deploySkillDir(action, dryRun, verbose, home, planned) {
         return { error: msg };
     }
 }
-async function deployFileWrite(action, dryRun, verbose, home, planned) {
+async function deployFileWrite(action, dryRun, verbose, home, planned, deps) {
     const label = `${action.skill} -> ${action.agent}`;
     try {
         await access(action.source);
@@ -291,32 +392,12 @@ async function deployFileWrite(action, dryRun, verbose, home, planned) {
         return { error: null };
     }
     try {
-        // Check if target exists — only allow overwrite if we own it
-        try {
-            await lstat(action.target);
-            const isOwned = await verifyDeployment(home, action.target, {
-                kind: "file-write",
-                source: action.source,
-                skill: action.skill,
-                agent: action.agent,
-            });
-            if (!isOwned) {
-                throw new Error(`Target "${action.target}" exists but is not managed by inception-engine — refusing to overwrite`);
-            }
-        }
-        catch (err) {
-            if (err instanceof Error && err.message.includes("refusing to overwrite"))
-                throw err;
-            // ENOENT — target doesn't exist, fine to create
-        }
-        await mkdir(path.dirname(action.target), { recursive: true });
-        await copyFile(action.source, action.target);
-        await registerDeployment(home, action.target, {
+        await replaceFileAtomically(action.target, deps, (tempPath, fileOps) => fileOps.copyFile(action.source, tempPath), () => backupManagedFileWriteTarget(action, home, deps), () => registerDeployment(home, action.target, {
             kind: "file-write",
             source: action.source,
             skill: action.skill,
             agent: action.agent,
-        });
+        }, deps.registry));
         logger.ok(label);
         if (verbose) {
             logger.detail(`write-file: ${action.source} -> ${action.target}`);
@@ -329,7 +410,7 @@ async function deployFileWrite(action, dryRun, verbose, home, planned) {
         return { error: msg };
     }
 }
-async function deployConfigPatch(action, dryRun, verbose, home, planned) {
+async function deployConfigPatch(action, dryRun, verbose, home, planned, deps) {
     const label = `${action.skill} -> ${action.agent}`;
     if (!isPlainObject(action.patch)) {
         const msg = `Config patch for skill "${action.skill}" must be a plain object`;
@@ -350,23 +431,30 @@ async function deployConfigPatch(action, dryRun, verbose, home, planned) {
     }
     try {
         // Guard against double-patching by a different skill/agent
-        const existingEntry = await lookupDeployment(home, action.target);
+        const existingEntry = await lookupDeployment(home, action.target, deps.registry);
         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`);
         }
-        const original = await readJsonConfig(action.target);
+        const original = await readJsonConfigFile(action.target);
         const undoPatch = computeUndoPatch(original, patch);
         const patched = applyMergePatch(original, patch);
-        await writeFile(action.target, `${JSON.stringify(patched, null, 2)}\n`, "utf-8");
-        await registerDeployment(home, action.target, {
+        await replaceFileAtomically(action.target, deps, (tempPath, fileOps) => fileOps.writeFile(tempPath, `${JSON.stringify(patched, null, 2)}\n`, "utf-8"), async () => {
+            const backupPath = `${action.target}.inception-backup`;
+            await (deps.fileOps ?? defaultDeployFileOps).rm(backupPath, {
+                recursive: true,
+                force: true,
+            });
+            await (deps.fileOps ?? defaultDeployFileOps).rename(action.target, backupPath);
+            return backupPath;
+        }, () => registerDeployment(home, action.target, {
             kind: "config-patch",
             patch,
             undoPatch,
             skill: action.skill,
             agent: action.agent,
-        });
+        }, deps.registry));
         logger.ok(label);
         if (verbose) {
             logger.detail(`patch-config: applied ${Object.keys(patch).length} key(s) to ${action.target}`);
@@ -429,38 +517,35 @@ async function assertTargetAbsent(targetPath) {
         // ENOENT is expected — target should not exist after backup
     }
 }
-async function createDeployTarget(action, home) {
-    if (action.method === "symlink") {
-        await symlink(action.source, action.target, "dir");
-    }
-    else {
-        await cp(action.source, action.target, { recursive: true });
-    }
+async function createDeployTarget(action, home, deps) {
+    await (deps.skillDirOps ?? defaultSkillDirOps).createTarget(action);
     await registerDeployment(home, action.target, {
         kind: action.kind,
         source: action.source,
         skill: action.skill,
         agent: action.agent,
         method: action.method,
-    });
+    }, deps.registry);
 }
-async function executeDeployAction(action, verbose, home) {
+async function executeDeployAction(action, verbose, home, deps) {
     const label = `${action.skill} -> ${action.agent}`;
     const backupPath = await backupExisting(action.target, verbose, home, {
         kind: action.kind,
         source: action.source,
         skill: action.skill,
         agent: action.agent,
-    });
+    }, deps);
     await mkdir(path.dirname(action.target), { recursive: true });
     try {
         await assertTargetAbsent(action.target);
-        await createDeployTarget(action, home);
+        await createDeployTarget(action, home, deps);
     }
     catch (createErr) {
         if (backupPath) {
             try {
-                await removeTarget(action.target).catch(() => {
+                await (deps.skillDirOps ?? defaultSkillDirOps)
+                    .removeTarget(action.target)
+                    .catch(() => {
                     /* best-effort cleanup */
                 });
                 await rename(backupPath, action.target);
@@ -472,14 +557,14 @@ async function executeDeployAction(action, verbose, home) {
         throw createErr;
     }
     if (backupPath) {
-        await removeTarget(backupPath);
+        await (deps.skillDirOps ?? defaultSkillDirOps).removeTarget(backupPath);
     }
     logger.ok(label);
     if (verbose) {
         logger.detail(`${action.method}: ${action.source} -> ${action.target}`);
     }
 }
-async function backupExisting(targetPath, verbose, home, expected) {
+async function backupExisting(targetPath, verbose, home, expected, deps) {
     try {
         await lstat(targetPath);
     }
@@ -491,7 +576,7 @@ async function backupExisting(targetPath, verbose, home, expected) {
         source: expected.source,
         skill: expected.skill,
         agent: expected.agent,
-    }))) {
+    }, deps.registry))) {
         throw new Error(`Target "${targetPath}" exists but is not managed by inception-engine — refusing to overwrite`);
     }
     const backupPath = `${targetPath}.inception-backup`;
@@ -507,12 +592,3 @@ async function backupExisting(targetPath, verbose, home, expected) {
     await rename(targetPath, backupPath);
     return backupPath;
 }
-async function removeTarget(targetPath) {
-    const stat = await lstat(targetPath);
-    if (stat.isSymbolicLink()) {
-        await unlink(targetPath);
-    }
-    else {
-        await rm(targetPath, { recursive: true });
-    }
-}

package/dist/core/init.d.ts

@@ -0,0 +1,9 @@
+import type { AgentId } from "../schemas/manifest.ts";
+export interface InitOptions {
+    directory: string;
+    agents: AgentId[] | null;
+    dryRun: boolean;
+    force: boolean;
+    verbose: boolean;
+}
+export declare function runInit(options: InitOptions): Promise<number>;

package/dist/core/init.js

@@ -0,0 +1,99 @@
+import { access, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { dryRunPrefix, logger } from "../logger.js";
+import { AGENT_IDS } from "../schemas/manifest.js";
+const SAFE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+async function findSkillDirs(baseDir, dir, found) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true, encoding: "utf-8" });
+    }
+    catch {
+        return;
+    }
+    const hasSkillMd = entries.some((e) => e.isFile() && e.name === "SKILL.md");
+    if (hasSkillMd) {
+        const relPath = path.relative(baseDir, dir).split(path.sep).join("/");
+        const name = path.basename(dir);
+        if (SAFE_NAME_RE.test(name)) {
+            found.push({ relPath, name });
+        }
+        else {
+            logger.warn("init", `Skipping "${relPath}": directory name "${name}" is not a valid skill name`);
+        }
+        // Don't recurse into a skill directory
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory() && !entry.name.startsWith(".")) {
+            await findSkillDirs(baseDir, path.join(dir, entry.name), found);
+        }
+    }
+}
+function resolveSkillName(relPath, name, namesSeen) {
+    if (!namesSeen.has(name))
+        return name;
+    // Collision: derive unique name from path by replacing separators with hyphens
+    const derived = relPath.replace(/\//g, "-");
+    if (SAFE_NAME_RE.test(derived))
+        return derived;
+    logger.warn("init", `Skipping "${relPath}": could not generate a unique valid name (collision with "${name}")`);
+    return null;
+}
+function buildSkills(found, agents) {
+    const namesSeen = new Set();
+    const skills = [];
+    for (const { relPath, name } of found) {
+        const skillName = resolveSkillName(relPath, name, namesSeen);
+        if (skillName === null)
+            continue;
+        namesSeen.add(skillName);
+        skills.push({ name: skillName, path: relPath, agents });
+    }
+    return skills;
+}
+async function manifestExists(manifestPath) {
+    try {
+        await access(manifestPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function runInit(options) {
+    const { directory, dryRun, force, verbose } = options;
+    const agents = options.agents ?? [...AGENT_IDS];
+    const manifestPath = path.join(directory, "inception.json");
+    if (!dryRun && (await manifestExists(manifestPath)) && !force) {
+        logger.error(`Error: ${manifestPath} already exists. Use --force to overwrite.`);
+        return 2;
+    }
+    const found = [];
+    await findSkillDirs(directory, directory, found);
+    if (found.length === 0) {
+        logger.info("No skill directories found (looking for directories containing SKILL.md).");
+        return 0;
+    }
+    const skills = buildSkills(found, agents);
+    if (skills.length === 0) {
+        logger.info("No skills could be added to the manifest.");
+        return 0;
+    }
+    const manifest = { skills, mcpServers: [], agentRules: [] };
+    const json = `${JSON.stringify(manifest, null, 2)}\n`;
+    if (dryRun) {
+        logger.info(`${dryRunPrefix(true)}Would write ${manifestPath} with ${skills.length} skill(s):`);
+        logger.info("");
+        logger.info(json);
+        return 0;
+    }
+    await writeFile(manifestPath, json, "utf-8");
+    logger.info(`Generated ${manifestPath} with ${skills.length} skill(s).`);
+    if (verbose) {
+        for (const s of skills) {
+            logger.detail(`${s.name}  →  ${s.path}`);
+        }
+    }
+    return 0;
+}

package/dist/core/ownership.d.ts

@@ -1,6 +1,10 @@
-import { type ConfigPatchRegistryEntry, type FileWriteRegistryEntry, type RegistryEntry, type SkillDirRegistryEntry } from "../schemas/registry.ts";
+import { type ConfigPatchRegistryEntry, type FileWriteRegistryEntry, type Registry, type RegistryEntry, type SkillDirRegistryEntry } from "../schemas/registry.ts";
 import type { AgentId } from "../types.ts";
 export type { RegistryEntry } from "../schemas/registry.ts";
+export interface RegistryPersistence {
+    load(home: string): Promise<Registry>;
+    save(home: string, registry: Registry): Promise<void>;
+}
 export type VerifyExpected = {
     kind: "skill-dir";
     source: string;
@@ -17,8 +21,9 @@ export type VerifyExpected = {
     agent: AgentId;
 };
 export declare function registryPath(home: string): string;
+export declare const defaultRegistryPersistence: RegistryPersistence;
 export type RegisterEntry = Omit<SkillDirRegistryEntry, "deployed"> | Omit<FileWriteRegistryEntry, "deployed"> | Omit<ConfigPatchRegistryEntry, "deployed">;
-export declare function registerDeployment(home: string, targetPath: string, entry: RegisterEntry): Promise<void>;
-export declare function unregisterDeployment(home: string, targetPath: string): Promise<void>;
-export declare function lookupDeployment(home: string, targetPath: string): Promise<RegistryEntry | null>;
-export declare function verifyDeployment(home: string, targetPath: string, expected: VerifyExpected): Promise<RegistryEntry | null>;
+export declare function registerDeployment(home: string, targetPath: string, entry: RegisterEntry, persistence?: RegistryPersistence): Promise<void>;
+export declare function unregisterDeployment(home: string, targetPath: string, persistence?: RegistryPersistence): Promise<void>;
+export declare function lookupDeployment(home: string, targetPath: string, persistence?: RegistryPersistence): Promise<RegistryEntry | null>;
+export declare function verifyDeployment(home: string, targetPath: string, expected: VerifyExpected, persistence?: RegistryPersistence): Promise<RegistryEntry | null>;

package/dist/core/ownership.js

@@ -24,6 +24,10 @@ async function saveRegistry(home, registry) {
     await writeFile(filePath, `${JSON.stringify(registry, null, 2)}\n`);
     await setFilePermissions(filePath);
 }
+export const defaultRegistryPersistence = {
+    load: loadRegistry,
+    save: saveRegistry,
+};
 /**
  * Ensure the file is not world-writable regardless of umask.
  * On Windows, the OS inherits ACLs from the parent directory — no-op is correct.
@@ -36,27 +40,27 @@ async function setFilePermissions(filePath) {
 function emptyRegistry() {
     return { version: 1, deployments: {} };
 }
-export async function registerDeployment(home, targetPath, entry) {
-    const registry = await loadRegistry(home);
+export async function registerDeployment(home, targetPath, entry, persistence = defaultRegistryPersistence) {
+    const registry = await persistence.load(home);
     registry.deployments[targetPath] = {
         ...entry,
         deployed: new Date().toISOString(),
     };
-    await saveRegistry(home, registry);
+    await persistence.save(home, registry);
 }
-export async function unregisterDeployment(home, targetPath) {
-    const registry = await loadRegistry(home);
+export async function unregisterDeployment(home, targetPath, persistence = defaultRegistryPersistence) {
+    const registry = await persistence.load(home);
     if (!(targetPath in registry.deployments))
         return;
     delete registry.deployments[targetPath];
-    await saveRegistry(home, registry);
+    await persistence.save(home, registry);
 }
-export async function lookupDeployment(home, targetPath) {
-    const registry = await loadRegistry(home);
+export async function lookupDeployment(home, targetPath, persistence = defaultRegistryPersistence) {
+    const registry = await persistence.load(home);
     return registry.deployments[targetPath] ?? null;
 }
-export async function verifyDeployment(home, targetPath, expected) {
-    const entry = await lookupDeployment(home, targetPath);
+export async function verifyDeployment(home, targetPath, expected, persistence = defaultRegistryPersistence) {
+    const entry = await lookupDeployment(home, targetPath, persistence);
     if (!entry)
         return null;
     if (entry.kind !== expected.kind)

package/dist/core/resolve.js

@@ -1,8 +1,8 @@
 import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import os from "node:os";
-import path from "node:path";
 import { UserError } from "../errors.js";
+import { getPathApi, resolveRuntimePaths } from "./runtime-paths.js";
 export function resolveHome() {
     if (process.platform === "win32") {
         return os.homedir();
@@ -97,13 +97,12 @@ export function resolveAgentDetectPath(agent, home) {
     return resolveAgentDetectPathFor(agent, home, getPlatformKey());
 }
 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");
+    const { appdata, xdgConfig } = resolveRuntimePaths(home);
     const resolved = segments.map((seg) => seg
         .replace("{home}", home)
         .replace("{name}", skillName)
         .replace("{appdata}", appdata)
         .replace("{xdg_config}", xdgConfig));
-    return path.join(...resolved);
+    const root = resolved.find((segment) => segment.length > 0) ?? home;
+    return getPathApi(root).join(...resolved);
 }

package/dist/core/revert.d.ts

@@ -1,7 +1,8 @@
 import type { AgentId, Manifest, PlannedChange, RevertAction } from "../types.ts";
+import { type RegistryPersistence } from "./ownership.ts";
 export declare function planRevert(manifest: Manifest, detectedAgents: AgentId[], home: string): RevertAction[];
 export declare function planRevertAll(manifest: Manifest, home: string): RevertAction[];
-export declare function executeRevert(actions: RevertAction[], dryRun: boolean, verbose: boolean, home: string): Promise<{
+export declare function executeRevert(actions: RevertAction[], dryRun: boolean, verbose: boolean, home: string, deps?: RevertDependencies): Promise<{
     succeeded: number;
     skipped: number;
     failed: Array<{
@@ -10,3 +11,7 @@ export declare function executeRevert(actions: RevertAction[], dryRun: boolean,
     }>;
     planned: PlannedChange[];
 }>;
+interface RevertDependencies {
+    registry?: RegistryPersistence;
+}
+export {};

package/dist/core/revert.js

@@ -1,19 +1,10 @@
 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 { compileAgentRuleReverts, compileMcpServerReverts, } from "./adapters/index.js";
+import { lookupDeployment, unregisterDeployment, } from "./ownership.js";
 import { resolveAgentSkillPath } from "./resolve.js";
-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);
-}
+import { resolveTargetTemplate } from "./runtime-paths.js";
 function buildSkillDirReverts(manifest, home, agentFilter) {
     const actions = [];
     for (const skill of manifest.skills) {
@@ -139,7 +130,7 @@ function lstatOutcome(err) {
     const msg = err instanceof Error ? err.message : String(err);
     return { outcome: "fail", error: msg };
 }
-export async function executeRevert(actions, dryRun, verbose, home) {
+export async function executeRevert(actions, dryRun, verbose, home, deps = {}) {
     let succeeded = 0;
     let skipped = 0;
     const failed = [];
@@ -149,13 +140,13 @@ export async function executeRevert(actions, dryRun, verbose, home) {
         let result;
         switch (action.kind) {
             case "skill-dir":
-                result = await executeRevertAction(action, dryRun, verbose, home, planned);
+                result = await executeRevertAction(action, dryRun, verbose, home, planned, deps);
                 break;
             case "file-write":
-                result = await revertFileWrite(action, dryRun, verbose, home, planned);
+                result = await revertFileWrite(action, dryRun, verbose, home, planned, deps);
                 break;
             case "config-patch":
-                result = await revertConfigPatch(action, dryRun, verbose, home, planned);
+                result = await revertConfigPatch(action, dryRun, verbose, home, planned, deps);
                 break;
             default:
                 throw new Error(`Unhandled revert action kind: ${action}`);
@@ -166,7 +157,7 @@ export async function executeRevert(actions, dryRun, verbose, home) {
     skipped = counts.skipped;
     return { succeeded, skipped, failed, planned };
 }
-async function executeRevertAction(action, dryRun, verbose, home, planned) {
+async function executeRevertAction(action, dryRun, verbose, home, planned, deps) {
     const label = `${action.skill} -> ${action.agent}`;
     try {
         await lstat(action.target);
@@ -180,7 +171,7 @@ async function executeRevertAction(action, dryRun, verbose, home, planned) {
         logger.fail(label, result.error);
         return result;
     }
-    const entry = await lookupDeployment(home, action.target);
+    const entry = await lookupDeployment(home, action.target, deps.registry);
     if (!entry || entry.skill !== action.skill || entry.agent !== action.agent) {
         logger.warn(label, `skipping: ${action.target} is not in the deployment registry — not managed by inception-engine`);
         return { outcome: "skip" };
@@ -205,7 +196,7 @@ async function executeRevertAction(action, dryRun, verbose, home, planned) {
         else {
             await rm(action.target, { recursive: true });
         }
-        await unregisterDeployment(home, action.target);
+        await unregisterDeployment(home, action.target, deps.registry);
         logger.ok(label);
         if (verbose) {
             logger.detail(`removed: ${action.target}`);
@@ -223,7 +214,7 @@ async function executeRevertAction(action, dryRun, verbose, home, planned) {
         return { outcome: "fail", error: msg };
     }
 }
-async function revertFileWrite(action, dryRun, verbose, home, planned) {
+async function revertFileWrite(action, dryRun, verbose, home, planned, deps) {
     const label = `${action.skill} -> ${action.agent}`;
     try {
         await lstat(action.target);
@@ -237,7 +228,7 @@ async function revertFileWrite(action, dryRun, verbose, home, planned) {
         logger.fail(label, result.error);
         return result;
     }
-    const entry = await lookupDeployment(home, action.target);
+    const entry = await lookupDeployment(home, action.target, deps.registry);
     if (!entry || entry.skill !== action.skill || entry.agent !== action.agent) {
         logger.warn(label, `skipping: ${action.target} is not in the deployment registry — not managed by inception-engine`);
         return { outcome: "skip" };
@@ -257,7 +248,7 @@ async function revertFileWrite(action, dryRun, verbose, home, planned) {
         // removal window; handle the case where the file has since disappeared.
         await lstat(action.target);
         await unlink(action.target);
-        await unregisterDeployment(home, action.target);
+        await unregisterDeployment(home, action.target, deps.registry);
         logger.ok(label);
         if (verbose) {
             logger.detail(`removed: ${action.target}`);
@@ -274,7 +265,7 @@ async function revertFileWrite(action, dryRun, verbose, home, planned) {
         return { outcome: "fail", error: msg };
     }
 }
-async function revertConfigPatch(action, dryRun, verbose, home, planned) {
+async function revertConfigPatch(action, dryRun, verbose, home, planned, deps) {
     const label = `${action.skill} -> ${action.agent}`;
     try {
         await lstat(action.target);
@@ -288,7 +279,7 @@ async function revertConfigPatch(action, dryRun, verbose, home, planned) {
         logger.fail(label, result.error);
         return result;
     }
-    const entry = await lookupDeployment(home, action.target);
+    const entry = await lookupDeployment(home, action.target, deps.registry);
     if (!entry ||
         entry.kind !== "config-patch" ||
         entry.skill !== action.skill ||
@@ -312,7 +303,7 @@ async function revertConfigPatch(action, dryRun, verbose, home, planned) {
         const current = await readJsonConfig(action.target);
         const restored = applyUndoPatch(current, configPatchEntry.undoPatch);
         await writeFile(action.target, `${JSON.stringify(restored, null, 2)}\n`, "utf-8");
-        await unregisterDeployment(home, action.target);
+        await unregisterDeployment(home, action.target, deps.registry);
         logger.ok(label);
         if (verbose) {
             logger.detail(`unapplied patch from: ${action.target}`);

package/dist/core/runtime-paths.d.ts

@@ -0,0 +1,8 @@
+import path from "node:path";
+export interface RuntimePaths {
+    appdata: string;
+    xdgConfig: string;
+}
+export declare function getPathApi(root: string): typeof path.posix | typeof path.win32;
+export declare function resolveRuntimePaths(home: string): RuntimePaths;
+export declare function resolveTargetTemplate(template: string, home: string): string;

package/dist/core/runtime-paths.js

@@ -0,0 +1,57 @@
+import path from "node:path";
+const TARGET_TEMPLATE_RE = /^\{(home|appdata|xdg_config)\}(?<suffix>(?:[\\/].*)?)$/;
+export function getPathApi(root) {
+    if (root.includes("\\") || /^[a-zA-Z]:/.test(root)) {
+        return path.win32;
+    }
+    if (root.startsWith("/")) {
+        return path.posix;
+    }
+    return process.platform === "win32" ? path.win32 : path.posix;
+}
+function normalizePathForComparison(candidate, pathApi) {
+    const normalized = pathApi.normalize(candidate);
+    return pathApi === path.win32 ? normalized.toLowerCase() : normalized;
+}
+function isSameOrDescendantPath(candidate, root) {
+    const pathApi = getPathApi(root);
+    const normalizedCandidate = normalizePathForComparison(candidate, pathApi);
+    const normalizedRoot = normalizePathForComparison(root, pathApi);
+    return (normalizedCandidate === normalizedRoot ||
+        normalizedCandidate.startsWith(normalizedRoot + pathApi.sep));
+}
+export function resolveRuntimePaths(home) {
+    const appdataRaw = process.env.APPDATA;
+    const homePathApi = getPathApi(home);
+    const appdata = appdataRaw && getPathApi(appdataRaw).isAbsolute(appdataRaw)
+        ? appdataRaw
+        : homePathApi.join(home, "AppData", "Roaming");
+    const xdgRaw = process.env.XDG_CONFIG_HOME;
+    const xdgConfig = xdgRaw && getPathApi(xdgRaw).isAbsolute(xdgRaw)
+        ? xdgRaw
+        : homePathApi.join(home, ".config");
+    return { appdata, xdgConfig };
+}
+export function resolveTargetTemplate(template, home) {
+    const { appdata, xdgConfig } = resolveRuntimePaths(home);
+    const match = TARGET_TEMPLATE_RE.exec(template);
+    if (!match) {
+        throw new Error(`Invalid target template: ${template}`);
+    }
+    const baseByRoot = {
+        home,
+        appdata,
+        xdg_config: xdgConfig,
+    };
+    const root = match[1];
+    const suffix = match.groups?.suffix ?? "";
+    const segments = suffix.split(/[\\/]+/).filter(Boolean);
+    const pathApi = getPathApi(baseByRoot[root]);
+    const resolved = segments.length === 0
+        ? baseByRoot[root]
+        : pathApi.join(baseByRoot[root], ...segments);
+    if (!isSameOrDescendantPath(resolved, baseByRoot[root])) {
+        throw new Error(`Target template resolves outside its placeholder root: ${template}`);
+    }
+    return suffix === "" ? baseByRoot[root] : `${baseByRoot[root]}${suffix}`;
+}

package/dist/core/validation.js

@@ -1,4 +1,4 @@
-import { lstat, realpath } from "node:fs/promises";
+import { lstat, realpath, stat } from "node:fs/promises";
 import path from "node:path";
 import { UserError } from "../errors.js";
 export function sourceAccessError(err, sourcePath) {
@@ -10,14 +10,39 @@ export function sourceAccessError(err, sourcePath) {
     const detail = err instanceof Error ? err.message : String(err);
     return `Failed to access source ${sourcePath}: ${detail}`;
 }
+function normalizePathForComparison(candidate) {
+    const normalized = path.normalize(candidate);
+    return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+function isSameOrDescendantPath(candidate, root) {
+    const normalizedCandidate = normalizePathForComparison(candidate);
+    const normalizedRoot = normalizePathForComparison(root);
+    return (normalizedCandidate === normalizedRoot ||
+        normalizedCandidate.startsWith(normalizedRoot + path.sep));
+}
+async function isSameFileSystemLocation(a, b) {
+    const [aStat, bStat] = await Promise.all([stat(a), stat(b)]);
+    return aStat.dev === bStat.dev && aStat.ino === bStat.ino;
+}
+async function isWithinRootByIdentity(candidate, root) {
+    let current = candidate;
+    while (true) {
+        if (await isSameFileSystemLocation(current, root))
+            return true;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return false;
+        current = parent;
+    }
+}
 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)) {
+        if (!(isSameOrDescendantPath(realSource, realRoot) ||
+            (await isWithinRootByIdentity(realSource, realRoot)))) {
             throw new UserError("DEPLOY_FAILED", `Skill path "${skillPath}" resolves outside the repository root via symlink: ${source} -> ${realSource}`);
         }
     }

package/dist/index.js

@@ -5,6 +5,7 @@ import { AGENT_REGISTRY } from "./config/agents.js";
 import { loadManifest } from "./config/manifest.js";
 import { executeDeploy, planDeploy } from "./core/deploy.js";
 import { detectInstalledAgents } from "./core/detect.js";
+import { runInit } from "./core/init.js";
 import { runPreflight } from "./core/preflight.js";
 import { resolveHome } from "./core/resolve.js";
 import { executeRevert, planRevert, planRevertAll } from "./core/revert.js";
@@ -17,10 +18,17 @@ inception-engine - Deploy AI agent skills
 Usage:
   inception-engine <directory> [options]
   inception-engine revert <directory> [options]
+  inception-engine init <directory> [options]
+
+Commands:
+  <directory>         Deploy skills from the manifest in the given directory
+  revert <directory>  Remove previously deployed skills
+  init <directory>    Scan a directory for skill folders and generate inception.json
 
 Options:
   --dry-run        Show what would be done without doing it
   --agents <list>  Comma-separated list of agent IDs to target
+  --force          (init only) Overwrite an existing inception.json
   --verbose        Show detailed output
   --debug          Show full error stack traces
   --help           Show this help message
@@ -38,6 +46,7 @@ function parseCLI(argv) {
             agents: null,
             verbose: false,
             debug: false,
+            force: false,
         };
     }
     let parsed;
@@ -50,6 +59,7 @@ function parseCLI(argv) {
                 verbose: { type: "boolean", default: false },
                 debug: { type: "boolean", default: false },
                 help: { type: "boolean", default: false },
+                force: { type: "boolean", default: false },
                 agents: { type: "string" },
             },
         });
@@ -66,6 +76,7 @@ function parseCLI(argv) {
             agents: null,
             verbose: false,
             debug: false,
+            force: false,
         };
     }
     let command = "deploy";
@@ -74,6 +85,10 @@ function parseCLI(argv) {
         command = "revert";
         pos = pos.slice(1);
     }
+    else if (pos[0] === "init") {
+        command = "init";
+        pos = pos.slice(1);
+    }
     if (pos.length > 1) {
         throw new UserError("INVALID_ARGS", `Unexpected argument: ${pos[1]}`);
     }
@@ -96,6 +111,7 @@ function parseCLI(argv) {
         agents,
         verbose: values.verbose,
         debug: values.debug,
+        force: values.force,
     };
 }
 async function main() {
@@ -104,6 +120,15 @@ async function main() {
         console.log(USAGE);
         return 0;
     }
+    if (options.command === "init") {
+        return runInit({
+            directory: options.directory,
+            agents: options.agents,
+            dryRun: options.dryRun,
+            force: options.force,
+            verbose: options.verbose,
+        });
+    }
     const manifest = await loadManifest(options.directory);
     const home = resolveHome();
     if (options.command === "deploy") {

package/dist/schemas/manifest.js

@@ -10,9 +10,10 @@ 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)\}/;
+// Target templates must be rooted at a known placeholder and may only add
+// descendant path segments beneath that root. e.g. "{home}/.claude/settings.json"
+// is valid, while "{home}/../.ssh/config" is rejected.
+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
@@ -53,6 +54,9 @@ const targetTemplateField = z
     .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}",
+})
+    .refine((t) => !t.split(/[\\/]+/).includes(".."), {
+    message: "target must not escape its placeholder root",
 });
 export const SkillEntrySchema = z.object({
     name: nameField,

package/dist/types.d.ts

@@ -85,10 +85,11 @@ export interface PlannedChange {
     confidence?: Confidence;
 }
 export interface CliOptions {
-    command: "deploy" | "revert" | "help";
+    command: "deploy" | "revert" | "init" | "help";
     directory: string;
     dryRun: boolean;
     agents: AgentId[] | null;
     verbose: boolean;
     debug: boolean;
+    force: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuznai/inception-engine",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Deploy AI agent skills from a git repo to user home directories",
   "license": "MIT",
   "author": "Damian Piątkowski",
@@ -38,11 +38,13 @@
     "typecheck": "tsc --noEmit",
     "fmt": "biome format --write .",
     "lint": "biome lint . --max-diagnostics none",
+    "lint:fix": "biome lint . --max-diagnostics none --write --unsafe",
     "predev": "node scripts/assert-direct-ts-node.mjs",
     "dev": "node src/index.ts",
     "pretest": "node scripts/assert-direct-ts-node.mjs",
-    "test": "node --test test/*.test.ts",
-    "prepublishOnly": "npm run typecheck && npm run lint && npm run build"
+    "test": "node --test --test-isolation=none test/**/*.test.ts",
+    "test:windows": "node --test --test-isolation=none test/unit/*.test.ts test/os/cross-platform/*.test.ts test/os/windows/*.test.ts",
+    "test:posix": "node --test --test-isolation=none test/unit/*.test.ts test/os/cross-platform/*.test.ts test/os/posix/*.test.ts"
   },
   "dependencies": {
     "zod": "^4.0.0"