@aliyunrds/ctxdb 0.0.5 → 0.0.8-beta.1

package/dist/cli/main.js

@@ -4,8 +4,7 @@ import {
   DEFAULT_INGEST_TIMEOUT_MS,
   compactChunk,
   compactKbQueryResponse,
-  findKb,
-  findOrCreateKb,
+  createKb,
   getDocument,
   listDocuments,
   listKnowledgeBases,
@@ -14,7 +13,7 @@ import {
   pollIngest,
   uploadFile,
   uploadText
-} from "../chunk-HAUTENYD.js";
+} from "../chunk-6S5RJYBC.js";
 import {
   DEFAULT_BASE_URL,
   DEFAULT_USER_ID,
@@ -23,12 +22,14 @@ import {
   agentFromEnv,
   agentHomeDir,
   configuredAgents,
-  isAgent,
+  isAgentSlug,
+  isBuiltinAgent,
   isComplete,
   load,
   removeAgent,
-  save
-} from "../chunk-QSSNPN3M.js";
+  save,
+  writeInstalledPkgVersion
+} from "../chunk-U3T5O6NX.js";
 
 // src/cli/util.ts
 var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
@@ -192,17 +193,16 @@ function printResult(value, json, command) {
 function agentFromFlags(flags) {
   const raw = flags.agent;
   if (raw === void 0) return agentFromEnv();
-  if (isAgent(raw)) return raw;
-  fail(`unknown --agent: ${String(raw)} (expected one of ${SUPPORTED_AGENTS.join(" / ")})`, 2);
+  if (isAgentSlug(raw)) return raw;
+  fail(`unknown --agent: ${String(raw)} (expected one of ${SUPPORTED_AGENTS.join(" / ")} / default)`, 2);
 }
 function buildContext(args) {
   const agent = agentFromFlags(args?.flags ?? {});
   const cfg = load({ agent });
   if (!isComplete(cfg)) {
-    process.stderr.write(
-      `config incomplete for agent ${agent}: run \`ctxdb setup --agent ${agent}\` or set CTXDB_API_KEY / CTXDB_BASE_URL / CTXDB_USER_ID env vars
-`
-    );
+    const hint = agent === "default" ? "run `ctxdb setup --api-key=<key> --base-url=<url>` or set CTXDB_API_KEY / CTXDB_BASE_URL env vars" : `run \`ctxdb setup --agent ${agent}\` or set CTXDB_API_KEY / CTXDB_BASE_URL / CTXDB_USER_ID env vars`;
+    process.stderr.write(`config incomplete for agent ${agent}: ${hint}
+`);
     process.exit(2);
   }
   const client = new HttpClient({
@@ -216,7 +216,7 @@ function fail(message, code = 1) {
 `);
   process.exit(code);
 }
-var PACKAGE_VERSION = "0.0.4";
+var PACKAGE_VERSION = "0.0.7";
 
 // src/setup/installer.ts
 import {
@@ -248,15 +248,10 @@ function skillInstallRoot(agent) {
       return join(homedir(), ".claude", "skills");
   }
 }
-var SKILL_DIR_NAME = "ctxdb";
-function skillResourceDir(agent) {
-  return agentSupportsHooks(agent) ? "hooks-driven" : "cli-only";
-}
-function skillInstallDir(agent) {
-  return join(skillInstallRoot(agent), SKILL_DIR_NAME);
-}
+var SKILL_DIRS = ["contextdb-memory", "contextdb-knowledge"];
+var LEGACY_SKILL_DIRS = ["ctxdb"];
 function agentSupportsHooks(agent) {
-  return agent === "qoder" || agent === "codex" || agent === "claude";
+  return isBuiltinAgent(agent);
 }
 function hookConfigPath(agent) {
   switch (agent) {
@@ -276,54 +271,48 @@ var LEGACY_QODER_SKILL_DIRS = [
 var HOOK_EVENTS = ["UserPromptSubmit", "Stop", "SessionStart"];
 async function runSetup(options) {
   const steps = [];
-  if (!isAgent(options.agent)) {
+  if (!isAgentSlug(options.agent)) {
     steps.push({
       step: "validate-agent",
       ok: false,
-      detail: `unknown --agent: ${String(options.agent)} (expected one of ${SUPPORTED_AGENTS.join(" / ")})`
+      detail: `unknown --agent: ${String(options.agent)} (expected one of ${SUPPORTED_AGENTS.join(" / ")} / default)`
     });
     return { ok: false, steps };
   }
   const agent = options.agent;
   const installSkill = options.installSkill !== false;
   const validate = options.validate !== false;
-  const homeCheck = checkAgentHome(agent);
-  steps.push(homeCheck);
-  if (!homeCheck.ok) return { ok: false, steps };
+  if (isBuiltinAgent(agent)) {
+    const homeCheck = checkAgentHome(agent);
+    steps.push(homeCheck);
+    if (!homeCheck.ok) return { ok: false, steps };
+  }
   const cfg = load({ agent });
   if (options.apiKey) cfg.apiKey = options.apiKey;
   if (options.baseUrl) cfg.baseUrl = options.baseUrl.replace(/\/+$/, "");
   else if (!cfg.baseUrl) cfg.baseUrl = DEFAULT_BASE_URL;
   cfg.userId = options.userId ?? cfg.userId ?? DEFAULT_USER_ID;
+  if (!cfg.apiKey) {
+    steps.push({
+      step: "write-config",
+      ok: false,
+      detail: `${agent}: --api-key is required (won't write config without a valid API key)`
+    });
+    return { ok: false, steps };
+  }
   save(cfg, void 0, { agent });
   steps.push({
     step: "write-config",
     ok: true,
     detail: `${agent}: ${cfg.baseUrl} (user_id=${cfg.userId})`
   });
-  if (installSkill) {
-    try {
-      const srcDir = locateSkillDir(skillResourceDir(agent));
-      if (srcDir) {
-        const dest = skillInstallDir(agent);
-        copySkillDir(srcDir, dest, agent);
-        steps.push({ step: "install-skill", ok: true, detail: dest });
-      } else {
-        steps.push({
-          step: "install-skill",
-          ok: false,
-          detail: `skill source directory not found (${skillResourceDir(agent)})`
-        });
-      }
-    } catch (err) {
-      steps.push({
-        step: "install-skill",
-        ok: false,
-        detail: err?.message ?? String(err)
-      });
-    }
+  if (installSkill && isBuiltinAgent(agent)) {
+    const installRoot = skillInstallRoot(agent);
+    const skillResult = installSkillsTo(installRoot, agent);
+    steps.push(...skillResult.steps);
+    if (!skillResult.ok) return { ok: false, steps };
   }
-  if (agentSupportsHooks(agent)) {
+  if (isBuiltinAgent(agent) && agentSupportsHooks(agent)) {
     const hookPaths = locateHookPaths();
     steps.push({
       step: "locate-hooks",
@@ -406,15 +395,15 @@ async function runSetup(options) {
 }
 function runRemove(agent, options = {}) {
   const steps = [];
-  if (!isAgent(agent)) {
+  if (!isAgentSlug(agent)) {
     steps.push({
       step: "validate-agent",
       ok: false,
-      detail: `unknown --agent: ${String(agent)} (expected one of ${SUPPORTED_AGENTS.join(" / ")})`
+      detail: `unknown --agent: ${String(agent)} (expected one of ${SUPPORTED_AGENTS.join(" / ")} / default)`
     });
     return { ok: false, steps };
   }
-  if (agentSupportsHooks(agent)) {
+  if (isBuiltinAgent(agent) && agentSupportsHooks(agent)) {
     const path = hookConfigPath(agent);
     if (!existsSync(path)) {
       steps.push({
@@ -451,12 +440,12 @@ function runRemove(agent, options = {}) {
         return { ok: false, steps };
       }
     }
-    const dirs = agent === "qoder" ? [
-      skillInstallDir("qoder"),
-      ...LEGACY_QODER_SKILL_DIRS.map(
-        (d) => join(homedir(), ".qoder", "skills", d)
-      )
-    ] : [skillInstallDir(agent)];
+    const root = skillInstallRoot(agent);
+    const dirs = [
+      ...SKILL_DIRS.map((d) => join(root, d)),
+      ...LEGACY_SKILL_DIRS.map((d) => join(root, d)),
+      ...agent === "qoder" ? LEGACY_QODER_SKILL_DIRS.map((d) => join(root, d)) : []
+    ];
     for (const p of dirs) {
       if (!existsSync(p)) continue;
       try {
@@ -470,26 +459,6 @@ function runRemove(agent, options = {}) {
         });
       }
     }
-  } else {
-    const dir = skillInstallDir(agent);
-    if (!existsSync(dir)) {
-      steps.push({
-        step: "skill-missing",
-        ok: true,
-        detail: `nothing to remove (${dir})`
-      });
-    } else {
-      try {
-        rmSync(dir, { recursive: true, force: true });
-        steps.push({ step: "remove-skill-dir", ok: true, detail: dir });
-      } catch (err) {
-        steps.push({
-          step: "remove-skill-dir",
-          ok: false,
-          detail: `${dir}: ${err?.message ?? String(err)}`
-        });
-      }
-    }
   }
   try {
     const r = removeAgent(agent, void 0, {
@@ -546,6 +515,12 @@ function runTeardown(options = {}) {
       steps.push({ ...s, step: `${agent}:${s.step}` });
     }
   }
+  const defaultSub = runRemove("default", { keepConfigShell });
+  if (defaultSub.steps.some((s) => s.step === "remove-config-section" && s.detail && !s.detail.includes("nothing to remove"))) {
+    for (const s of defaultSub.steps) {
+      steps.push({ ...s, step: `default:${s.step}` });
+    }
+  }
   if (purgeConfig) {
     const cfgPath = join(homedir(), ".ctxdb", "ctxdb.json");
     if (existsSync(cfgPath)) {
@@ -649,11 +624,15 @@ function checkHookNodePaths(agent) {
       if (!entryIsCtxdb(entry)) continue;
       for (const h of entry.hooks ?? []) {
         if (h?.type !== "command" || typeof h.command !== "string") continue;
-        const cmd = h.command;
-        if (cmd.includes("@aliyunrds/ctxdb")) {
-          const parts = cmd.split(" ");
-          if (parts.length >= 2 && !parts[0].endsWith(".js") && !parts[0].endsWith(".ts")) {
-            nodePaths.add(parts[0]);
+        if (Array.isArray(h.args) && h.args.length > 0) {
+          nodePaths.add(h.command);
+        } else {
+          const cmd = h.command;
+          if (cmd.includes("@aliyunrds/ctxdb")) {
+            const parts = cmd.split(" ");
+            if (parts.length >= 2 && !parts[0].endsWith(".js") && !parts[0].endsWith(".ts")) {
+              nodePaths.add(parts[0]);
+            }
           }
         }
       }
@@ -827,6 +806,44 @@ function copySkillDir(src, dest, agent) {
     }
   }
 }
+var SKILL_INSTALL_TARGETS = {
+  qoder: join(homedir(), ".qoder", "skills"),
+  codex: join(homedir(), ".codex", "skills"),
+  claude: join(homedir(), ".claude", "skills"),
+  openclaw: join(homedir(), ".openclaw", "skills"),
+  hermes: join(homedir(), ".hermes", "skills")
+};
+function skillInstallTargetPath(target) {
+  return SKILL_INSTALL_TARGETS[target] ?? null;
+}
+function installSkillsTo(targetRoot, agent = "default") {
+  const steps = [];
+  for (const skillName of SKILL_DIRS) {
+    try {
+      const srcDir = locateSkillDir(skillName);
+      if (srcDir) {
+        const dest = join(targetRoot, skillName);
+        copySkillDir(srcDir, dest, agent);
+        steps.push({ step: "install-skill", ok: true, detail: dest });
+      } else {
+        steps.push({
+          step: "install-skill",
+          ok: false,
+          detail: `skill source directory not found (${skillName})`
+        });
+        return { ok: false, steps };
+      }
+    } catch (err) {
+      steps.push({
+        step: "install-skill",
+        ok: false,
+        detail: err?.message ?? String(err)
+      });
+      return { ok: false, steps };
+    }
+  }
+  return { ok: true, steps };
+}
 function appendHooks(agent, hookPaths) {
   const path = hookConfigPath(agent);
   if (!path) return;
@@ -852,16 +869,15 @@ var LEGACY_MARKER_KEYS = ["_ctxdbQoder", "_ctxdbPackage"];
 var LEGACY_MARKER_VALUES = ["@aliyunrds/ctxdb-qoder"];
 var TOOL_SCOPED_EVENTS = /* @__PURE__ */ new Set(["PreToolUse", "PostToolUse"]);
 function appendOne(hooks, event, command, agent) {
-  const commandWithAgent = `${process.execPath} ${command} --agent=${agent}`;
   if (!Array.isArray(hooks[event])) hooks[event] = [];
   const dup = hooks[event].some(
     (entry2) => Array.isArray(entry2?.hooks) && entry2.hooks.some(
-      (h) => h?.type === "command" && typeof h.command === "string" && h.command === commandWithAgent
+      (h) => h?.type === "command" && Array.isArray(h.args) && h.args[0] === command
     )
   );
   if (dup) return;
   const entry = {
-    hooks: [{ type: "command", command: commandWithAgent, timeout: 60 }],
+    hooks: [{ type: "command", command: process.execPath, args: [command, `--agent=${agent}`], timeout: 60 }],
     [ENTRY_MARKER_KEY]: ENTRY_MARKER_VALUE,
     [ENTRY_AGENT_KEY]: agent
   };
@@ -1081,7 +1097,7 @@ function describeCodexFeatureMutation(status2, createdNew) {
   }
 }
 function runUpgrade(options = {}) {
-  const agents = options.agent ? [options.agent] : configuredAgents(options.configPath);
+  const agents = options.agent ? [options.agent] : configuredAgents(options.configPath).filter(isBuiltinAgent);
   if (agents.length === 0) {
     return {
       ok: false,
@@ -1113,24 +1129,19 @@ function upgradeOneAgent(agent) {
   if (!homeCheck.ok) {
     return { ok: true, steps, hints: [`${agent}: skipped \u2014 agent home not found`] };
   }
-  try {
-    const srcDir = locateSkillDir(skillResourceDir(agent));
-    if (srcDir) {
-      const dest = skillInstallDir(agent);
-      copySkillDir(srcDir, dest, agent);
-      steps.push({ step: "install-skill", ok: true, detail: dest });
-    } else {
-      steps.push({
-        step: "install-skill",
-        ok: false,
-        detail: "skill source directory not found"
-      });
-      return { ok: false, steps };
+  const root = skillInstallRoot(agent);
+  for (const legacy of LEGACY_SKILL_DIRS) {
+    const legacyDir = join(root, legacy);
+    if (!existsSync(legacyDir)) continue;
+    try {
+      rmSync(legacyDir, { recursive: true, force: true });
+      steps.push({ step: "remove-legacy-skill", ok: true, detail: legacyDir });
+    } catch {
     }
-  } catch (err) {
-    steps.push({ step: "install-skill", ok: false, detail: err?.message ?? String(err) });
-    return { ok: false, steps };
   }
+  const skillResult = installSkillsTo(root, agent);
+  steps.push(...skillResult.steps);
+  if (!skillResult.ok) return { ok: false, steps };
   if (agentSupportsHooks(agent)) {
     const hookPaths = locateHookPaths();
     if (!hookPaths) {
@@ -1188,7 +1199,7 @@ async function status(args) {
       pingError = err?.message ?? String(err);
     }
   }
-  const hookHealth = checkHookNodePaths(agent);
+  const hookHealth = isBuiltinAgent(agent) ? checkHookNodePaths(agent) : { installed: false, nodePaths: [], nodeOk: true, detail: "no hooks (default agent)" };
   printResult(
     {
       ok: complete,
@@ -1226,25 +1237,51 @@ async function ping(args) {
 }
 
 // src/cli/setup-cli.ts
+var HELP = `ctxdb setup \u2014 configure an agent
+
+USAGE
+  ctxdb setup [--agent <qoder|codex|claude>]
+              [--api-key=K] [--base-url=URL] [--user-id=ID]
+              [--no-install-skill] [--no-validate] [--json]
+
+BEHAVIOR
+  Without --agent  Writes agents.default in ~/.ctxdb/ctxdb.json (CLI-only,
+                   no hooks or skills installed).
+  With --agent     Writes agent config + installs hooks + skills for the
+                   specified agent harness.
+
+FLAGS
+  --agent <name>        Target agent (qoder|codex|claude)
+  --api-key <key>       API key (required on first setup)
+  --base-url <url>      Server URL (default: https://context-database.aliyuncs.com)
+  --user-id <id>        User bucket (default: "default")
+  --no-install-skill    Skip skill directory installation
+  --no-validate         Skip connectivity ping after setup
+  --json                Machine-readable JSON output
+`;
 function parseAgent(args) {
   const raw = args.flags.agent;
-  if (typeof raw !== "string") return null;
-  return SUPPORTED_AGENTS.includes(raw) ? raw : null;
-}
-function agentError() {
+  if (raw === void 0) return "default";
+  if (typeof raw === "string" && isAgentSlug(raw)) return raw;
   process.stderr.write(
-    `ctxdb setup: --agent <${SUPPORTED_AGENTS.join("|")}> is required
-  e.g. ctxdb setup --agent qoder --api-key=<key>
+    `unknown --agent: ${String(raw)} (expected one of ${SUPPORTED_AGENTS.join(" / ")} / default)
 `
   );
+  process.exit(2);
 }
 async function setup(args) {
-  const agent = parseAgent(args);
-  if (!agent) {
-    agentError();
-    return 2;
+  if (args.flags.help || args.flags.h) {
+    process.stdout.write(HELP);
+    return 0;
   }
+  const agent = parseAgent(args);
   const json = !!args.flags.json;
+  if (agent === "default" && !json && !configuredAgents().includes("default")) {
+    process.stderr.write(
+      `hint: creating CLI-only "default" agent (no hooks/skills). Use --agent <claude|qoder|codex> for full setup.
+`
+    );
+  }
   const result = await runSetup({
     agent,
     apiKey: typeof args.flags["api-key"] === "string" ? args.flags["api-key"] : void 0,
@@ -1263,7 +1300,7 @@ ${h}
 }
 
 // src/cli/teardown.ts
-var HELP = `ctxdb uninstall \u2014 remove hooks + skills
+var HELP2 = `ctxdb uninstall \u2014 remove hooks + skills
 
 USAGE
   ctxdb uninstall [--agent <qoder|codex|claude>] [--purge-config] [--purge-logs] [--purge-all] [--json]
@@ -1290,15 +1327,15 @@ NOTE
 `;
 function uninstall(args) {
   if (args.flags.help || args.flags.h) {
-    process.stdout.write(HELP);
+    process.stdout.write(HELP2);
     return 0;
   }
   const json = !!args.flags.json;
   const agentFlag = args.flags.agent;
   if (agentFlag !== void 0) {
-    if (!isAgent(agentFlag)) {
+    if (!isAgentSlug(agentFlag)) {
       process.stderr.write(
-        `unknown --agent: ${String(agentFlag)} (expected one of ${SUPPORTED_AGENTS.join(" / ")})
+        `unknown --agent: ${String(agentFlag)} (expected one of ${SUPPORTED_AGENTS.join(" / ")} / default)
 `
       );
       return 2;
@@ -1326,10 +1363,145 @@ ${h}
   return result.ok ? 0 : 1;
 }
 
+// src/lib/self-update.ts
+import { spawnSync } from "child_process";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { dirname as dirname2 } from "path";
+var PACKAGE_NAME = "@aliyunrds/ctxdb";
+var NPM_VIEW_TIMEOUT_MS = 1e4;
+function detectInstallMethod() {
+  const dir = dirname2(fileURLToPath2(import.meta.url));
+  return dir.includes("/node_modules/") ? "npm" : "unknown";
+}
+function checkLatestVersion(currentVersion) {
+  const result = spawnSync("npm", ["view", PACKAGE_NAME, "version"], {
+    encoding: "utf-8",
+    timeout: NPM_VIEW_TIMEOUT_MS,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  if (result.status !== 0 || !result.stdout?.trim()) {
+    return {
+      latest: null,
+      current: currentVersion,
+      isNewer: false,
+      error: result.stderr?.trim() || `npm view exited with code ${result.status}`
+    };
+  }
+  const latest = result.stdout.trim();
+  return {
+    latest,
+    current: currentVersion,
+    isNewer: isNewerVersion(latest, currentVersion)
+  };
+}
+function isNewerVersion(candidate, current) {
+  const parse = (v) => v.replace(/^v/, "").split(".").map(Number);
+  const [cMaj = 0, cMin = 0, cPat = 0] = parse(candidate);
+  const [uMaj = 0, uMin = 0, uPat = 0] = parse(current);
+  if (cMaj !== uMaj) return cMaj > uMaj;
+  if (cMin !== uMin) return cMin > uMin;
+  return cPat > uPat;
+}
+function runSelfUpdate(currentVersion, passthroughArgs = []) {
+  const method = detectInstallMethod();
+  if (method !== "npm") {
+    return {
+      ok: false,
+      updated: false,
+      fromVersion: currentVersion,
+      error: "ctxdb was not installed via npm. Update manually with your package manager."
+    };
+  }
+  const check = checkLatestVersion(currentVersion);
+  if (check.error) {
+    process.stderr.write(`ctxdb: npm view failed (${check.error}), skipping self-update
+`);
+    return { ok: true, updated: false, fromVersion: currentVersion };
+  }
+  if (!check.isNewer) {
+    process.stderr.write(`ctxdb: package already up to date (v${currentVersion})
+`);
+    return { ok: true, updated: false, fromVersion: currentVersion };
+  }
+  process.stderr.write(`ctxdb: updating ${PACKAGE_NAME} v${currentVersion} \u2192 v${check.latest}...
+`);
+  const install = spawnSync("npm", ["install", "-g", `${PACKAGE_NAME}@${check.latest}`], {
+    stdio: "inherit",
+    encoding: "utf-8"
+  });
+  if (install.status !== 0) {
+    return {
+      ok: false,
+      updated: false,
+      fromVersion: currentVersion,
+      error: `npm install -g failed with exit code ${install.status}`
+    };
+  }
+  process.stderr.write(`ctxdb: package updated to v${check.latest}, refreshing skills/hooks...
+`);
+  const upgradeArgs = ["upgrade", ...passthroughArgs];
+  const refresh = spawnSync("ctxdb", upgradeArgs, {
+    stdio: "inherit",
+    encoding: "utf-8"
+  });
+  return {
+    ok: refresh.status === 0,
+    updated: true,
+    fromVersion: currentVersion,
+    toVersion: check.latest,
+    error: refresh.status !== 0 ? `ctxdb upgrade exited with code ${refresh.status}` : void 0
+  };
+}
+
 // src/cli/upgrade.ts
+var HELP3 = `ctxdb upgrade \u2014 refresh skills + hooks
+
+USAGE
+  ctxdb upgrade [--agent <qoder|codex|claude>] [--self-update] [--json]
+
+BEHAVIOR
+  Refreshes skill files and hook entries for configured agents without
+  touching credentials. Designed for the post-npm-update path.
+
+  Without --agent: upgrades all configured built-in agents.
+  With --agent:    upgrades only the specified agent.
+
+FLAGS
+  --agent <name>   Target a single agent (qoder|codex|claude)
+  --self-update    Also pull latest package from npm before upgrading
+  --json           Machine-readable JSON output
+`;
 function upgrade(args) {
+  if (args.flags.help || args.flags.h) {
+    process.stdout.write(HELP3);
+    return 0;
+  }
+  const selfUpdate = !!args.flags["self-update"];
+  if (selfUpdate) {
+    const passthrough = [];
+    const agentFlag2 = args.flags.agent;
+    if (agentFlag2) passthrough.push("--agent", agentFlag2);
+    if (args.flags.json) passthrough.push("--json");
+    const result2 = runSelfUpdate(PACKAGE_VERSION, passthrough);
+    if (!result2.ok) {
+      if (args.flags.json) {
+        process.stdout.write(JSON.stringify({ ok: false, error: result2.error }) + "\n");
+      } else {
+        process.stderr.write(`ctxdb: self-update failed: ${result2.error}
+`);
+      }
+      return 1;
+    }
+    if (result2.updated) {
+      return 0;
+    }
+  }
   const agentFlag = args.flags.agent;
-  if (agentFlag && !isAgent(agentFlag)) {
+  if (agentFlag === "default") {
+    process.stderr.write("nothing to upgrade for default agent (no hooks or skills)\n");
+    return 0;
+  }
+  if (agentFlag && !isBuiltinAgent(agentFlag)) {
     process.stderr.write(
       `unknown --agent: ${agentFlag} (expected one of ${SUPPORTED_AGENTS.join(" / ")})
 `
@@ -1337,6 +1509,12 @@ function upgrade(args) {
     return 2;
   }
   const result = runUpgrade({ agent: agentFlag });
+  if (result.ok) {
+    try {
+      writeInstalledPkgVersion(PACKAGE_VERSION);
+    } catch {
+    }
+  }
   const json = !!args.flags.json;
   printResult(result, json);
   if (!json && result.hints) {
@@ -1347,6 +1525,71 @@ ${h}
   return result.ok ? 0 : 1;
 }
 
+// src/cli/skill-cli.ts
+var SUPPORTED_TARGETS = Object.keys(SKILL_INSTALL_TARGETS);
+var HELP4 = `ctxdb skill install \u2014 install skill files to an agent's skill directory
+
+USAGE
+  ctxdb skill install --target <name>
+  ctxdb skill install --path <dir>
+
+TARGETS
+  ${SUPPORTED_TARGETS.join(", ")}
+
+FLAGS
+  --target <name>   Install to a built-in agent's skill directory
+  --path <dir>      Install to a custom directory
+  --json            Machine-readable JSON output
+
+Note: This command only installs skill files (contextdb, contextdb-memory,
+contextdb-knowledge). It does not write config or install hooks.
+To configure server connection, run: ctxdb setup --api-key=<key> --base-url=<url>
+`;
+function skillInstall(args) {
+  if (args.flags.help || args.flags.h) {
+    process.stdout.write(HELP4);
+    return 0;
+  }
+  const json = !!args.flags.json;
+  const target = args.flags.target;
+  const customPath = args.flags.path;
+  if (target && customPath) {
+    fail("--target and --path are mutually exclusive", 2);
+  }
+  if (!target && !customPath) {
+    process.stderr.write(HELP4);
+    return 2;
+  }
+  let targetRoot;
+  if (customPath) {
+    targetRoot = customPath;
+  } else {
+    const resolved = skillInstallTargetPath(target);
+    if (!resolved) {
+      fail(
+        `unknown --target: ${target} (supported: ${SUPPORTED_TARGETS.join(", ")})`,
+        2
+      );
+    }
+    targetRoot = resolved;
+  }
+  const result = installSkillsTo(targetRoot);
+  const ok = result.ok;
+  const output = {
+    ok,
+    target: target ?? null,
+    path: targetRoot,
+    steps: result.steps
+  };
+  printResult(output, json);
+  if (ok && !json) {
+    process.stderr.write(
+      "\nNote: This command only installs skill files.\nTo configure server connection, run:\n  ctxdb setup --api-key=<key> --base-url=<url>\n"
+    );
+  }
+  return ok ? 0 : 1;
+}
+
 // src/cli/memory.ts
 async function memoryAdd(args) {
   const text = args.positional[0];
@@ -1477,25 +1720,20 @@ async function kbUploadText(args) {
   const text = args.flags["text"];
   if (!kbName || !docName || typeof text !== "string") {
     fail(
-      "usage: ctxdb kb upload-text <kb-name> <doc-name> --text=<body> [--kb-description=...] [--file-path=<server-logical-path>] [--no-wait]"
+      "usage: ctxdb kb upload-text <kb-name> <doc-name> --text=<body> [--file-path=<server-logical-path>] [--no-wait]"
     );
   }
   const ctx = buildContext(args);
-  const description = args.flags["kb-description"] ?? "";
   const filePath = typeof args.flags["file-path"] === "string" ? args.flags["file-path"] : void 0;
-  const { kb, created } = await findOrCreateKb(ctx.client, kbName, description);
-  const doc = await uploadText(ctx.client, kb.id, docName, text, "text/plain", filePath);
+  const doc = await uploadText(ctx.client, kbName, docName, text, "text/plain", filePath);
   if (args.flags["no-wait"]) {
-    printResult({ kb, kb_created: created, document: doc }, !!args.flags.json);
+    printResult({ document: doc }, !!args.flags.json);
     return 0;
   }
-  const final = await pollIngest(ctx.client, kb.id, doc.id, {
+  const final = await pollIngest(ctx.client, kbName, doc.id, {
     timeoutMs: DEFAULT_INGEST_TIMEOUT_MS
   });
-  printResult(
-    { kb, kb_created: created, document: final },
-    !!args.flags.json
-  );
+  printResult({ document: final }, !!args.flags.json);
   return 0;
 }
 async function kbUploadFile(args) {
@@ -1506,23 +1744,28 @@ async function kbUploadFile(args) {
     );
   }
   const ctx = buildContext(args);
-  const { kb, created } = await findOrCreateKb(ctx.client, kbName);
-  const doc = await uploadFile(ctx.client, kb.id, localPath, {
+  const doc = await uploadFile(ctx.client, kbName, localPath, {
     docName: typeof args.flags["doc-name"] === "string" ? args.flags["doc-name"] : void 0,
     filePath: typeof args.flags["file-path"] === "string" ? args.flags["file-path"] : void 0,
     timeoutMs: DEFAULT_FILE_INGEST_TIMEOUT_MS
   });
   if (args.flags["no-wait"]) {
-    printResult({ kb, kb_created: created, document: doc }, !!args.flags.json);
+    printResult({ document: doc }, !!args.flags.json);
     return 0;
   }
-  const final = await pollIngest(ctx.client, kb.id, doc.id, {
+  const final = await pollIngest(ctx.client, kbName, doc.id, {
     timeoutMs: DEFAULT_FILE_INGEST_TIMEOUT_MS
   });
-  printResult(
-    { kb, kb_created: created, document: final },
-    !!args.flags.json
-  );
+  printResult({ document: final }, !!args.flags.json);
+  return 0;
+}
+async function kbCreate(args) {
+  const kbName = args.positional[0];
+  if (!kbName) fail("usage: ctxdb kb create <kb-name> [--description=<desc>]");
+  const ctx = buildContext(args);
+  const description = typeof args.flags["description"] === "string" ? args.flags["description"] : "";
+  const kb = await createKb(ctx.client, kbName, description);
+  printResult(kb, !!args.flags.json);
   return 0;
 }
 async function kbList(args) {
@@ -1532,28 +1775,24 @@ async function kbList(args) {
   return 0;
 }
 async function kbDocumentsList(args) {
-  const kbNameOrId = args.positional[0];
-  if (!kbNameOrId) fail("usage: ctxdb kb documents-list <kb-name-or-id>");
+  const kbName = args.positional[0];
+  if (!kbName) fail("usage: ctxdb kb documents-list <kb-name>");
   const ctx = buildContext(args);
-  const kb = await findKb(ctx.client, kbNameOrId);
-  if (!kb) fail(`KB not found: ${kbNameOrId}`);
-  const docs = await listDocuments(ctx.client, kb.id);
+  const docs = await listDocuments(ctx.client, kbName);
   printResult(
-    { kb, documents: docs, count: docs.length },
+    { documents: docs, count: docs.length },
     !!args.flags.json
   );
   return 0;
 }
 async function kbDocumentGet(args) {
-  const [kbNameOrId, docId] = args.positional;
-  if (!kbNameOrId || !docId) {
-    fail("usage: ctxdb kb document-get <kb-name-or-id> <doc-id>");
+  const [kbName, docId] = args.positional;
+  if (!kbName || !docId) {
+    fail("usage: ctxdb kb document-get <kb-name> <doc-id>");
   }
   const ctx = buildContext(args);
-  const kb = await findKb(ctx.client, kbNameOrId);
-  if (!kb) fail(`KB not found: ${kbNameOrId}`);
-  const doc = await getDocument(ctx.client, kb.id, docId);
-  printResult({ kb, document: doc }, !!args.flags.json);
+  const doc = await getDocument(ctx.client, kbName, docId);
+  printResult({ document: doc }, !!args.flags.json);
   return 0;
 }
 async function kbSearch(args) {
@@ -1564,16 +1803,10 @@ async function kbSearch(args) {
     );
   }
   const ctx = buildContext(args);
-  const kbList2 = (typeof args.flags.kb === "string" ? args.flags.kb : "").split(",").map((s) => s.trim()).filter(Boolean);
-  const datasetIds = [];
-  for (const name of kbList2) {
-    const kb = await findKb(ctx.client, name);
-    if (!kb) fail(`KB not found: ${name}`);
-    datasetIds.push(kb.id);
-  }
+  const kbNames = (typeof args.flags.kb === "string" ? args.flags.kb : "").split(",").map((s) => s.trim()).filter(Boolean);
   const body = {
     question: query,
-    dataset_ids: datasetIds
+    knowledge_base_names: kbNames
   };
   if (typeof args.flags["top-k"] === "string") {
     const n = Number(args.flags["top-k"]);
@@ -1590,21 +1823,22 @@ async function kbSearch(args) {
 }
 
 // src/cli/main.ts
-var HELP2 = `ctxdb v${PACKAGE_VERSION} \u2014 RDS ContextDatabase CLI (multi-agent)
+var HELP5 = `ctxdb v${PACKAGE_VERSION} \u2014 RDS ContextDatabase CLI (multi-agent)
 
 USAGE
   ctxdb <command> [args] [--flags]
 
 COMMANDS
-  setup --agent <qoder|codex|claude>
+  setup [--agent <qoder|codex|claude>]
         [--api-key=K] [--base-url=URL] [--user-id=ID]
         [--no-install-skill] [--no-validate] [--json]
+                                 Without --agent \u2192 writes agents.default (CLI-only, no hooks/skills)
                                  Qoder    \u2192 writes agents.qoder config + ~/.qoder/settings.json hooks + skill
                                  Codex    \u2192 writes agents.codex config + ~/.codex/hooks.json hooks + skill
                                  Claude   \u2192 writes agents.claude config + ~/.claude/settings.json hooks + skill
-  status [--agent <qoder|codex|claude>] [--json]
-  ping [--agent <qoder|codex|claude>] [--json]
-  uninstall [--agent <qoder|codex|claude>] [--purge-config] [--purge-logs] [--purge-all] [--json]
+  status [--agent <name>] [--json]
+  ping [--agent <name>] [--json]
+  uninstall [--agent <name>] [--purge-config] [--purge-logs] [--purge-all] [--json]
   teardown                       (alias for uninstall)
                                  Without --agent: removes hooks + skills for every agent.
                                  With --agent: removes only that agent's hooks + skill + config section.
@@ -1612,10 +1846,9 @@ COMMANDS
                                  --purge-logs   also deletes ~/.ctxdb/logs/.
                                  --purge-all    deletes everything under ~/.ctxdb/
                                  (does not run npm uninstall).
-  upgrade [--agent <name>] [--json]
-                                 Refresh skills + hooks for configured agents.
-                                 Run after npm update -g @aliyunrds/ctxdb.
-                                 Does not modify credentials.
+  upgrade|update [--agent <name>] [--self-update] [--json]
+                                 Refresh skills + hooks. --self-update also
+                                 pulls latest package from npm.
 
   memory add <text> [--agent=<name>] [--user-id=...] [--metadata=K1=V1,K2=V2] [--no-infer]
   memory search <query> [--agent=<name>] [--top-k=10] [--threshold=0.4] [--knowledge]
@@ -1629,13 +1862,14 @@ COMMANDS
   memory update <memory-id> --text=<new-text> [--agent=<name>]
   memory delete <memory-id> | --all [--agent=<name>]
 
+  kb create <kb-name> [--description=<desc>] [--agent=<name>]
   kb upload-text <kb-name> <doc-name> --text=<body> [--agent=<name>]
-                 [--kb-description=...] [--file-path=<server-logical-path>] [--no-wait]
+                 [--file-path=<server-logical-path>] [--no-wait]
   kb upload-file <kb-name> <local-path> [--agent=<name>] [--doc-name=...]
                  [--file-path=<server-logical-path>] [--no-wait]
   kb list [--agent=<name>]
-  kb documents-list <kb-name-or-id> [--agent=<name>]
-  kb document-get <kb-name-or-id> <doc-id> [--agent=<name>]
+  kb documents-list <kb-name> [--agent=<name>]
+  kb document-get <kb-name> <doc-id> [--agent=<name>]
   kb search <query> [--agent=<name>] [--kb=name1,name2] [--top-k=N] [--threshold=F]
                     [--verbose] [--raw]
                                  Standalone KB recall (independent of memory).
@@ -1644,10 +1878,20 @@ COMMANDS
                                  doc_id?/tags? for citation.
                                  --raw: server response verbatim (curl parity).
 
+  skill install --target <qoder|codex|claude|openclaw|hermes> [--json]
+  skill install --path <dir> [--json]
+                                 Install skill files (contextdb-memory,
+                                 contextdb-knowledge) to an agent's skill directory.
+                                 Does not write config or install hooks.
+
+AGENT RESOLUTION (when --agent is omitted):
+  1. CTXDB_AGENT env var
+  2. agents.default section in ~/.ctxdb/ctxdb.json
+
 ENV VARS (override selected ~/.ctxdb/ctxdb.json agent config):
   CTXDB_AGENT  CTXDB_API_KEY  CTXDB_BASE_URL  CTXDB_USER_ID
 
-CONFIG: ~/.ctxdb/ctxdb.json (agents.qoder / agents.codex / agents.claude)
+CONFIG: ~/.ctxdb/ctxdb.json (agents.default / agents.qoder / agents.codex / agents.claude)
 LOGS:   ~/.ctxdb/logs/ctxdb.log
 `;
 var ROUTES = {
@@ -1657,6 +1901,10 @@ var ROUTES = {
   uninstall,
   teardown: uninstall,
   upgrade,
+  update: upgrade,
+  skill: {
+    install: skillInstall
+  },
   memory: {
     add: memoryAdd,
     search: memorySearch,
@@ -1666,6 +1914,7 @@ var ROUTES = {
     delete: memoryDelete
   },
   kb: {
+    create: kbCreate,
     "upload-text": kbUploadText,
     "upload-file": kbUploadFile,
     list: kbList,
@@ -1676,7 +1925,7 @@ var ROUTES = {
 };
 async function main(argv = process.argv.slice(2)) {
   if (argv.length === 0 || argv[0] === "-h" || argv[0] === "--help") {
-    process.stdout.write(HELP2);
+    process.stdout.write(HELP5);
     return 0;
   }
   if (argv[0] === "-v" || argv[0] === "--version") {
@@ -1689,7 +1938,7 @@ async function main(argv = process.argv.slice(2)) {
   if (!route) {
     process.stderr.write(`unknown command: ${first}
 `);
-    process.stderr.write(HELP2);
+    process.stderr.write(HELP5);
     return 2;
   }
   if (typeof route === "function") {
@@ -1702,6 +1951,13 @@ async function main(argv = process.argv.slice(2)) {
     );
     return 2;
   }
+  if (rest[0] === "-h" || rest[0] === "--help") {
+    process.stdout.write(
+      `usage: ctxdb ${first} <${Object.keys(route).join("|")}> ...
+`
+    );
+    return 0;
+  }
   const [sub, ...subRest] = rest;
   const handler = route[sub];
   if (!handler) {