@kuznai/inception-engine 0.4.0 → 0.5.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,17 +161,15 @@ 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.
+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.
 
-- **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.
+- **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.
 
-- **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.
-
-- **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.
 
-> **Note:** Skills deployed before `.inception-totem` was introduced must be re-deployed before `revert` can remove them.
+- **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
 
@@ -181,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
 
@@ -189,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.js

@@ -1,7 +1,7 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { AGENT_IDS } from "../types.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;
@@ -28,44 +28,45 @@ function validateManifest(data, filePath) {
     if (!Array.isArray(obj.skills)) {
         throw new UserError("MANIFEST_INVALID", `${filePath}: "skills" must be an array`);
     }
-    const skills = obj.skills.map((entry, i) => {
-        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`);
-        }
-        const SAFE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
-        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(", ")}`);
-            }
-        }
-        return {
-            name: skill.name,
-            path: skill.path,
-            agents: skill.agents,
-        };
-    });
+    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(", ")}`);
+        }
+    }
+    return {
+        name: skill.name,
+        path: skill.path,
+        agents: skill.agents,
+    };
+}

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

@@ -1,10 +1,10 @@
-import { access, lstat, mkdir, symlink, cp, unlink, rm, rename, realpath } from "node:fs/promises";
+import { access, cp, lstat, mkdir, realpath, rename, rm, symlink, unlink, } from "node:fs/promises";
 import path from "node:path";
 import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
-import { resolveAgentSkillPath, getDeployMethod } from "./resolve.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";
 export async function planDeploy(manifest, sourceDir, detectedAgents, home) {
     const method = getDeployMethod();
     const actions = [];
@@ -18,20 +18,7 @@ export async function planDeploy(manifest, sourceDir, detectedAgents, home) {
     }
     for (const skill of manifest.skills) {
         const source = path.resolve(sourceDir, skill.path);
-        if (!source.startsWith(resolvedSourceDir + path.sep)) {
-            throw new UserError("DEPLOY_FAILED", `Skill path "${skill.path}" resolves outside the repository root: ${source}`);
-        }
-        try {
-            const realSource = await realpath(source);
-            if (realSource !== realRoot && !realSource.startsWith(realRoot + path.sep)) {
-                throw new UserError("DEPLOY_FAILED", `Skill path "${skill.path}" resolves outside the repository root via symlink: ${source} -> ${realSource}`);
-            }
-        }
-        catch (err) {
-            if (err instanceof UserError)
-                throw err;
-            // Source doesn't exist yet — will be caught during execute
-        }
+        await validateSourcePath(source, skill.path, resolvedSourceDir, realRoot);
         for (const agentId of skill.agents) {
             if (!detectedAgents.includes(agentId))
                 continue;
@@ -39,12 +26,18 @@ export async function planDeploy(manifest, sourceDir, detectedAgents, home) {
             if (!agent)
                 continue;
             const target = resolveAgentSkillPath(agent, skill.name, home);
-            actions.push({ skill: skill.name, agent: agentId, source, target, method });
+            actions.push({
+                skill: skill.name,
+                agent: agentId,
+                source,
+                target,
+                method,
+            });
         }
     }
     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) {
@@ -67,48 +60,7 @@ export async function executeDeploy(actions, dryRun, verbose) {
             continue;
         }
         try {
-            const backupPath = await backupExisting(action.target, verbose);
-            await mkdir(path.dirname(action.target), { recursive: true });
-            try {
-                // Final TOCTOU check: ensure nothing appeared at the target after backup
-                try {
-                    await lstat(action.target);
-                    throw new Error(`Target path appeared unexpectedly after backup: ${action.target}`);
-                }
-                catch (err) {
-                    if (err instanceof Error && err.message.startsWith("Target path appeared"))
-                        throw err;
-                    // ENOENT is expected — target should not exist after backup
-                }
-                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 });
-                }
-            }
-            catch (createErr) {
-                // Rollback: restore backup if creation failed
-                if (backupPath) {
-                    try {
-                        await rename(backupPath, action.target);
-                    }
-                    catch {
-                        // Best-effort rollback
-                    }
-                }
-                throw createErr;
-            }
-            // Success: remove backup
-            if (backupPath) {
-                await removeTarget(backupPath);
-            }
-            logger.ok(label);
-            if (verbose) {
-                logger.detail(`${action.method}: ${action.source} -> ${action.target}`);
-            }
+            await executeDeployAction(action, verbose, home);
             succeeded++;
         }
         catch (err) {
@@ -119,18 +71,90 @@ export async function executeDeploy(actions, dryRun, verbose) {
     }
     return { succeeded, failed };
 }
-async function backupExisting(targetPath, verbose) {
-    let stat;
+async function validateSourcePath(source, skillPath, resolvedSourceDir, realRoot) {
+    if (!source.startsWith(resolvedSourceDir + path.sep)) {
+        throw new UserError("DEPLOY_FAILED", `Skill path "${skillPath}" resolves outside the repository root: ${source}`);
+    }
+    try {
+        const realSource = await realpath(source);
+        if (realSource !== realRoot &&
+            !realSource.startsWith(realRoot + path.sep)) {
+            throw new UserError("DEPLOY_FAILED", `Skill path "${skillPath}" resolves outside the repository root via symlink: ${source} -> ${realSource}`);
+        }
+    }
+    catch (err) {
+        if (err instanceof UserError)
+            throw err;
+        // Source doesn't exist yet — will be caught during execute
+    }
+}
+async function assertTargetAbsent(targetPath) {
+    try {
+        await lstat(targetPath);
+        throw new Error(`Target path appeared unexpectedly after backup: ${targetPath}`);
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.startsWith("Target path appeared"))
+            throw err;
+        // 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 });
+    }
+    await registerDeployment(home, action.target, {
+        source: action.source,
+        skill: action.skill,
+        agent: action.agent,
+        method: action.method,
+    });
+}
+async function executeDeployAction(action, verbose, home) {
+    const label = `${action.skill} -> ${action.agent}`;
+    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, home);
+    }
+    catch (createErr) {
+        if (backupPath) {
+            try {
+                await rename(backupPath, action.target);
+            }
+            catch {
+                // Best-effort rollback
+            }
+        }
+        throw createErr;
+    }
+    if (backupPath) {
+        await removeTarget(backupPath);
+    }
+    logger.ok(label);
+    if (verbose) {
+        logger.detail(`${action.method}: ${action.source} -> ${action.target}`);
+    }
+}
+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";
+    const backupPath = `${targetPath}.inception-backup`;
     // Clean up any stale backup from a previous failed attempt
     try {
         await lstat(backupPath);

package/dist/core/detect.js

@@ -1,5 +1,5 @@
-import { access } from "node:fs/promises";
 import { execFile } from "node:child_process";
+import { access } from "node:fs/promises";
 import { promisify } from "node:util";
 import { AGENT_REGISTRY } from "../config/agents.js";
 import { resolveAgentDetectPath } from "./resolve.js";
@@ -19,7 +19,9 @@ async function isAgentInstalled(agent, home) {
         await access(detectPath);
         return true;
     }
-    catch { }
+    catch {
+        // path does not exist — fall through to binary detection
+    }
     if (agent.detectBinary) {
         return isBinaryInPath(agent.detectBinary);
     }

package/dist/core/ownership.d.ts

@@ -1,10 +1,17 @@
-import type { Stats } from "node:fs";
 import type { AgentId } from "../types.ts";
-export interface TotemData {
+export interface RegistryEntry {
     source: string;
     skill: string;
     agent: AgentId;
+    method: "symlink" | "copy";
+    deployed: string;
 }
-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>;
+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;
+}): Promise<RegistryEntry | null>;

package/dist/core/ownership.js

@@ -1,44 +1,73 @@
-import { access, readlink, readFile, writeFile, chmod } 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;
+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);
+        if (parsed &&
+            typeof parsed === "object" &&
+            parsed.version === 1 &&
+            parsed.deployments &&
+            typeof parsed.deployments === "object") {
+            return parsed;
+        }
+        return 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/resolve.js

@@ -7,41 +7,58 @@ export function resolveHome() {
     if (process.platform === "win32") {
         return os.homedir();
     }
-    const sudoUser = process.env["SUDO_USER"];
-    if (sudoUser) {
+    const sudoUser = process.env.SUDO_USER;
+    if (sudoUser && process.getuid?.() === 0) {
         return lookupHomeForUser(sudoUser);
     }
     return os.homedir();
 }
 export function lookupHomeForUserWith(username, platform, execFileFn, readFileFn) {
-    // Method 1: getent passwd (Linux/POSIX — handles LDAP, NIS, local via NSS)
     if (platform !== "darwin") {
-        try {
-            const out = execFileFn("getent", ["passwd", username], {
-                encoding: "utf8",
-                stdio: ["ignore", "pipe", "ignore"],
-            }).trim();
-            const home = out.split(":")[5];
-            if (typeof home === "string" && home.startsWith("/"))
-                return home;
-        }
-        catch {
-            // getent unavailable or user not found — try next method
-        }
+        const home = lookupViaGetent(username, execFileFn);
+        if (home)
+            return home;
     }
-    // Method 2: dscl (macOS directory services)
     if (platform === "darwin") {
-        try {
-            const out = execFileFn("dscl", [".", "-read", `/Users/${username}`, "NFSHomeDirectory"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
-            const home = out.replace(/^NFSHomeDirectory:\s*/, "").trim();
-            if (home.startsWith("/"))
-                return home;
-        }
-        catch {
-            // dscl unavailable or user record not found — try next method
-        }
+        const home = lookupViaDscl(username, execFileFn);
+        if (home)
+            return home;
     }
-    // Method 3: parse /etc/passwd directly (universal POSIX fallback)
+    const home = lookupViaEtcPasswd(username, readFileFn);
+    if (home)
+        return home;
+    throw new UserError("RESOLVE_FAILED", `Cannot determine home directory for user "${username}". ` +
+        `Tried getent, dscl, and /etc/passwd. ` +
+        `Run without sudo, or set HOME to the correct path before invoking with sudo.`);
+}
+function lookupViaGetent(username, execFileFn) {
+    try {
+        const out = execFileFn("getent", ["passwd", username], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        const home = out.split(":")[5];
+        if (typeof home === "string" && home.startsWith("/"))
+            return home;
+    }
+    catch {
+        // getent unavailable or user not found
+    }
+    return null;
+}
+function lookupViaDscl(username, execFileFn) {
+    try {
+        const out = execFileFn("dscl", [".", "-read", `/Users/${username}`, "NFSHomeDirectory"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        const home = out.replace(/^NFSHomeDirectory:\s*/, "").trim();
+        if (home.startsWith("/"))
+            return home;
+    }
+    catch {
+        // dscl unavailable or user record not found
+    }
+    return null;
+}
+function lookupViaEtcPasswd(username, readFileFn) {
     try {
         const passwd = readFileFn("/etc/passwd", "utf8");
         for (const line of passwd.split("\n")) {
@@ -54,11 +71,9 @@ export function lookupHomeForUserWith(username, platform, execFileFn, readFileFn
         }
     }
     catch {
-        // /etc/passwd unavailable — fall through to error
+        // /etc/passwd unavailable
     }
-    throw new UserError("RESOLVE_FAILED", `Cannot determine home directory for user "${username}". ` +
-        `Tried getent, dscl, and /etc/passwd. ` +
-        `Run without sudo, or set HOME to the correct path before invoking with sudo.`);
+    return null;
 }
 function lookupHomeForUser(username) {
     return lookupHomeForUserWith(username, process.platform, execFileSync, readFileSync);
@@ -82,10 +97,13 @@ export function resolveAgentDetectPath(agent, home) {
     return resolveAgentDetectPathFor(agent, home, getPlatformKey());
 }
 function resolvePlaceholders(segments, skillName, home) {
-    const appdata = process.env["APPDATA"] ?? path.join(home, "AppData", "Roaming");
+    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,7 @@
 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;
 }>;

package/dist/core/revert.js

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

package/dist/index.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 import path from "node:path";
 import { parseArgs } from "node:util";
-import { AGENT_IDS } from "./types.js";
-import { loadManifest } from "./config/manifest.js";
 import { AGENT_REGISTRY } from "./config/agents.js";
-import { resolveHome } from "./core/resolve.js";
+import { loadManifest } from "./config/manifest.js";
+import { executeDeploy, planDeploy } from "./core/deploy.js";
 import { detectInstalledAgents } from "./core/detect.js";
-import { planDeploy, executeDeploy } from "./core/deploy.js";
-import { planRevert, planRevertAll, executeRevert } from "./core/revert.js";
+import { resolveHome } from "./core/resolve.js";
+import { executeRevert, planRevert, planRevertAll } from "./core/revert.js";
 import { UserError } from "./errors.js";
-import { logger, dryRunPrefix } from "./logger.js";
+import { dryRunPrefix, logger } from "./logger.js";
+import { AGENT_IDS } from "./types.js";
 const USAGE = `
 inception-engine - Deploy AI agent skills
 
