@kuznai/inception-engine 0.4.1 → 0.6.0

package/README.md

@@ -2,6 +2,8 @@
 
 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. It does not yet manage persistent instruction files, MCP configuration, subagents, or agent-specific config patching.
+
 ## Quick Start
 
 ```bash
@@ -26,10 +28,12 @@ Managed skills overwrite their previous version. If a target exists but was not
 | Claude Code | `claude-code` | `~/.claude/skills/` | Yes | Yes | Yes |
 | OpenAI Codex | `codex` | `~/.codex/skills/` | Yes | Yes | Yes |
 | Gemini CLI | `gemini-cli` | `~/.gemini/skills/` | Yes | Yes | Yes |
-| Antigravity | `antigravity` | `~/.gemini/antigravity/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.
+
 \* OpenCode on Windows uses `%APPDATA%\opencode\skills\`.
 
 ### Feature Support
@@ -37,8 +41,8 @@ Managed skills overwrite their previous version. If a target exists but was not
 | Feature | Status |
 |---|---|
 | Skills (SKILL.md) | Supported |
-| MCP Servers | Planned |
-| Agent Rules | Planned |
+| MCP Servers | Accepted in manifest, not implemented |
+| Agent Rules | Accepted in manifest, not implemented |
 
 ## Manifest Format
 
@@ -60,10 +64,12 @@ Create an `inception.json` file at the root of your skills directory:
 
 Each skill entry has:
 
-- **name** - Unique skill identifier (lowercase, hyphens allowed)
+- **name** - Unique skill identifier using letters, digits, dots, underscores, or hyphens; it 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.
+
 ## Creating Skills
 
 Each skill is a directory containing at minimum a `SKILL.md` file with YAML frontmatter:
@@ -155,16 +161,16 @@ Revert targets all agents listed in the manifest by default (regardless of detec
 
 ### Ownership Tracking and Safe Revert
 
-inception-engine writes a structured `.inception-totem` marker file during every deploy so that `revert` and future deploys never touch content they did not create. The totem contains metadata (source path, skill name, agent ID, deploy timestamp) and is validated on both revert and redeploy.
-
-- **POSIX (symlink)**: `.inception-totem` is written inside the skill source directory. On revert, the tool resolves the symlink target and checks for a valid `.inception-totem` there. Only symlinks whose resolved target contains a valid totem are removed.
+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.
 
-- **Windows (copy)**: `.inception-totem` is written inside each deployed skill directory. On revert, this file must be present and valid for the directory to be removed.
+- **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.
 
-- **Deploy safety**: Before overwriting an existing target, the engine checks for a valid `.inception-totem`. If the target exists but is not managed by inception-engine, the deploy is skipped with an error — the unmanaged content is never removed.
+- **Strong binding**: Each registry entry binds a specific target path to its source, skill, agent, and deploy method. A target is only considered managed if all 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.
 
+- **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.
+
 ## Running with Privilege Escalation
 
 The tool works without elevated privileges. If run with `sudo` on POSIX systems, it looks up the real user's home directory from the OS directory services (`getent passwd` on Linux, `dscl` on macOS, `/etc/passwd` as a universal fallback) so skills are deployed to the correct location regardless of where home directories are stored — standard `/home/<user>`, LDAP/NIS paths, enterprise layouts, or otherwise.
@@ -179,7 +185,11 @@ On Windows, `os.homedir()` correctly resolves even in elevated PowerShell or cmd
 
 When run under `sudo` on POSIX, `SUDO_USER` is read as an advisory signal to identify the real user. The username is validated through OS directory services (`getent passwd` on Linux, `dscl` on macOS, `/etc/passwd` as a fallback) — it is never used as a raw path. This is standard practice for sudo-aware CLI tools.
 
-Automation edge case: if the tool runs inside a pipeline where `SUDO_USER` has been set externally in the environment before the process starts, the tool will look up that username's home directory. To avoid this in automation, either run without `sudo` or set `HOME` explicitly before invoking the tool.
+`SUDO_USER` is only consulted when the process is actually running as root (UID 0). If `SUDO_USER` is present in the environment but the process is not root — for example, as a stale shell variable from a prior `sudo` session or an externally injected value in automation — it is ignored and the standard home directory is used instead.
+
+### XDG_CONFIG_HOME support
+
+On POSIX, agents whose config lives under `~/.config/` (currently OpenCode) honor `$XDG_CONFIG_HOME` when it is set to an absolute path. If the variable is unset or contains a relative path (which the XDG Base Directory Specification disallows), the tool falls back to the standard `~/.config` default. This has no effect on Windows.
 
 ### Windows %APPDATA% fallback
 
@@ -187,7 +197,7 @@ On Windows, `%APPDATA%` is used to locate agent config directories (currently on
 
 ### Future: mixed asset layouts on Windows
 
-Windows deployment currently uses directory-level copy (one `cp -r` per skill). This works correctly for the present skill model where each skill is a single directory. If file-based assets or mixed (file + directory) skill layouts are added in the future, the copy strategy in `src/core/deploy.ts` will need revisiting — including `.inception-totem` placement and revert logic.
+Windows deployment currently uses directory-level copy (one `cp -r` per skill). This works correctly for the present skill model where each skill is a single directory. If file-based assets or mixed (file + directory) skill layouts are added in the future, the copy strategy in `src/core/deploy.ts` will need revisiting.
 
 ## Requirements
 

package/dist/config/agents.js

@@ -11,6 +11,11 @@ export const AGENT_REGISTRY = [
             windows: ["{home}", ".claude"],
         },
         detectBinary: "claude",
+        provenance: {
+            skills: "documented",
+            detectPaths: "documented",
+            detectBinary: "documented",
+        },
     },
     {
         id: "codex",
@@ -24,6 +29,11 @@ export const AGENT_REGISTRY = [
             windows: ["{home}", ".codex"],
         },
         detectBinary: "codex",
+        provenance: {
+            skills: "documented",
+            detectPaths: "documented",
+            detectBinary: "documented",
+        },
     },
     {
         id: "gemini-cli",
@@ -37,6 +47,11 @@ export const AGENT_REGISTRY = [
             windows: ["{home}", ".gemini"],
         },
         detectBinary: "gemini",
+        provenance: {
+            skills: "documented",
+            detectPaths: "documented",
+            detectBinary: "documented",
+        },
     },
     {
         id: "antigravity",
@@ -50,19 +65,29 @@ export const AGENT_REGISTRY = [
             windows: ["{home}", ".gemini", "antigravity"],
         },
         detectBinary: null,
+        provenance: {
+            skills: "implementation-only",
+            detectPaths: "implementation-only",
+            detectBinary: "provisional",
+        },
     },
     {
         id: "opencode",
         displayName: "OpenCode",
         skills: {
-            posix: ["{home}", ".config", "opencode", "skills", "{name}"],
+            posix: ["{xdg_config}", "opencode", "skills", "{name}"],
             windows: ["{appdata}", "opencode", "skills", "{name}"],
         },
         detectPaths: {
-            posix: ["{home}", ".config", "opencode"],
+            posix: ["{xdg_config}", "opencode"],
             windows: ["{appdata}", "opencode"],
         },
         detectBinary: "opencode",
+        provenance: {
+            skills: "documented",
+            detectPaths: "documented",
+            detectBinary: "documented",
+        },
     },
     {
         id: "github-copilot",
@@ -76,6 +101,11 @@ export const AGENT_REGISTRY = [
             windows: ["{home}", ".copilot"],
         },
         detectBinary: "github-copilot",
+        provenance: {
+            skills: "documented",
+            detectPaths: "documented",
+            detectBinary: "documented",
+        },
     },
 ];
 export const AGENT_REGISTRY_BY_ID = Object.fromEntries(AGENT_REGISTRY.map((a) => [a.id, a]));

package/dist/config/manifest.d.ts

@@ -1,2 +1,2 @@
-import type { Manifest } from "../types.ts";
+import type { Manifest } from "../schemas/manifest.ts";
 export declare function loadManifest(directory: string): Promise<Manifest>;

package/dist/config/manifest.js

@@ -1,15 +1,24 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { formatZodPath } from "../schemas/errors.js";
+import { ManifestSchema } from "../schemas/manifest.js";
 import { UserError } from "../errors.js";
-import { AGENT_IDS } from "../types.js";
 export async function loadManifest(directory) {
     const manifestPath = path.join(directory, "inception.json");
     let raw;
     try {
         raw = await readFile(manifestPath, "utf-8");
     }
-    catch {
-        throw new UserError("MANIFEST_INVALID", `No inception.json found in ${directory}. Are you pointing to the right repo?`);
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            throw new UserError("MANIFEST_INVALID", `No inception.json found in ${directory}. Are you pointing to the right repo?`);
+        }
+        if (code === "EACCES" || code === "EPERM") {
+            throw new UserError("MANIFEST_INVALID", `Permission denied reading ${manifestPath}. Check file permissions.`);
+        }
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new UserError("MANIFEST_INVALID", `Failed to read ${manifestPath}: ${detail}`);
     }
     let parsed;
     try {
@@ -21,52 +30,15 @@ export async function loadManifest(directory) {
     return validateManifest(parsed, manifestPath);
 }
 function validateManifest(data, filePath) {
-    if (typeof data !== "object" || data === null || Array.isArray(data)) {
-        throw new UserError("MANIFEST_INVALID", `${filePath}: manifest must be a JSON object`);
-    }
-    const obj = data;
-    if (!Array.isArray(obj.skills)) {
-        throw new UserError("MANIFEST_INVALID", `${filePath}: "skills" must be an array`);
-    }
-    const skills = obj.skills.map((entry, i) => validateSkillEntry(entry, i, filePath));
-    return {
-        skills,
-        mcpServers: Array.isArray(obj.mcpServers) ? obj.mcpServers : [],
-        agentRules: Array.isArray(obj.agentRules) ? obj.agentRules : [],
-    };
-}
-const SAFE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
-function validateSkillEntry(entry, i, filePath) {
-    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
-        throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}] must be an object`);
-    }
-    const skill = entry;
-    if (typeof skill.name !== "string" || skill.name.length === 0) {
-        throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].name must be a non-empty string`);
-    }
-    if (!SAFE_NAME_RE.test(skill.name)) {
-        throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].name must contain only letters, digits, hyphens, underscores, and dots, and must not start with a dot`);
-    }
-    if (typeof skill.path !== "string" || skill.path.length === 0) {
-        throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].path must be a non-empty string`);
-    }
-    if (path.isAbsolute(skill.path)) {
-        throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].path must be a relative path`);
-    }
-    if (path.normalize(skill.path).startsWith("..")) {
-        throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].path must not escape the repository root`);
-    }
-    if (!Array.isArray(skill.agents) || skill.agents.length === 0) {
-        throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].agents must be a non-empty array`);
-    }
-    for (const agent of skill.agents) {
-        if (!AGENT_IDS.includes(agent)) {
-            throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].agents contains unknown agent "${agent}". Valid agents: ${AGENT_IDS.join(", ")}`);
+    const result = ManifestSchema.safeParse(data);
+    if (!result.success) {
+        const issue = result.error.issues[0];
+        const issuePath = issue.path;
+        // Top-level "skills" key: missing or wrong type → uniform message
+        if (issuePath.length === 1 && issuePath[0] === "skills") {
+            throw new UserError("MANIFEST_INVALID", `${filePath}: "skills" must be an array`);
         }
+        throw new UserError("MANIFEST_INVALID", `${filePath}: ${formatZodPath(issuePath)}${issue.message}`);
     }
-    return {
-        name: skill.name,
-        path: skill.path,
-        agents: skill.agents,
-    };
+    return result.data;
 }

package/dist/core/deploy.d.ts

@@ -1,6 +1,6 @@
 import type { AgentId, DeployAction, Manifest } from "../types.ts";
 export declare function planDeploy(manifest: Manifest, sourceDir: string, detectedAgents: AgentId[], home: string): Promise<DeployAction[]>;
-export declare function executeDeploy(actions: DeployAction[], dryRun: boolean, verbose: boolean): Promise<{
+export declare function executeDeploy(actions: DeployAction[], dryRun: boolean, verbose: boolean, home: string): Promise<{
     succeeded: number;
     failed: Array<{
         action: DeployAction;

package/dist/core/deploy.js

@@ -3,8 +3,17 @@ 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 { isOwnedByInceptionEngine, writeTotem } from "./ownership.js";
+import { registerDeployment, verifyDeployment } from "./ownership.js";
 import { getDeployMethod, resolveAgentSkillPath } from "./resolve.js";
+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 planDeploy(manifest, sourceDir, detectedAgents, home) {
     const method = getDeployMethod();
     const actions = [];
@@ -37,7 +46,7 @@ export async function planDeploy(manifest, sourceDir, detectedAgents, home) {
     }
     return actions;
 }
-export async function executeDeploy(actions, dryRun, verbose) {
+export async function executeDeploy(actions, dryRun, verbose, home) {
     let succeeded = 0;
     const failed = [];
     for (const action of actions) {
@@ -45,8 +54,8 @@ export async function executeDeploy(actions, dryRun, verbose) {
         try {
             await access(action.source);
         }
-        catch {
-            const msg = `Source not found: ${action.source}`;
+        catch (err) {
+            const msg = sourceAccessError(err, action.source);
             failed.push({ action, error: msg });
             logger.fail(label, msg);
             continue;
@@ -60,7 +69,7 @@ export async function executeDeploy(actions, dryRun, verbose) {
             continue;
         }
         try {
-            await executeDeployAction(action, verbose);
+            await executeDeployAction(action, verbose, home);
             succeeded++;
         }
         catch (err) {
@@ -99,31 +108,31 @@ async function assertTargetAbsent(targetPath) {
         // ENOENT is expected — target should not exist after backup
     }
 }
-async function createDeployTarget(action) {
+async function createDeployTarget(action, home) {
     if (action.method === "symlink") {
         await symlink(action.source, action.target, "dir");
-        await writeTotem(action.source, {
-            source: action.source,
-            skill: action.skill,
-            agent: action.agent,
-        });
     }
     else {
         await cp(action.source, action.target, { recursive: true });
-        await writeTotem(action.target, {
-            source: action.source,
-            skill: action.skill,
-            agent: action.agent,
-        });
     }
+    await registerDeployment(home, action.target, {
+        source: action.source,
+        skill: action.skill,
+        agent: action.agent,
+        method: action.method,
+    });
 }
-async function executeDeployAction(action, verbose) {
+async function executeDeployAction(action, verbose, home) {
     const label = `${action.skill} -> ${action.agent}`;
-    const backupPath = await backupExisting(action.target, verbose);
+    const backupPath = await backupExisting(action.target, verbose, home, {
+        source: action.source,
+        skill: action.skill,
+        agent: action.agent,
+    });
     await mkdir(path.dirname(action.target), { recursive: true });
     try {
         await assertTargetAbsent(action.target);
-        await createDeployTarget(action);
+        await createDeployTarget(action, home);
     }
     catch (createErr) {
         if (backupPath) {
@@ -144,15 +153,14 @@ async function executeDeployAction(action, verbose) {
         logger.detail(`${action.method}: ${action.source} -> ${action.target}`);
     }
 }
-async function backupExisting(targetPath, verbose) {
-    let stat;
+async function backupExisting(targetPath, verbose, home, expected) {
     try {
-        stat = await lstat(targetPath);
+        await lstat(targetPath);
     }
     catch {
         return null;
     }
-    if (!(await isOwnedByInceptionEngine(targetPath, stat))) {
+    if (!(await verifyDeployment(home, targetPath, expected))) {
         throw new Error(`Target "${targetPath}" exists but is not managed by inception-engine — refusing to overwrite`);
     }
     const backupPath = `${targetPath}.inception-backup`;

package/dist/core/ownership.d.ts

@@ -1,10 +1,12 @@
-import type { Stats } from "node:fs";
+import { type RegistryEntry } from "../schemas/registry.ts";
 import type { AgentId } from "../types.ts";
-export interface TotemData {
+export type { RegistryEntry } from "../schemas/registry.ts";
+export declare function registryPath(home: string): string;
+export declare function registerDeployment(home: string, targetPath: string, entry: Omit<RegistryEntry, "deployed">): 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: {
     source: string;
     skill: string;
     agent: AgentId;
-}
-export declare function formatTotem(data: TotemData): string;
-export declare function writeTotem(directory: string, data: TotemData): Promise<void>;
-export declare function isOwnedByInceptionEngine(targetPath: string, stat: Stats): Promise<boolean>;
+}): Promise<RegistryEntry | null>;

package/dist/core/ownership.js

@@ -1,44 +1,68 @@
-import { access, chmod, readFile, readlink, writeFile } from "node:fs/promises";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
-const TOTEM_FILE = ".inception-totem";
-const TOTEM_HEADER = "inception-engine";
-export function formatTotem(data) {
-    const lines = [
-        TOTEM_HEADER,
-        `source=${data.source}`,
-        `skill=${data.skill}`,
-        `agent=${data.agent}`,
-        `deployed=${new Date().toISOString()}`,
-    ];
-    return `${lines.join("\n")}\n`;
-}
-export async function writeTotem(directory, data) {
-    const totemPath = path.join(directory, TOTEM_FILE);
-    await writeFile(totemPath, formatTotem(data));
-    await chmod(totemPath, 0o644);
-}
-export async function isOwnedByInceptionEngine(targetPath, stat) {
-    const totemLocation = stat.isSymbolicLink()
-        ? await resolveSymlinkTotemPath(targetPath)
-        : path.join(targetPath, TOTEM_FILE);
-    if (!totemLocation)
-        return false;
+import { RegistrySchema, } from "../schemas/registry.js";
+const REGISTRY_DIR = ".inception-engine";
+const REGISTRY_FILE = "registry.json";
+export function registryPath(home) {
+    return path.join(home, REGISTRY_DIR, REGISTRY_FILE);
+}
+async function loadRegistry(home) {
     try {
-        const content = await readFile(totemLocation, "utf-8");
-        return content.startsWith(TOTEM_HEADER);
+        const content = await readFile(registryPath(home), "utf-8");
+        const parsed = JSON.parse(content);
+        const result = RegistrySchema.safeParse(parsed);
+        return result.success ? result.data : emptyRegistry();
     }
     catch {
-        return false;
+        return emptyRegistry();
     }
 }
-async function resolveSymlinkTotemPath(targetPath) {
-    try {
-        const linkTarget = await readlink(targetPath);
-        const resolved = path.resolve(path.dirname(targetPath), linkTarget);
-        await access(resolved);
-        return path.join(resolved, TOTEM_FILE);
+async function saveRegistry(home, registry) {
+    const dir = path.join(home, REGISTRY_DIR);
+    await mkdir(dir, { recursive: true });
+    const filePath = registryPath(home);
+    await writeFile(filePath, `${JSON.stringify(registry, null, 2)}\n`);
+    await setFilePermissions(filePath);
+}
+/**
+ * Ensure the file is not world-writable regardless of umask.
+ * On Windows, the OS inherits ACLs from the parent directory — no-op is correct.
+ */
+async function setFilePermissions(filePath) {
+    if (process.platform !== "win32") {
+        await chmod(filePath, 0o644);
     }
-    catch {
+}
+function emptyRegistry() {
+    return { version: 1, deployments: {} };
+}
+export async function registerDeployment(home, targetPath, entry) {
+    const registry = await loadRegistry(home);
+    registry.deployments[targetPath] = {
+        ...entry,
+        deployed: new Date().toISOString(),
+    };
+    await saveRegistry(home, registry);
+}
+export async function unregisterDeployment(home, targetPath) {
+    const registry = await loadRegistry(home);
+    if (!(targetPath in registry.deployments))
+        return;
+    delete registry.deployments[targetPath];
+    await saveRegistry(home, registry);
+}
+export async function lookupDeployment(home, targetPath) {
+    const registry = await loadRegistry(home);
+    return registry.deployments[targetPath] ?? null;
+}
+export async function verifyDeployment(home, targetPath, expected) {
+    const entry = await lookupDeployment(home, targetPath);
+    if (!entry)
+        return null;
+    if (entry.source !== expected.source ||
+        entry.skill !== expected.skill ||
+        entry.agent !== expected.agent) {
         return null;
     }
+    return entry;
 }

package/dist/core/preflight.d.ts

@@ -0,0 +1,6 @@
+import type { CliOptions, Manifest } from "../types.ts";
+export interface PreflightWarning {
+    kind: "policy" | "config-authority" | "info";
+    message: string;
+}
+export declare function runPreflight(_options: CliOptions, _manifest: Manifest, _home: string): Promise<PreflightWarning[]>;

package/dist/core/preflight.js

@@ -0,0 +1,6 @@
+export async function runPreflight(_options, _manifest, _home) {
+    // Extension point for future enterprise policy checks.
+    // Future additions: check for local-config overrides, policy files,
+    // agent version constraints, etc.
+    return [];
+}

package/dist/core/resolve.js

@@ -8,7 +8,7 @@ export function resolveHome() {
         return os.homedir();
     }
     const sudoUser = process.env.SUDO_USER;
-    if (sudoUser) {
+    if (sudoUser && process.getuid?.() === 0) {
         return lookupHomeForUser(sudoUser);
     }
     return os.homedir();
@@ -98,9 +98,12 @@ export function resolveAgentDetectPath(agent, home) {
 }
 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 resolved = segments.map((seg) => seg
         .replace("{home}", home)
         .replace("{name}", skillName)
-        .replace("{appdata}", appdata));
+        .replace("{appdata}", appdata)
+        .replace("{xdg_config}", xdgConfig));
     return path.join(...resolved);
 }

package/dist/core/revert.d.ts

@@ -1,7 +1,11 @@
 import type { AgentId, Manifest, RevertAction } from "../types.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): Promise<{
+export declare function executeRevert(actions: RevertAction[], dryRun: boolean, verbose: boolean, home: string): Promise<{
     succeeded: number;
     skipped: number;
+    failed: Array<{
+        action: RevertAction;
+        error: string;
+    }>;
 }>;

package/dist/core/revert.js

@@ -1,7 +1,7 @@
 import { lstat, rm, unlink } from "node:fs/promises";
 import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
 import { logger } from "../logger.js";
-import { isOwnedByInceptionEngine } from "./ownership.js";
+import { lookupDeployment, unregisterDeployment } from "./ownership.js";
 import { resolveAgentSkillPath } from "./resolve.js";
 export function planRevert(manifest, detectedAgents, home) {
     const actions = [];
@@ -31,40 +31,57 @@ export function planRevertAll(manifest, home) {
     }
     return actions;
 }
-export async function executeRevert(actions, dryRun, verbose) {
+function lstatOutcome(err) {
+    if (err.code === "ENOENT") {
+        return { outcome: "skip" };
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    return { outcome: "fail", error: msg };
+}
+export async function executeRevert(actions, dryRun, verbose, home) {
     let succeeded = 0;
     let skipped = 0;
+    const failed = [];
     for (const action of actions) {
-        const result = await executeRevertAction(action, dryRun, verbose);
-        if (result === "skip") {
+        const result = await executeRevertAction(action, dryRun, verbose, home);
+        if (result.outcome === "fail") {
+            failed.push({ action, error: result.error });
+        }
+        else if (result.outcome === "skip") {
             skipped++;
         }
         else {
             succeeded++;
         }
     }
-    return { succeeded, skipped };
+    return { succeeded, skipped, failed };
 }
-async function executeRevertAction(action, dryRun, verbose) {
+async function executeRevertAction(action, dryRun, verbose, home) {
     const label = `${action.skill} -> ${action.agent}`;
     let stat;
     try {
         stat = await lstat(action.target);
     }
-    catch {
-        logger.skip(label, "(not found, skipping)");
-        return "skip";
+    catch (err) {
+        const result = lstatOutcome(err);
+        if (result.outcome === "skip") {
+            logger.skip(label, "(not found, skipping)");
+            return result;
+        }
+        logger.fail(label, result.error);
+        return result;
     }
-    if (!(await isOwnedByInceptionEngine(action.target, stat))) {
-        logger.warn(label, `skipping: ${action.target} does not have inception-engine ownership proof — not managed by inception-engine`);
-        return "skip";
+    const entry = await lookupDeployment(home, action.target);
+    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" };
     }
     if (dryRun) {
         logger.plan(label);
         if (verbose) {
             logger.detail(`would remove: ${action.target}`);
         }
-        return "ok";
+        return { outcome: "ok" };
     }
     try {
         if (stat.isSymbolicLink()) {
@@ -73,15 +90,16 @@ async function executeRevertAction(action, dryRun, verbose) {
         else {
             await rm(action.target, { recursive: true });
         }
+        await unregisterDeployment(home, action.target);
         logger.ok(label);
         if (verbose) {
             logger.detail(`removed: ${action.target}`);
         }
-        return "ok";
+        return { outcome: "ok" };
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         logger.fail(label, msg);
-        return "skip";
+        return { outcome: "fail", error: msg };
     }
 }

package/dist/index.js

@@ -6,10 +6,11 @@ import { loadManifest } from "./config/manifest.js";
 import { executeDeploy, planDeploy } from "./core/deploy.js";
 import { detectInstalledAgents } from "./core/detect.js";
 import { resolveHome } from "./core/resolve.js";
+import { runPreflight } from "./core/preflight.js";
 import { executeRevert, planRevert, planRevertAll } from "./core/revert.js";
 import { UserError } from "./errors.js";
 import { dryRunPrefix, logger } from "./logger.js";
-import { AGENT_IDS } from "./types.js";
+import { AgentListSchema } from "./schemas/manifest.js";
 const USAGE = `
 inception-engine - Deploy AI agent skills
 
@@ -82,13 +83,11 @@ function parseCLI(argv) {
     }
     let agents = null;
     if (typeof values.agents === "string") {
-        const ids = values.agents.split(",").map((s) => s.trim());
-        for (const id of ids) {
-            if (!AGENT_IDS.includes(id)) {
-                throw new UserError("INVALID_ARGS", `Unknown agent: "${id}". Valid agents: ${AGENT_IDS.join(", ")}`);
-            }
+        const r = AgentListSchema.safeParse(values.agents);
+        if (!r.success) {
+            throw new UserError("INVALID_ARGS", r.error.issues[0].message);
         }
-        agents = ids;
+        agents = r.data;
     }
     return {
         command,
@@ -107,6 +106,10 @@ async function main() {
     }
     const manifest = await loadManifest(options.directory);
     const home = resolveHome();
+    const preflightWarnings = await runPreflight(options, manifest, home);
+    for (const w of preflightWarnings) {
+        logger.warn("preflight", w.message);
+    }
     if (options.command === "deploy") {
         return runDeploy(options, manifest, home);
     }
@@ -137,7 +140,7 @@ async function runDeploy(options, manifest, home) {
         return 0;
     }
     logger.info(`${dryRunPrefix(options.dryRun)}Deploying ${actions.length} skill(s):`);
-    const { succeeded, failed } = await executeDeploy(actions, options.dryRun, options.verbose);
+    const { succeeded, failed } = await executeDeploy(actions, options.dryRun, options.verbose, home);
     logger.info("");
     if (failed.length > 0) {
         logger.info(`${succeeded} succeeded, ${failed.length} failed`);
@@ -155,8 +158,16 @@ async function runRevert(options, manifest, home) {
         return 0;
     }
     logger.info(`${dryRunPrefix(options.dryRun)}Reverting ${actions.length} skill(s):`);
-    const { succeeded, skipped } = await executeRevert(actions, options.dryRun, options.verbose);
+    const { succeeded, skipped, failed } = await executeRevert(actions, options.dryRun, options.verbose, home);
     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)" : ""}`);
+        return 1;
+    }
     const parts = [`${succeeded} removed`];
     if (skipped > 0)
         parts.push(`${skipped} skipped`);

package/dist/schemas/errors.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Shared helpers for mapping Zod parse errors to user-facing messages.
+ */
+export declare function formatZodPath(path: (string | number)[]): string;

package/dist/schemas/errors.js

@@ -0,0 +1,14 @@
+/**
+ * Shared helpers for mapping Zod parse errors to user-facing messages.
+ */
+export function formatZodPath(path) {
+    if (path.length === 0)
+        return "";
+    return `${path
+        .map((seg, i) => {
+        if (typeof seg === "number")
+            return `[${seg}]`;
+        return i === 0 ? seg : `.${seg}`;
+    })
+        .join("")} `;
+}

package/dist/schemas/manifest.d.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+declare const AGENT_IDS: readonly ["claude-code", "codex", "gemini-cli", "antigravity", "opencode", "github-copilot"];
+export { AGENT_IDS };
+export declare const AgentIdSchema: z.ZodEnum<{
+    "claude-code": "claude-code";
+    codex: "codex";
+    "gemini-cli": "gemini-cli";
+    antigravity: "antigravity";
+    opencode: "opencode";
+    "github-copilot": "github-copilot";
+}>;
+export type AgentId = z.output<typeof AgentIdSchema>;
+export declare const SkillEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    path: z.ZodString;
+    agents: 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.core.$strip>;
+export declare const ManifestSchema: z.ZodObject<{
+    skills: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        path: z.ZodString;
+        agents: 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.core.$strip>>;
+    mcpServers: z.ZodCatch<z.ZodArray<z.ZodUnknown>>;
+    agentRules: z.ZodCatch<z.ZodArray<z.ZodUnknown>>;
+}, z.core.$strip>;
+export type SkillEntry = z.infer<typeof SkillEntrySchema>;
+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";
+    codex: "codex";
+    "gemini-cli": "gemini-cli";
+    antigravity: "antigravity";
+    opencode: "opencode";
+    "github-copilot": "github-copilot";
+}>>>>;

package/dist/schemas/manifest.js

@@ -0,0 +1,58 @@
+import nodePath from "node:path";
+import { z } from "zod";
+const AGENT_IDS = [
+    "claude-code",
+    "codex",
+    "gemini-cli",
+    "antigravity",
+    "opencode",
+    "github-copilot",
+];
+export { AGENT_IDS };
+const SAFE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+// 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
+// value in the message (Zod 4's invalid_value issue omits the received value).
+// The .pipe(AgentIdSchema) at the end provides the AgentId output type.
+const agentIdElement = z
+    .string()
+    .superRefine((v, ctx) => {
+    if (!AGENT_IDS.includes(v)) {
+        ctx.addIssue({
+            code: "custom",
+            message: `unknown agent "${v}". Valid agents: ${AGENT_IDS.join(", ")}`,
+        });
+    }
+})
+    .pipe(AgentIdSchema);
+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" }),
+});
+export const ManifestSchema = z.object({
+    skills: z.array(SkillEntrySchema),
+    mcpServers: z.array(z.unknown()).catch([]),
+    agentRules: z.array(z.unknown()).catch([]),
+});
+// Parses the --agents CLI flag: comma-separated agent IDs → AgentId[]
+export const AgentListSchema = z
+    .string()
+    .transform((s) => s.split(",").map((id) => id.trim()))
+    .pipe(z.array(agentIdElement).min(1, { message: "agent list must not be empty" }));

