@caik.dev/cli 0.1.2 → 0.1.3

package/dist/index.js

@@ -2,10 +2,10 @@
 
 // src/index.ts
 import { Command } from "commander";
-import { readFileSync as readFileSync8 } from "fs";
+import { readFileSync as readFileSync9 } from "fs";
 import { fileURLToPath } from "url";
-import { dirname as dirname5, join as join8 } from "path";
-import chalk2 from "chalk";
+import { dirname as dirname5, join as join9 } from "path";
+import chalk3 from "chalk";
 
 // src/errors.ts
 var CaikError = class extends Error {
@@ -165,6 +165,11 @@ function writeConfig(config) {
   writeFileSync(path, JSON.stringify(config, null, 2) + "\n", "utf-8");
   chmodSync(path, 384);
 }
+function setApiKey(key) {
+  const config = readConfig();
+  config.apiKey = key;
+  writeConfig(config);
+}
 function resolveConfig(opts) {
   const config = readConfig();
   return {
@@ -294,7 +299,7 @@ ${result.total} result${result.total !== 1 ? "s" : ""} found.`);
 }
 
 // src/commands/install.ts
-import { existsSync as existsSync7 } from "fs";
+import { existsSync as existsSync7, unlinkSync as unlinkSync2 } from "fs";
 import { writeFileSync as writeFileSync6, mkdirSync as mkdirSync6 } from "fs";
 import { dirname as dirname3, resolve } from "path";
 import { execSync as execSync3 } from "child_process";
@@ -335,7 +340,8 @@ function detectOpenClaw() {
   const home = homedir2();
   const openclawDir = join2(home, ".openclaw");
   const cwdConfig = join2(process.cwd(), "openclaw.json");
-  if (!existsSync2(openclawDir) && !existsSync2(cwdConfig)) return null;
+  const inPath = commandExists("openclaw");
+  if (!existsSync2(openclawDir) && !existsSync2(cwdConfig) && !inPath) return null;
   const configPaths = [];
   if (existsSync2(cwdConfig)) configPaths.push(cwdConfig);
   if (existsSync2(join2(openclawDir, "openclaw.json"))) {
@@ -453,26 +459,26 @@ function upsertRegistryEntry(entry) {
   }
   writeRegistry(registry);
 }
-function removeRegistryEntry(slug, platform) {
+function removeRegistryEntry(slug, platform2) {
   const registry = readRegistry();
   const idx = registry.entries.findIndex(
-    (e) => e.slug === slug && e.platform === platform
+    (e) => e.slug === slug && e.platform === platform2
   );
   if (idx < 0) return null;
   const [removed] = registry.entries.splice(idx, 1);
   writeRegistry(registry);
   return removed;
 }
-function findRegistryEntry(slug, platform) {
+function findRegistryEntry(slug, platform2) {
   const registry = readRegistry();
   return registry.entries.find(
-    (e) => e.slug === slug && (!platform || e.platform === platform)
+    (e) => e.slug === slug && (!platform2 || e.platform === platform2)
   ) ?? null;
 }
-function listRegistryEntries(platform) {
+function listRegistryEntries(platform2) {
   const registry = readRegistry();
-  if (!platform) return registry.entries;
-  return registry.entries.filter((e) => e.platform === platform);
+  if (!platform2) return registry.entries;
+  return registry.entries.filter((e) => e.platform === platform2);
 }
 function cleanupFiles(entry) {
   const failed = [];
@@ -771,6 +777,12 @@ var OpenClawAdapter = class {
   get openclawDir() {
     return join5(homedir4(), ".openclaw");
   }
+  get managedHooksDir() {
+    return join5(this.openclawDir, "hooks");
+  }
+  get caikHookDir() {
+    return join5(this.managedHooksDir, "caik-contributions");
+  }
   /** OpenClaw's own config — NOT where MCP servers go. */
   get openclawConfigPath() {
     return join5(this.openclawDir, "openclaw.json");
@@ -849,8 +861,12 @@ var OpenClawAdapter = class {
   async detect() {
     const hasDir = existsSync5(this.openclawDir);
     const inPath = this.isInPath();
-    if (!hasDir && !inPath) return null;
+    const hasCwdConfig = existsSync5(join5(process.cwd(), "openclaw.json"));
+    if (!hasDir && !inPath && !hasCwdConfig) return null;
     const configPaths = [];
+    if (hasCwdConfig) {
+      configPaths.push(join5(process.cwd(), "openclaw.json"));
+    }
     if (existsSync5(this.openclawConfigPath)) {
       configPaths.push(this.openclawConfigPath);
     }
@@ -886,14 +902,27 @@ var OpenClawAdapter = class {
     this.writeJson(this.mcpConfigPath, config);
   }
   async registerHooks(_hookConfig) {
-    console.error(
-      "[caik] To enable CAIK telemetry hooks in OpenClaw, install the CAIK hook pack:\n    openclaw hooks install @caik.dev/openclaw-hooks\n  (Hook pack not yet available \u2014 hooks are optional, CAIK works without them.)"
+    if (!existsSync5(this.caikHookDir)) {
+      mkdirSync4(this.caikHookDir, { recursive: true });
+    }
+    writeFileSync4(
+      join5(this.caikHookDir, "HOOK.md"),
+      HOOK_MD_CONTENT,
+      "utf-8"
+    );
+    writeFileSync4(
+      join5(this.caikHookDir, "handler.js"),
+      HANDLER_JS_CONTENT,
+      "utf-8"
     );
   }
   async unregisterHooks() {
-    console.error(
-      "[caik] To remove CAIK hooks from OpenClaw, run:\n    openclaw hooks uninstall @caik.dev/openclaw-hooks"
-    );
+    if (existsSync5(this.caikHookDir)) {
+      try {
+        rmSync2(this.caikHookDir, { recursive: true, force: true });
+      } catch {
+      }
+    }
   }
   async installSkill(_slug, content, files) {
     if (!existsSync5(this.skillDir)) {
@@ -950,6 +979,135 @@ var OpenClawAdapter = class {
     return !!servers && MCP_KEY2 in servers;
   }
 };
+var HOOK_MD_CONTENT = `---
+name: caik-contributions
+description: "Track artifact usage to build your CAIK contribution level and community karma"
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "\u{1F4E6}",
+        "events": ["command:new", "command:reset", "command:stop", "command"],
+        "install": [{ "id": "local", "kind": "local", "label": "CAIK CLI hook pack" }],
+      },
+  }
+---
+
+# CAIK Contribution Tracking
+
+Reports session lifecycle events to the CAIK API to build your contribution level and community karma.
+
+## What It Does
+
+- **Session start** (\`command:new\`): Records that a new agent session began
+- **Session end** (\`command:stop\`, \`command:reset\`): Flushes buffered tool-use events and records session end
+- **Tool use** (\`command\`): Buffers tool execution events for batch reporting
+
+## Privacy
+
+- Only sends: event type, platform name, tool name, timestamp
+- No code, file contents, or conversation data is transmitted
+- Contribution tracking can be disabled: \`caik config set contributions false\`
+
+## Configuration
+
+Set \`CAIK_API_URL\` and \`CAIK_API_KEY\` environment variables, or configure via \`caik init --auth\`.
+`;
+var HANDLER_JS_CONTENT = `/**
+ * CAIK contribution tracking hook for OpenClaw.
+ * Fire-and-forget \u2014 never blocks the agent, never throws.
+ */
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+const CAIK_DIR = path.join(os.homedir(), ".caik");
+const PENDING_PATH = path.join(CAIK_DIR, "pending-events.json");
+const CONFIG_PATH = path.join(CAIK_DIR, "config.json");
+const TIMEOUT_MS = 2000;
+
+async function loadConfig() {
+  try {
+    const raw = await fs.readFile(CONFIG_PATH, "utf-8");
+    return JSON.parse(raw);
+  } catch { return {}; }
+}
+
+async function getApiUrl() {
+  const cfg = await loadConfig();
+  return process.env.CAIK_API_URL || cfg.apiUrl || "https://caik.dev";
+}
+
+async function getApiKey() {
+  const cfg = await loadConfig();
+  return process.env.CAIK_API_KEY || cfg.apiKey || null;
+}
+
+async function readPending() {
+  try {
+    const raw = await fs.readFile(PENDING_PATH, "utf-8");
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch { return []; }
+}
+
+async function writePending(events) {
+  await fs.mkdir(CAIK_DIR, { recursive: true });
+  await fs.writeFile(PENDING_PATH, JSON.stringify(events) + "\\n", "utf-8");
+}
+
+async function appendEvent(event) {
+  const events = await readPending();
+  events.push(event);
+  await writePending(events);
+  return events;
+}
+
+async function clearPending() { await writePending([]); }
+
+async function postEvents(events) {
+  if (events.length === 0) return;
+  const apiUrl = await getApiUrl();
+  const apiKey = await getApiKey();
+  const headers = { "Content-Type": "application/json" };
+  if (apiKey) headers["Authorization"] = "Bearer " + apiKey;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    await fetch(apiUrl + "/api/v1/events", {
+      method: "POST", headers,
+      body: JSON.stringify({ events }),
+      signal: controller.signal,
+    });
+    await clearPending();
+  } catch { /* fire-and-forget */ }
+  finally { clearTimeout(timeout); }
+}
+
+const handler = async (event) => {
+  try {
+    const cfg = await loadConfig();
+    if (cfg.contributions === false || cfg.telemetry === false) return;
+    const timestamp = (event.timestamp ?? new Date()).toISOString();
+    if (event.type === "command") {
+      const action = event.action;
+      if (action === "new") {
+        await postEvents([{ type: "session_start", platform: "openclaw", timestamp }]);
+      } else if (action === "stop" || action === "reset") {
+        const pending = await readPending();
+        pending.push({ type: "session_end", platform: "openclaw", timestamp });
+        await postEvents(pending);
+      } else {
+        await appendEvent({ type: "tool_use", platform: "openclaw", tool: action, timestamp });
+        const pending = await readPending();
+        if (pending.length >= 50) await postEvents(pending);
+      }
+    }
+  } catch { /* never fail */ }
+};
+
+export default handler;
+`;
 
 // src/platform/cursor.ts
 import { existsSync as existsSync6, mkdirSync as mkdirSync5, readFileSync as readFileSync5, writeFileSync as writeFileSync5, rmSync as rmSync3 } from "fs";
@@ -1210,14 +1368,29 @@ Examples:
       detectedPlatform = legacyPlatformMap[raw] ?? raw;
     } else {
       const detected = detectPlatforms();
-      if (detected.length > 0) {
+      if (detected.length > 1 && !opts.yes && !globalOpts.json) {
+        console.log(info("Multiple platforms detected:"));
+        for (let i = 0; i < detected.length; i++) {
+          const d = detected[i];
+          console.log(info(`  ${i + 1}) ${d.name} (${d.tier})`));
+        }
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await rl.question(`Select platform [1-${detected.length}]: `);
+        rl.close();
+        const idx = parseInt(answer, 10);
+        if (isNaN(idx) || idx < 1 || idx > detected.length) {
+          console.log(error("Invalid selection. Aborting."));
+          return;
+        }
+        detectedPlatform = detected[idx - 1].name;
+      } else if (detected.length > 0) {
         detectedPlatform = detected[0].name;
       }
     }
-    const platform = detectedPlatform;
+    const platform2 = detectedPlatform;
     const spinner = createSpinner(`Fetching ${slug}...`);
     if (!globalOpts.json) spinner.start();
-    const params = { platform };
+    const params = { platform: platform2 };
     const installInfo = await client.get(`/install/${encodeURIComponent(slug)}`, params);
     if (globalOpts.json) {
       spinner.stop();
@@ -1268,41 +1441,77 @@ Examples:
       }
       spinner.start();
     }
-    for (const file of safeFiles) {
-      const dir = dirname3(file.resolvedPath);
-      if (!existsSync7(dir)) {
-        mkdirSync6(dir, { recursive: true });
+    const writtenFiles = [];
+    const resolvedPlatform = detectedPlatform ?? "generic";
+    let registryWritten = false;
+    let mcpRegistered = false;
+    let skillInstalled = false;
+    const rollback = async () => {
+      for (const filePath of writtenFiles) {
+        try {
+          if (existsSync7(filePath)) unlinkSync2(filePath);
+        } catch {
+        }
       }
-      writeFileSync6(file.resolvedPath, file.content, "utf-8");
-    }
-    if (installInfo.installCommand) {
-      try {
+      if (registryWritten) {
+        try {
+          removeRegistryEntry(slug, resolvedPlatform);
+        } catch {
+        }
+      }
+      const adapter2 = getPlatformAdapter(resolvedPlatform);
+      if (mcpRegistered) {
+        try {
+          await adapter2.unregisterMcp();
+        } catch {
+        }
+      }
+      if (skillInstalled && adapter2.uninstallSkill) {
+        try {
+          await adapter2.uninstallSkill(slug);
+        } catch {
+        }
+      }
+      if (writtenFiles.length > 0) {
+        console.log(info(`Rolled back ${writtenFiles.length} file(s) written during install.`));
+      }
+    };
+    try {
+      for (const file of safeFiles) {
+        const dir = dirname3(file.resolvedPath);
+        if (!existsSync7(dir)) {
+          mkdirSync6(dir, { recursive: true });
+        }
+        writeFileSync6(file.resolvedPath, file.content, "utf-8");
+        writtenFiles.push(file.resolvedPath);
+      }
+      if (installInfo.installCommand) {
         execSync3(installInfo.installCommand, { stdio: "pipe" });
-      } catch (err) {
-        spinner.stop();
-        console.error(error(`Install command failed: ${err instanceof Error ? err.message : String(err)}`));
-        client.post("/telemetry/install", {
-          artifactSlug: slug,
-          platform,
-          success: false,
-          errorMessage: err instanceof Error ? err.message : String(err)
-        }).catch(() => {
-        });
-        process.exit(1);
       }
-    }
-    if (installInfo.postInstallHook) {
-      try {
-        execSync3(installInfo.postInstallHook, { stdio: "pipe" });
-      } catch {
+      if (installInfo.postInstallHook) {
+        try {
+          execSync3(installInfo.postInstallHook, { stdio: "pipe" });
+        } catch {
+        }
       }
+    } catch (err) {
+      spinner.stop();
+      console.error(error(`Install failed: ${err instanceof Error ? err.message : String(err)}`));
+      await rollback();
+      client.post("/telemetry/install", {
+        artifactSlug: slug,
+        platform: platform2,
+        success: false,
+        errorMessage: err instanceof Error ? err.message : String(err)
+      }).catch(() => {
+      });
+      process.exit(1);
     }
     spinner.stop();
     console.log(success(`Installed ${installInfo.artifact.name}`));
     if (installInfo.contract?.touchedPaths) {
       console.log(info(`Files: ${installInfo.contract.touchedPaths.join(", ")}`));
     }
-    const resolvedPlatform = detectedPlatform ?? "generic";
     upsertRegistryEntry({
       slug,
       version: installInfo.artifact.version ?? "0.0.0",
@@ -1312,11 +1521,13 @@ Examples:
       files: safeFiles.map((f) => f.resolvedPath),
       artifactType: installInfo.artifact.primitive ?? "unknown"
     });
+    registryWritten = true;
     const adapter = getPlatformAdapter(resolvedPlatform);
     const primitive = installInfo.artifact.primitive;
     if (primitive === "connector") {
       try {
         await adapter.registerMcp(getDefaultMcpConfig());
+        mcpRegistered = true;
       } catch {
       }
     }
@@ -1324,12 +1535,13 @@ Examples:
       try {
         const content = safeFiles.map((f) => f.content).join("\n");
         await adapter.installSkill(slug, content);
+        skillInstalled = true;
       } catch {
       }
     }
     client.post("/telemetry/install", {
       artifactSlug: slug,
-      platform,
+      platform: platform2,
       success: true
     }).catch(() => {
     });
@@ -1339,14 +1551,120 @@ Examples:
 // src/commands/init.ts
 import { createInterface as createInterface2 } from "readline/promises";
 import { stdin, stdout } from "process";
+
+// src/auth.ts
+import { createServer } from "http";
+import { execFile } from "child_process";
+import { URL as URL2 } from "url";
+import { platform } from "os";
+import { randomBytes } from "crypto";
+var TIMEOUT_MS = 6e4;
+function openBrowser(url) {
+  const os = platform();
+  return new Promise((resolve3) => {
+    if (os === "darwin") {
+      execFile("open", [url], (err) => resolve3(!err));
+    } else if (os === "win32") {
+      execFile("cmd", ["/c", "start", "", url], (err) => resolve3(!err));
+    } else {
+      execFile("xdg-open", [url], (err) => resolve3(!err));
+    }
+  });
+}
+async function authenticate(apiUrl, port = 0) {
+  const state = randomBytes(16).toString("hex");
+  return new Promise((resolve3, reject) => {
+    const server = createServer((req, res) => {
+      const actualPort = server.address().port;
+      const reqUrl = new URL2(req.url ?? "/", `http://localhost:${actualPort}`);
+      if (reqUrl.pathname !== "/callback") {
+        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.end("Not found");
+        return;
+      }
+      const returnedState = reqUrl.searchParams.get("state");
+      if (returnedState !== state) {
+        res.writeHead(403, { "Content-Type": "text/html" });
+        res.end(
+          "<html><body><h2>Authentication failed</h2><p>Invalid state parameter (possible CSRF). You can close this tab.</p></body></html>"
+        );
+        return;
+      }
+      const apiKeyParam = reqUrl.searchParams.get("api_key");
+      if (!apiKeyParam) {
+        res.writeHead(400, { "Content-Type": "text/html" });
+        res.end(
+          "<html><body><h2>Authentication failed</h2><p>No API key received. You can close this tab.</p></body></html>"
+        );
+        cleanup();
+        reject(new Error("No API key received in callback"));
+        return;
+      }
+      setApiKey(apiKeyParam);
+      res.writeHead(200, { "Content-Type": "text/html" });
+      res.end(
+        "<html><body><h2>Authenticated!</h2><p>You can close this tab and return to your terminal.</p></body></html>"
+      );
+      cleanup();
+      resolve3(apiKeyParam);
+    });
+    const timeout = setTimeout(() => {
+      cleanup();
+      reject(new Error("Authentication timed out after 60 seconds"));
+    }, TIMEOUT_MS);
+    function cleanup() {
+      clearTimeout(timeout);
+      server.close();
+    }
+    server.listen(port, async () => {
+      const actualPort = server.address().port;
+      const callbackUrl = `http://localhost:${actualPort}/callback`;
+      const loginUrl = `${apiUrl}/auth/signin?redirect=${encodeURIComponent(callbackUrl)}&state=${encodeURIComponent(state)}`;
+      console.log(info(`Listening on http://localhost:${actualPort} for callback...`));
+      const opened = await openBrowser(loginUrl);
+      if (opened) {
+        console.log(info("Browser opened. Complete sign-in to continue."));
+      } else {
+        console.log(
+          error("Could not open browser automatically.")
+        );
+        console.log(info(`Open this URL manually:
+  ${loginUrl}`));
+      }
+    });
+    server.on("error", (err) => {
+      clearTimeout(timeout);
+      reject(
+        new Error(
+          `Failed to start auth server: ${err.message}`
+        )
+      );
+    });
+  });
+}
+
+// src/commands/init.ts
 function registerInitCommand(program2) {
   program2.command("init").description("Configure the CAIK CLI").option("--auth", "Set up authentication (opens browser)").addHelpText("after", `
 Examples:
   caik init
-  caik init --auth`).action(async (_opts) => {
+  caik init --auth`).action(async (opts) => {
+    const config = readConfig();
+    if (opts.auth) {
+      console.log(info("Opening browser for authentication..."));
+      try {
+        const apiKey = await authenticate(config.apiUrl);
+        config.apiKey = apiKey;
+        writeConfig(config);
+        console.log(success("Authenticated and saved API key"));
+        console.log(info(`Config saved to ~/.caik/config.json`));
+      } catch (err) {
+        console.log(error(`Authentication failed: ${err instanceof Error ? err.message : String(err)}`));
+      }
+      return;
+    }
     const rl = createInterface2({ input: stdin, output: stdout });
     try {
-      const config = readConfig();
       const apiUrl = await rl.question(`API URL (${config.apiUrl}): `);
       if (apiUrl.trim()) {
         config.apiUrl = apiUrl.trim();
@@ -2016,7 +2334,7 @@ Artifact: ${entry.slug} (${entry.artifactType})`));
     if (!globalOpts.json) spinner.start();
     const failedFiles = cleanupFiles(entry);
     const adapter = getPlatformAdapter(entry.platform);
-    if (entry.artifactType === "mcp-server") {
+    if (entry.artifactType === "connector" || entry.artifactType === "mcp-server") {
       try {
         await adapter.unregisterMcp();
       } catch (err) {
@@ -2027,7 +2345,8 @@ Artifact: ${entry.slug} (${entry.artifactType})`));
         }
       }
     }
-    if ((entry.artifactType === "skill" || entry.artifactType === "subagent" || entry.artifactType === "command") && adapter.uninstallSkill) {
+    const skillTypes = /* @__PURE__ */ new Set(["executable", "composition", "skill", "subagent", "command"]);
+    if (skillTypes.has(entry.artifactType) && adapter.uninstallSkill) {
       try {
         await adapter.uninstallSkill(slug);
       } catch (err) {
@@ -2159,12 +2478,12 @@ function createClient(program2) {
 }
 function registerHookCommand(program2) {
   const hook = program2.command("hook").description("Platform hook callbacks (observation only, never gates agent actions)");
-  hook.command("session-start").description("Log session start event").action(async () => {
+  hook.command("session-start").description("Log session start event").option("--platform <name>", "Platform name", "claude-code").action(async (opts) => {
     try {
       const client = createClient(program2);
       const event = {
         type: "session_start",
-        platform: "claude-code",
+        platform: opts.platform ?? "claude-code",
         timestamp: (/* @__PURE__ */ new Date()).toISOString()
       };
       await postSingleEventWithTimeout(client, event);
@@ -2172,13 +2491,13 @@ function registerHookCommand(program2) {
     }
     process.exit(0);
   });
-  hook.command("session-end").description("Flush pending events and log session end").action(async () => {
+  hook.command("session-end").description("Flush pending events and log session end").option("--platform <name>", "Platform name", "claude-code").action(async (opts) => {
     try {
       const client = createClient(program2);
       const pending = readPendingEvents();
       const endEvent = {
         type: "session_end",
-        platform: "claude-code",
+        platform: opts.platform ?? "claude-code",
         timestamp: (/* @__PURE__ */ new Date()).toISOString()
       };
       pending.push(endEvent);
@@ -2187,11 +2506,11 @@ function registerHookCommand(program2) {
     }
     process.exit(0);
   });
-  hook.command("post-tool-use").description("Buffer a tool-use event").option("--tool <name>", "Tool name").option("--success <bool>", "Whether the tool call succeeded").action(async (opts) => {
+  hook.command("post-tool-use").description("Buffer a tool-use event").option("--platform <name>", "Platform name", "claude-code").option("--tool <name>", "Tool name").option("--success <bool>", "Whether the tool call succeeded").action(async (opts) => {
     try {
       const event = {
         type: "tool_use",
-        platform: "claude-code",
+        platform: opts.platform ?? "claude-code",
         tool: opts.tool,
         success: opts.success === "true" || opts.success === true,
         timestamp: (/* @__PURE__ */ new Date()).toISOString()
@@ -2255,10 +2574,16 @@ function registerHookCommand(program2) {
 
 // src/commands/setup.ts
 import { createInterface as createInterface5 } from "readline/promises";
+import { existsSync as existsSync12 } from "fs";
 
 // src/platform/templates/claude-code-skill.ts
 function getClaudeCodeSkillContent() {
-  return `# CAIK \u2014 AI Artifact Registry
+  return `---
+name: caik
+description: Search, install, and manage AI coding artifacts (skills, rules, prompts, MCP servers, knowledge packs) from the CAIK community registry. Use when the user wants to find reusable building blocks, install artifacts, or contribute back to the community.
+---
+
+# CAIK \u2014 AI Artifact Registry
 
 CAIK is a community-driven registry for AI coding artifacts \u2014 skills, rules, prompts, MCP servers, and knowledge packs. Use CAIK to discover, install, and share reusable building blocks across projects.
 
@@ -2296,7 +2621,12 @@ Ask your agent: "Find CAIK artifacts for [your use case]" \u2014 the agent will
 
 // src/platform/templates/cursor-skill.ts
 function getCursorSkillContent() {
-  return `# CAIK \u2014 AI Artifact Registry
+  return `---
+name: caik
+description: Search, install, and manage AI coding artifacts (skills, rules, prompts, MCP servers, knowledge packs) from the CAIK community registry. Use when the user wants to find reusable building blocks, install artifacts, or contribute back to the community.
+---
+
+# CAIK \u2014 AI Artifact Registry
 
 CAIK is a community-driven registry for AI coding artifacts. Use CAIK to discover and install rules, prompts, and knowledge packs into your Cursor workspace.
 
@@ -2330,7 +2660,12 @@ Ask Cursor: "Find CAIK artifacts for [your use case]" to search the registry.
 
 // src/platform/templates/openclaw-skill.ts
 function getOpenClawSkillContent() {
-  return `# CAIK \u2014 AI Artifact Registry
+  return `---
+name: caik
+description: Search, install, and manage AI coding artifacts (skills, rules, prompts, MCP servers, knowledge packs) from the CAIK community registry. Use when the user wants to find reusable building blocks, install artifacts, or contribute back to the community.
+---
+
+# CAIK \u2014 AI Artifact Registry
 
 CAIK is a community-driven registry for AI coding artifacts \u2014 skills, rules, prompts, MCP servers, and knowledge packs. Use CAIK to discover and install reusable building blocks.
 
@@ -2338,9 +2673,9 @@ CAIK is a community-driven registry for AI coding artifacts \u2014 skills, rules
 
 CAIK artifacts integrate with OpenClaw's skill system. Installed skills are available as callable capabilities within your OpenClaw agent.
 
-## Hook Telemetry
+## Contribution Tracking
 
-CAIK uses OpenClaw lifecycle hooks to track artifact usage. When you invoke a CAIK-installed skill, outcome data is reported automatically to improve community rankings. You can disable telemetry with \`caik config set telemetry false\`.
+CAIK uses OpenClaw lifecycle hooks to track artifact usage. When you invoke a CAIK-installed skill, outcome data is reported automatically to build your contribution level and community karma. You can disable it with \`caik config set contributions false\`.
 
 ## MCP Tools
 
@@ -2367,8 +2702,8 @@ Ask your agent: "Find CAIK artifacts for [your use case]" to search the registry
 }
 
 // src/platform/templates/index.ts
-function getSkillContent(platform) {
-  switch (platform) {
+function getSkillContent(platform2) {
+  switch (platform2) {
     case "claude-code":
       return getClaudeCodeSkillContent();
     case "cursor":
@@ -2410,8 +2745,8 @@ Ask your agent: "Find CAIK artifacts for [your use case]" to search the registry
 }
 
 // src/commands/setup.ts
-function getHookConfig(platform) {
-  if (platform === "claude-code") {
+function getHookConfig(platform2) {
+  if (platform2 === "claude-code") {
     return {
       hooks: {
         SessionStart: [{ type: "command", command: "npx -y @caik.dev/cli hook session-start" }],
@@ -2420,7 +2755,7 @@ function getHookConfig(platform) {
       }
     };
   }
-  if (platform === "cursor") {
+  if (platform2 === "cursor") {
     return {
       hooks: {
         sessionStart: "npx -y @caik.dev/cli hook cursor-session-start",
@@ -2431,24 +2766,154 @@ function getHookConfig(platform) {
   }
   return {
     hooks: {
-      session_start: "npx -y @caik.dev/cli hook session-start",
-      session_end: "npx -y @caik.dev/cli hook session-end",
-      after_tool_call: "npx -y @caik.dev/cli hook post-tool-use"
+      session_start: "npx -y @caik.dev/cli hook session-start --platform openclaw",
+      session_end: "npx -y @caik.dev/cli hook session-end --platform openclaw",
+      after_tool_call: "npx -y @caik.dev/cli hook post-tool-use --platform openclaw"
     }
   };
 }
+async function runRepair() {
+  console.log(heading("\nCAIK Repair"));
+  console.log("\u2550".repeat(40));
+  console.log();
+  const spinner = createSpinner("Detecting platforms...");
+  spinner.start();
+  const detected = detectPlatforms();
+  spinner.stop();
+  if (detected.length === 0) {
+    console.log(warn("No supported agent platforms detected. Nothing to repair."));
+    return;
+  }
+  console.log(info(`Detected ${detected.length} platform(s): ${detected.map((p) => p.name).join(", ")}`));
+  console.log();
+  let repairedMcp = 0;
+  let repairedHooks = 0;
+  let repairedSkills = 0;
+  const registryWarnings = [];
+  for (const platform2 of detected) {
+    console.log(heading(`Checking ${platform2.name}...`));
+    console.log("\u2500".repeat(40));
+    const adapter = getPlatformAdapter(platform2.name);
+    let mcpRegistered = false;
+    try {
+      mcpRegistered = await adapter.isRegistered();
+    } catch {
+    }
+    if (mcpRegistered) {
+      console.log(`  MCP server:  ${success("registered")}`);
+    } else {
+      const mcpSpinner = createSpinner("  Re-registering MCP server...");
+      mcpSpinner.start();
+      try {
+        const mcpConfig = getDefaultMcpConfig();
+        await adapter.registerMcp(mcpConfig);
+        mcpSpinner.stop();
+        console.log(`  MCP server:  ${success("repaired")} (re-registered)`);
+        repairedMcp++;
+      } catch (err) {
+        mcpSpinner.stop();
+        console.log(`  MCP server:  ${error(`repair failed: ${err instanceof Error ? err.message : String(err)}`)}`);
+      }
+    }
+    if (adapter.registerHooks && platform2.capabilities.hooks) {
+      const hookSpinner = createSpinner("  Ensuring hooks are registered...");
+      hookSpinner.start();
+      try {
+        const hookConfig = getHookConfig(platform2.name);
+        await adapter.registerHooks(hookConfig);
+        hookSpinner.stop();
+        console.log(`  Hooks:       ${success("ensured")}`);
+        repairedHooks++;
+      } catch (err) {
+        hookSpinner.stop();
+        console.log(`  Hooks:       ${error(`repair failed: ${err instanceof Error ? err.message : String(err)}`)}`);
+      }
+    } else if (!platform2.capabilities.hooks) {
+      console.log(`  Hooks:       ${dim("not supported on this platform")}`);
+    }
+    if (adapter.installSkill && platform2.capabilities.skills) {
+      const skillSpinner = createSpinner("  Ensuring SKILL.md is installed...");
+      skillSpinner.start();
+      try {
+        const content = getSkillContent(platform2.name);
+        await adapter.installSkill("caik", content);
+        skillSpinner.stop();
+        console.log(`  SKILL.md:    ${success("ensured")}`);
+        repairedSkills++;
+      } catch (err) {
+        skillSpinner.stop();
+        console.log(`  SKILL.md:    ${error(`repair failed: ${err instanceof Error ? err.message : String(err)}`)}`);
+      }
+    } else if (!platform2.capabilities.skills) {
+      console.log(`  SKILL.md:    ${dim("not supported on this platform")}`);
+    }
+    console.log();
+  }
+  const registryEntries = listRegistryEntries();
+  if (registryEntries.length > 0) {
+    console.log(heading("Registry Integrity"));
+    console.log("\u2500".repeat(40));
+    let cleanEntries = 0;
+    for (const entry of registryEntries) {
+      const missing = entry.files.filter((f) => !existsSync12(f));
+      if (missing.length > 0) {
+        const msg = `${entry.slug} (${entry.platform}): ${missing.length} missing file(s)`;
+        registryWarnings.push(msg);
+        console.log(`  ${warn(msg)}`);
+        for (const f of missing) {
+          console.log(`    ${dim(f)}`);
+        }
+      } else {
+        cleanEntries++;
+      }
+    }
+    if (registryWarnings.length === 0) {
+      console.log(`  ${success("All")} ${registryEntries.length} registry entries have their files intact.`);
+    } else if (cleanEntries > 0) {
+      console.log(`  ${success(`${cleanEntries}`)} entries OK, ${warn(`${registryWarnings.length}`)} with missing files.`);
+    }
+    if (registryWarnings.length > 0) {
+      console.log();
+      console.log(
+        dim("  Artifact files cannot be auto-repaired. Run `caik install <slug>` to reinstall.")
+      );
+    }
+    console.log();
+  }
+  console.log(heading("Repair Summary"));
+  console.log("\u2550".repeat(40));
+  const actions = [];
+  if (repairedMcp > 0) actions.push(`${repairedMcp} MCP registration(s) repaired`);
+  if (repairedHooks > 0) actions.push(`${repairedHooks} hook registration(s) ensured`);
+  if (repairedSkills > 0) actions.push(`${repairedSkills} skill installation(s) ensured`);
+  if (registryWarnings.length > 0) actions.push(`${registryWarnings.length} registry warning(s)`);
+  if (actions.length === 0) {
+    console.log(success("Everything looks good. No repairs needed."));
+  } else {
+    for (const a of actions) {
+      console.log(`  ${info(a)}`);
+    }
+  }
+  console.log();
+}
 function registerSetupCommand(program2) {
-  program2.command("setup").description("Interactive setup wizard \u2014 configure CAIK for your agent platforms").option("--platform <name>", "Skip detection, configure a specific platform").option("--skip-hooks", "Register MCP only, skip hook registration").option("--skip-stacks", "Skip stack recommendations").option("-y, --yes", "Accept all defaults (non-interactive)").addHelpText("after", `
+  program2.command("setup").description("Interactive setup wizard \u2014 configure CAIK for your agent platforms").option("--platform <name>", "Skip detection, configure a specific platform").option("--skip-hooks", "Register MCP only, skip hook registration").option("--skip-stacks", "Skip stack recommendations").option("--repair", "Detect and fix configuration drift (re-register MCP, hooks, skills)").option("-y, --yes", "Accept all defaults (non-interactive)").addHelpText("after", `
 Examples:
   caik setup
   caik setup --platform claude-code
-  caik setup --yes --skip-hooks`).action(async (opts) => {
+  caik setup --yes --skip-hooks
+  caik setup --repair`).action(async (opts) => {
     const globalOpts = program2.opts();
     const { apiKey } = resolveConfig(globalOpts);
     const skipHooks = Boolean(opts.skipHooks);
     const skipStacks = Boolean(opts.skipStacks);
     const autoYes = Boolean(opts.yes);
     const platformFlag = opts.platform;
+    const repair = Boolean(opts.repair);
+    if (repair) {
+      await runRepair();
+      return;
+    }
     console.log(heading("\nCAIK Setup Wizard"));
     console.log("\u2550".repeat(40));
     console.log();
@@ -2508,10 +2973,10 @@ Examples:
       }
     }
     console.log();
-    for (const platform of selected) {
-      console.log(heading(`Configuring ${platform.name}...`));
+    for (const platform2 of selected) {
+      console.log(heading(`Configuring ${platform2.name}...`));
       console.log("\u2500".repeat(40));
-      const adapter = getPlatformAdapter(platform.name);
+      const adapter = getPlatformAdapter(platform2.name);
       const mcpConfig = getDefaultMcpConfig();
       const mcpSpinner = createSpinner("Registering MCP server...");
       mcpSpinner.start();
@@ -2523,28 +2988,31 @@ Examples:
         mcpSpinner.stop();
         console.log(error(`Failed to register MCP server: ${err instanceof Error ? err.message : String(err)}`));
       }
-      if (!skipHooks && adapter.registerHooks && platform.capabilities.hooks) {
+      if (!skipHooks && adapter.registerHooks && platform2.capabilities.hooks) {
         const hookSpinner = createSpinner("Registering hooks...");
         hookSpinner.start();
         try {
-          const hookConfig = getHookConfig(platform.name);
+          const hookConfig = getHookConfig(platform2.name);
           await adapter.registerHooks(hookConfig);
           hookSpinner.stop();
           console.log(success("Hooks registered"));
+          if (platform2.name === "openclaw") {
+            console.log(dim("  Restart the OpenClaw gateway to load hooks: openclaw daemon restart"));
+          }
         } catch (err) {
           hookSpinner.stop();
           console.log(error(`Failed to register hooks: ${err instanceof Error ? err.message : String(err)}`));
         }
-      } else if (!skipHooks && !platform.capabilities.hooks) {
+      } else if (!skipHooks && !platform2.capabilities.hooks) {
         console.log(dim("  Hooks not supported on this platform \u2014 skipped"));
       } else if (skipHooks) {
         console.log(dim("  Hooks skipped (--skip-hooks)"));
       }
-      if (adapter.installSkill && platform.capabilities.skills) {
+      if (adapter.installSkill && platform2.capabilities.skills) {
         const skillSpinner = createSpinner("Installing SKILL.md...");
         skillSpinner.start();
         try {
-          const content = getSkillContent(platform.name);
+          const content = getSkillContent(platform2.name);
           await adapter.installSkill("caik", content);
           skillSpinner.stop();
           console.log(success("SKILL.md installed"));
@@ -2575,13 +3043,147 @@ Examples:
   });
 }
 
+// src/commands/upgrade.ts
+import { execSync as execSync5 } from "child_process";
+
+// src/update-check.ts
+import { readFileSync as readFileSync8, writeFileSync as writeFileSync9, mkdirSync as mkdirSync9, existsSync as existsSync13 } from "fs";
+import { join as join8 } from "path";
+import { homedir as homedir7 } from "os";
+import chalk2 from "chalk";
+var PKG_NAME = "@caik.dev/cli";
+var CACHE_PATH = join8(homedir7(), ".caik", "update-check.json");
+var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+function readCache() {
+  try {
+    const raw = readFileSync8(CACHE_PATH, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function writeCache(entry) {
+  const dir = join8(homedir7(), ".caik");
+  if (!existsSync13(dir)) {
+    mkdirSync9(dir, { recursive: true });
+  }
+  writeFileSync9(CACHE_PATH, JSON.stringify(entry) + "\n", "utf-8");
+}
+function getCurrentVersion() {
+  try {
+    const pkgPath = join8(
+      new URL(".", import.meta.url).pathname,
+      "..",
+      "package.json"
+    );
+    const pkg = JSON.parse(readFileSync8(pkgPath, "utf-8"));
+    return pkg.version;
+  } catch {
+    return "0.0.0";
+  }
+}
+async function fetchLatestVersion() {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3e3);
+    const res = await fetch(
+      `https://registry.npmjs.org/${PKG_NAME}/latest`,
+      { signal: controller.signal }
+    );
+    clearTimeout(timeout);
+    if (!res.ok) return null;
+    const data = await res.json();
+    return data.version ?? null;
+  } catch {
+    return null;
+  }
+}
+function isNewer(latest, current) {
+  const a = latest.split(".").map(Number);
+  const b = current.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((a[i] ?? 0) > (b[i] ?? 0)) return true;
+    if ((a[i] ?? 0) < (b[i] ?? 0)) return false;
+  }
+  return false;
+}
+async function checkForUpdate(opts = {}) {
+  const current = getCurrentVersion();
+  if (!opts.force) {
+    const cache = readCache();
+    if (cache && Date.now() - cache.checkedAt < CHECK_INTERVAL_MS) {
+      return {
+        current,
+        latest: cache.latest,
+        updateAvailable: isNewer(cache.latest, current)
+      };
+    }
+  }
+  const latest = await fetchLatestVersion();
+  if (latest) {
+    writeCache({ latest, checkedAt: Date.now() });
+  }
+  return {
+    current,
+    latest,
+    updateAvailable: latest ? isNewer(latest, current) : false
+  };
+}
+async function printUpdateHint() {
+  try {
+    const info2 = await checkForUpdate();
+    if (info2.updateAvailable && info2.latest) {
+      console.error(
+        chalk2.yellow(
+          `
+  Update available: ${info2.current} \u2192 ${info2.latest}  Run ${chalk2.bold("caik upgrade")} to update
+`
+        )
+      );
+    }
+  } catch {
+  }
+}
+
+// src/commands/upgrade.ts
+function registerUpgradeCommand(program2) {
+  program2.command("upgrade").description("Upgrade the CAIK CLI to the latest version").action(async () => {
+    const spinner = createSpinner("Checking for updates...");
+    spinner.start();
+    const update = await checkForUpdate({ force: true });
+    if (!update.latest) {
+      spinner.stop();
+      console.log(error("Could not determine the latest version. Check your network connection."));
+      return;
+    }
+    if (!update.updateAvailable) {
+      spinner.stop();
+      console.log(success(`Already on the latest version (${update.current})`));
+      return;
+    }
+    spinner.text = `Upgrading ${update.current} \u2192 ${update.latest}...`;
+    try {
+      execSync5("npm install -g @caik.dev/cli@latest", {
+        stdio: "pipe",
+        timeout: 6e4
+      });
+      spinner.stop();
+      console.log(success(`Upgraded to ${update.latest}`));
+    } catch (err) {
+      spinner.stop();
+      console.log(error("Upgrade failed. Try manually:"));
+      console.log(info("npm install -g @caik.dev/cli@latest"));
+    }
+  });
+}
+
 // src/index.ts
 var __filename = fileURLToPath(import.meta.url);
 var __dirname = dirname5(__filename);
 var version = "0.0.1";
 try {
-  const pkgPath = join8(__dirname, "..", "package.json");
-  const pkg = JSON.parse(readFileSync8(pkgPath, "utf-8"));
+  const pkgPath = join9(__dirname, "..", "package.json");
+  const pkg = JSON.parse(readFileSync9(pkgPath, "utf-8"));
   version = pkg.version;
 } catch {
 }
@@ -2601,15 +3203,17 @@ registerUninstallCommand(program);
 registerKarmaCommand(program);
 registerHookCommand(program);
 registerSetupCommand(program);
+registerUpgradeCommand(program);
 program.exitOverride();
 async function main() {
+  const updateHint = printUpdateHint();
   try {
     await program.parseAsync(process.argv);
   } catch (err) {
     if (err instanceof CaikError) {
-      console.error(chalk2.red(`\u2717 ${err.message}`));
+      console.error(chalk3.red(`\u2717 ${err.message}`));
       if (err.suggestion) {
-        console.error(chalk2.dim(`  ${err.suggestion}`));
+        console.error(chalk3.dim(`  ${err.suggestion}`));
       }
       process.exit(err.exitCode);
     }
@@ -2617,8 +3221,9 @@ async function main() {
       const exitCode = err.exitCode;
       process.exit(exitCode);
     }
-    console.error(chalk2.red(`\u2717 Unexpected error: ${err instanceof Error ? err.message : String(err)}`));
+    console.error(chalk3.red(`\u2717 Unexpected error: ${err instanceof Error ? err.message : String(err)}`));
     process.exit(1);
   }
+  await updateHint;
 }
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caik.dev/cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "description": "CAIK CLI — Search, install, and publish AI artifacts from your terminal",
   "keywords": [