@@ -30,7 +30,14 @@ Supported agents:
 function parseCLI(argv) {
     const args = argv.slice(2);
     if (args.length === 0) {
-        return { command: "help", directory: "", dryRun: false, agents: null, verbose: false, debug: false };
+        return {
+            command: "help",
+            directory: "",
+            dryRun: false,
+            agents: null,
+            verbose: false,
+            debug: false,
+        };
     }
     let parsed;
     try {
@@ -39,10 +46,10 @@ function parseCLI(argv) {
             allowPositionals: true,
             options: {
                 "dry-run": { type: "boolean", default: false },
-                "verbose": { type: "boolean", default: false },
-                "debug": { type: "boolean", default: false },
-                "help": { type: "boolean", default: false },
-                "agents": { type: "string" },
+                verbose: { type: "boolean", default: false },
+                debug: { type: "boolean", default: false },
+                help: { type: "boolean", default: false },
+                agents: { type: "string" },
             },
         });
     }
@@ -51,7 +58,14 @@ function parseCLI(argv) {
     }
     const { values, positionals } = parsed;
     if (values.help) {
-        return { command: "help", directory: "", dryRun: false, agents: null, verbose: false, debug: false };
+        return {
+            command: "help",
+            directory: "",
+            dryRun: false,
+            agents: null,
+            verbose: false,
+            debug: false,
+        };
     }
     let command = "deploy";
     let pos = positionals;