package/dist/schemas/registry.d.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+export declare const RegistryEntrySchema: z.ZodObject<{
+    source: z.ZodString;
+    skill: z.ZodString;
+    agent: z.ZodEnum<{
+        "claude-code": "claude-code";
+        codex: "codex";
+        "gemini-cli": "gemini-cli";
+        antigravity: "antigravity";
+        opencode: "opencode";
+        "github-copilot": "github-copilot";
+    }>;
+    method: z.ZodEnum<{
+        symlink: "symlink";
+        copy: "copy";
+    }>;
+    deployed: z.ZodString;
+}, z.core.$strip>;
+export declare const RegistrySchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    deployments: z.ZodRecord<z.ZodString, z.ZodObject<{
+        source: z.ZodString;
+        skill: z.ZodString;
+        agent: z.ZodEnum<{
+            "claude-code": "claude-code";
+            codex: "codex";
+            "gemini-cli": "gemini-cli";
+            antigravity: "antigravity";
+            opencode: "opencode";
+            "github-copilot": "github-copilot";
+        }>;
+        method: z.ZodEnum<{
+            symlink: "symlink";
+            copy: "copy";
+        }>;
+        deployed: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type RegistryEntry = z.infer<typeof RegistryEntrySchema>;
+export type Registry = z.infer<typeof RegistrySchema>;

package/dist/schemas/registry.js

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { AgentIdSchema } from "./manifest.js";
+export const RegistryEntrySchema = z.object({
+    source: z.string(),
+    skill: z.string(),
+    agent: AgentIdSchema,
+    method: z.enum(["symlink", "copy"]),
+    deployed: z.string(),
+});
+export const RegistrySchema = z.object({
+    version: z.literal(1),
+    deployments: z.record(z.string(), RegistryEntrySchema),
+});

package/dist/types.d.ts

@@ -1,25 +1,22 @@
-export type AgentId = "claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot";
-export declare const AGENT_IDS: readonly AgentId[];
-export interface SkillEntry {
-    name: string;
-    path: string;
-    agents: AgentId[];
-}
-export interface Manifest {
-    skills: SkillEntry[];
-    mcpServers: unknown[];
-    agentRules: unknown[];
-}
+import type { AgentId } from "./schemas/manifest.ts";
+export type { AgentId, Manifest, SkillEntry } from "./schemas/manifest.ts";
 export interface AgentPaths {
     posix: string[];
     windows: string[];
 }
+export type Confidence = "documented" | "implementation-only" | "provisional";
+export interface AgentProvenance {
+    skills: Confidence;
+    detectPaths: Confidence;
+    detectBinary: Confidence;
+}
 export interface AgentConfig {
     id: AgentId;
     displayName: string;
     skills: AgentPaths;
     detectPaths: AgentPaths;
     detectBinary: string | null;
+    provenance: AgentProvenance;
 }
 export interface DeployAction {
     skill: string;

package/dist/types.js

@@ -1,8 +1 @@
-export const AGENT_IDS = [
-    "claude-code",
-    "codex",
-    "gemini-cli",
-    "antigravity",
-    "opencode",
-    "github-copilot",
-];
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuznai/inception-engine",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Deploy AI agent skills from a git repo to user home directories",
   "license": "MIT",
   "author": "Damian Piątkowski",
@@ -36,12 +36,15 @@
   "scripts": {
     "build": "tsc",
     "typecheck": "tsc --noEmit",
-    "format": "biome format --write .",
+    "fmt": "biome format --write .",
     "lint": "biome lint . --max-diagnostics none",
     "dev": "node src/index.ts",
     "test": "node --test test/*.test.ts",
     "prepublishOnly": "npm run typecheck && npm run lint && npm run build"
   },
+  "dependencies": {
+    "zod": "^4.0.0"
+  },
   "devDependencies": {
     "@biomejs/biome": "^2.4.8",
     "@types/node": "^25.5.0",