@@ -94,56 +108,59 @@ async function main() {
     const manifest = await loadManifest(options.directory);
     const home = resolveHome();
     if (options.command === "deploy") {
-        let detectedAgents;
-        if (options.agents) {
-            detectedAgents = options.agents;
-            if (options.verbose) {
-                logger.info(`Using specified agents: ${detectedAgents.join(", ")}`);
-            }
-        }
-        else {
-            detectedAgents = await detectInstalledAgents(home);
-            if (detectedAgents.length === 0) {
-                logger.info("No supported AI agents detected on this system.");
-                logger.info(`Install one of: ${AGENT_REGISTRY.map((a) => a.displayName).join(", ")}`);
-                return 0;
-            }
-            if (options.verbose) {
-                logger.info(`Detected agents: ${detectedAgents.join(", ")}`);
-            }
-        }
-        const actions = await planDeploy(manifest, options.directory, detectedAgents, home);
-        if (actions.length === 0) {
-            logger.info("No skills to deploy for detected agents.");
-            return 0;
-        }
-        logger.info(`${dryRunPrefix(options.dryRun)}Deploying ${actions.length} skill(s):`);
-        const { succeeded, failed } = await executeDeploy(actions, options.dryRun, options.verbose);
-        logger.info("");
-        if (failed.length > 0) {
-            logger.info(`${succeeded} succeeded, ${failed.length} failed`);
-            return 1;
-        }
-        else {
-            logger.info(`${succeeded} skill(s) deployed${options.dryRun ? " (dry-run)" : ""}`);
+        return runDeploy(options, manifest, home);
+    }
+    return runRevert(options, manifest, home);
+}
+async function runDeploy(options, manifest, home) {
+    let detectedAgents;
+    if (options.agents) {
+        detectedAgents = options.agents;
+        if (options.verbose) {
+            logger.info(`Using specified agents: ${detectedAgents.join(", ")}`);
         }
     }
     else {
-        const actions = options.agents
-            ? planRevert(manifest, options.agents, home)
-            : planRevertAll(manifest, home);
-        if (actions.length === 0) {
-            logger.info("No skills to revert.");
+        detectedAgents = await detectInstalledAgents(home);
+        if (detectedAgents.length === 0) {
+            logger.info("No supported AI agents detected on this system.");
+            logger.info(`Install one of: ${AGENT_REGISTRY.map((a) => a.displayName).join(", ")}`);
             return 0;
         }
-        logger.info(`${dryRunPrefix(options.dryRun)}Reverting ${actions.length} skill(s):`);
-        const { succeeded, skipped } = await executeRevert(actions, options.dryRun, options.verbose);
-        logger.info("");
-        const parts = [`${succeeded} removed`];
-        if (skipped > 0)
-            parts.push(`${skipped} skipped`);
-        logger.info(`${parts.join(", ")}${options.dryRun ? " (dry-run)" : ""}`);
+        if (options.verbose) {
+            logger.info(`Detected agents: ${detectedAgents.join(", ")}`);
+        }
+    }
+    const actions = await planDeploy(manifest, options.directory, detectedAgents, home);
+    if (actions.length === 0) {
+        logger.info("No skills to deploy for detected agents.");
+        return 0;
+    }
+    logger.info(`${dryRunPrefix(options.dryRun)}Deploying ${actions.length} skill(s):`);
+    const { succeeded, failed } = await executeDeploy(actions, options.dryRun, options.verbose, home);
+    logger.info("");
+    if (failed.length > 0) {
+        logger.info(`${succeeded} succeeded, ${failed.length} failed`);
+        return 1;
+    }
+    logger.info(`${succeeded} skill(s) deployed${options.dryRun ? " (dry-run)" : ""}`);
+    return 0;
+}
+async function runRevert(options, manifest, home) {
+    const actions = options.agents
+        ? planRevert(manifest, options.agents, home)
+        : planRevertAll(manifest, home);
+    if (actions.length === 0) {
+        logger.info("No skills to revert.");
+        return 0;
     }
+    logger.info(`${dryRunPrefix(options.dryRun)}Reverting ${actions.length} skill(s):`);
+    const { succeeded, skipped } = await executeRevert(actions, options.dryRun, options.verbose, home);
+    logger.info("");
+    const parts = [`${succeeded} removed`];
+    if (skipped > 0)
+        parts.push(`${skipped} skipped`);
+    logger.info(`${parts.join(", ")}${options.dryRun ? " (dry-run)" : ""}`);
     return 0;
 }
 const USER_ERROR_EXIT = {

package/dist/logger.js

@@ -57,5 +57,5 @@ export const logger = createLogger();
 export function dryRunPrefix(dryRun) {
     if (!dryRun)
         return "";
-    return Boolean(process.stdout.isTTY) ? `\x1b[36m[dry-run]\x1b[0m ` : `[dry-run] `;
+    return process.stdout.isTTY ? `\x1b[36m[dry-run]\x1b[0m ` : `[dry-run] `;
 }

package/dist/types.d.ts

@@ -14,12 +14,19 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuznai/inception-engine",
-  "version": "0.4.0",
+  "version": "0.5.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",
+    "fmt": "biome format --write .",
+    "lint": "biome lint . --max-diagnostics none",
     "dev": "node src/index.ts",
     "test": "node --test test/*.test.ts",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run typecheck && npm run lint && npm run build"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.4.8",
     "@types/node": "^25.5.0",
-    "typescript": "^5.8.0"
+    "typescript": "^6.0.2"
   }
 }