@aliyunrds/ctxdb 0.0.4 → 0.0.7

package/dist/cli/main.js

@@ -1,29 +1,46 @@
 #!/usr/bin/env node
+import {
+  DEFAULT_FILE_INGEST_TIMEOUT_MS,
+  DEFAULT_INGEST_TIMEOUT_MS,
+  compactChunk,
+  compactKbQueryResponse,
+  createKb,
+  getDocument,
+  listDocuments,
+  listKnowledgeBases,
+  minimalChunk,
+  minimalKbQueryResponse,
+  pollIngest,
+  uploadFile,
+  uploadText
+} from "../chunk-6S5RJYBC.js";
 import {
   DEFAULT_BASE_URL,
   DEFAULT_USER_ID,
   HttpClient,
-  NotFoundError,
   SUPPORTED_AGENTS,
   agentFromEnv,
   agentHomeDir,
   configuredAgents,
-  isAgent,
+  isAgentSlug,
+  isBuiltinAgent,
   isComplete,
   load,
   removeAgent,
-  save
-} from "../chunk-QSSNPN3M.js";
+  save,
+  writeInstalledPkgVersion
+} from "../chunk-S45GOYUU.js";
 
 // src/cli/util.ts
 var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   // universal
   "json",
+  "help",
+  "h",
   // setup / init
   "no-install-skill",
   "no-validate",
-  "remove",
-  // teardown
+  // uninstall
   "purge-config",
   "purge-logs",
   "purge-all",
@@ -108,9 +125,9 @@ function isStatusResult(v) {
   if (typeof v !== "object" || v === null) return false;
   return "agent" in v && "connected" in v;
 }
-function formatSetupResult(r) {
+function formatSetupResult(r, command = "setup") {
   const lines = [];
-  lines.push(`${r.ok ? CHECK : CROSS} ${BOLD}ctxdb setup${RESET} ${r.ok ? "completed" : "failed"}
+  lines.push(`${r.ok ? CHECK : CROSS} ${BOLD}ctxdb ${command}${RESET} ${r.ok ? "completed" : "failed"}
 `);
   for (const s of r.steps) {
     const icon = s.ok ? CHECK : CROSS;
@@ -160,13 +177,13 @@ function formatStatusResult(r) {
   }
   return lines.join("\n");
 }
-function printResult(value, json) {
+function printResult(value, json, command) {
   if (json) {
     process.stdout.write(JSON.stringify(value, null, 2) + "\n");
   } else if (isUpgradeResult(value)) {
     process.stdout.write(formatUpgradeResult(value) + "\n");
   } else if (isSetupResult(value)) {
-    process.stdout.write(formatSetupResult(value) + "\n");
+    process.stdout.write(formatSetupResult(value, command ?? "setup") + "\n");
   } else if (isStatusResult(value)) {
     process.stdout.write(formatStatusResult(value) + "\n");
   } else {
@@ -176,17 +193,16 @@ function printResult(value, json) {
 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({
@@ -200,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 {
@@ -221,7 +237,7 @@ import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { execFileSync } from "child_process";
 var UNINSTALL_NPM_HINT = "To also remove the npm binaries: `npm uninstall -g @aliyunrds/ctxdb @aliyunrds/ctxdb-shared`";
-var UNINSTALL_ORDER_HINT = "When you eventually want to uninstall: run `ctxdb teardown --purge-all` FIRST, then `npm uninstall -g @aliyunrds/ctxdb @aliyunrds/ctxdb-shared`. (npm 7+ removed uninstall lifecycle hooks, so the order matters \u2014 otherwise agent settings.json hooks + ~/.ctxdb/ residue stay behind.)";
+var UNINSTALL_ORDER_HINT = "When you eventually want to uninstall: run `ctxdb uninstall --purge-all` FIRST, then `npm uninstall -g @aliyunrds/ctxdb @aliyunrds/ctxdb-shared`. (npm 7+ removed uninstall lifecycle hooks, so the order matters \u2014 otherwise agent settings.json hooks + ~/.ctxdb/ residue stay behind.)";
 function skillInstallRoot(agent) {
   switch (agent) {
     case "qoder":
@@ -232,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) {
@@ -260,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",
@@ -390,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({
@@ -435,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 {
@@ -454,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, {
@@ -530,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)) {
@@ -811,6 +802,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;
@@ -1065,7 +1094,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,
@@ -1097,24 +1126,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) {
@@ -1157,46 +1181,6 @@ function upgradeOneAgent(agent) {
 }
 
 // src/cli/top.ts
-import { homedir as homedir2 } from "os";
-import { join as join2 } from "path";
-async function init(args) {
-  const agent = agentFromFlags(args.flags);
-  const cfg = load({ agent });
-  if (typeof args.flags["api-key"] === "string") cfg.apiKey = args.flags["api-key"];
-  if (typeof args.flags["base-url"] === "string") {
-    cfg.baseUrl = args.flags["base-url"].replace(/\/+$/, "");
-  } else if (!cfg.baseUrl) {
-    cfg.baseUrl = DEFAULT_BASE_URL;
-  }
-  const cliUserId = typeof args.flags["user-id"] === "string" ? args.flags["user-id"] : void 0;
-  cfg.userId = cliUserId ?? cfg.userId ?? DEFAULT_USER_ID;
-  save(cfg, void 0, { agent });
-  let validated = false;
-  let pingError = null;
-  if (!args.flags["no-validate"] && cfg.apiKey) {
-    try {
-      const client = new HttpClient({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey });
-      await client.get("/v1/ping/");
-      validated = true;
-    } catch (err) {
-      pingError = err?.message ?? String(err);
-    }
-  }
-  printResult(
-    {
-      ok: true,
-      config_path: join2(homedir2(), ".ctxdb", "ctxdb.json"),
-      agent,
-      api_key_set: Boolean(cfg.apiKey),
-      base_url: cfg.baseUrl,
-      user_id: cfg.userId,
-      validated,
-      ping_error: pingError
-    },
-    !!args.flags.json
-  );
-  return 0;
-}
 async function status(args) {
   const agent = agentFromFlags(args.flags);
   const cfg = load({ agent });
@@ -1212,7 +1196,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,
@@ -1250,34 +1234,50 @@ 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 (args.flags.remove) {
-    const result2 = runRemove(agent);
-    printResult(result2, json);
-    if (!json && result2.hints) {
-      for (const h of result2.hints) process.stderr.write(`
-${h}
-`);
-    }
-    return result2.ok ? 0 : 1;
+  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,
@@ -1297,14 +1297,61 @@ ${h}
 }
 
 // src/cli/teardown.ts
-function teardown(args) {
+var HELP2 = `ctxdb uninstall \u2014 remove hooks + skills
+
+USAGE
+  ctxdb uninstall [--agent <qoder|codex|claude>] [--purge-config] [--purge-logs] [--purge-all] [--json]
+
+DEFAULT BEHAVIOR (no --agent, no purge flags)
+  Strips ctxdb hook entries and skill directories for ALL agents (qoder,
+  codex, claude). Keeps ~/.ctxdb/ctxdb.json (credentials) and ~/.ctxdb/logs/
+  so you can re-run \`ctxdb setup\` later without losing configuration.
+
+WITH --agent <name>
+  Only removes hooks + skill + config section for the specified agent.
+  Other agents remain untouched.
+
+FLAGS
+  --agent <name>   Target a single agent (qoder|codex|claude)
+  --purge-config   Also delete ~/.ctxdb/ctxdb.json
+  --purge-logs     Also delete ~/.ctxdb/logs/
+  --purge-all      Delete everything under ~/.ctxdb/
+  --json           Machine-readable JSON output
+
+NOTE
+  Does not run \`npm uninstall\`. After uninstall completes, remove the
+  npm package separately: npm uninstall -g @aliyunrds/ctxdb @aliyunrds/ctxdb-shared
+`;
+function uninstall(args) {
+  if (args.flags.help || args.flags.h) {
+    process.stdout.write(HELP2);
+    return 0;
+  }
+  const json = !!args.flags.json;
+  const agentFlag = args.flags.agent;
+  if (agentFlag !== void 0) {
+    if (!isAgentSlug(agentFlag)) {
+      process.stderr.write(
+        `unknown --agent: ${String(agentFlag)} (expected one of ${SUPPORTED_AGENTS.join(" / ")} / default)
+`
+      );
+      return 2;
+    }
+    const result2 = runRemove(agentFlag);
+    printResult(result2, json, `uninstall --agent ${agentFlag}`);
+    if (!json && result2.hints) {
+      for (const h of result2.hints) process.stderr.write(`
+${h}
+`);
+    }
+    return result2.ok ? 0 : 1;
+  }
   const result = runTeardown({
     purgeConfig: !!args.flags["purge-config"],
     purgeLogs: !!args.flags["purge-logs"],
     purgeAll: !!args.flags["purge-all"]
   });
-  const json = !!args.flags.json;
-  printResult(result, json);
+  printResult(result, json, "uninstall");
   if (!json && result.hints) {
     for (const h of result.hints) process.stderr.write(`
 ${h}
@@ -1313,10 +1360,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(" / ")})
 `
@@ -1324,6 +1506,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) {
@@ -1334,238 +1522,69 @@ ${h}
   return result.ok ? 0 : 1;
 }
 
-// src/lib/kb.ts
-import { readFileSync as readFileSync2, existsSync as existsSync2, statSync as statSync2 } from "fs";
-import { basename, extname } from "path";
-import { homedir as homedir3 } from "os";
-import { resolve } from "path";
-var KB_COLLECTION = "/v1/knowledge/knowledge_bases";
-var DOCUMENTS = "/v1/knowledge/documents";
-var FILES = "/v1/knowledge/files";
-var DOCUMENT_DETAIL = "/v1/knowledge/documents/detail";
-async function tryNewThenLegacy(newPath, newCall, legacyCall) {
-  try {
-    return await newCall();
-  } catch (err) {
-    if (err instanceof NotFoundError && err.path === newPath) {
-      return legacyCall();
-    }
-    throw err;
-  }
-}
-var DEFAULT_POLL_INTERVAL_MS = 1500;
-var DEFAULT_INGEST_TIMEOUT_MS = 3e4;
-var DEFAULT_FILE_INGEST_TIMEOUT_MS = 6e4;
-var MIME_BY_EXT = {
-  ".pdf": "application/pdf",
-  ".txt": "text/plain",
-  ".md": "text/markdown",
-  ".markdown": "text/markdown",
-  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-  ".doc": "application/msword",
-  ".html": "text/html",
-  ".htm": "text/html",
-  ".json": "application/json",
-  ".csv": "text/csv",
-  ".xml": "application/xml",
-  ".rtf": "application/rtf"
-};
-async function listKnowledgeBases(client) {
-  const resp = await client.get(KB_COLLECTION);
-  if (Array.isArray(resp)) return resp;
-  if (resp && typeof resp === "object") {
-    const o = resp;
-    return o.knowledge_bases ?? o.results ?? [];
+// 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;
   }
-  return [];
-}
-async function findKb(client, kbNameOrId) {
-  for (const kb of await listKnowledgeBases(client)) {
-    if (!kb || typeof kb !== "object") continue;
-    if (kb.name === kbNameOrId || kb.id === kbNameOrId) return kb;
+  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);
   }
-  return null;
-}
-async function createKb(client, kbName, description = "") {
-  return client.postJson(KB_COLLECTION, { name: kbName, description: description || "" });
-}
-async function findOrCreateKb(client, kbName, description = "") {
-  const existing = await findKb(client, kbName);
-  if (existing) return { kb: existing, created: false };
-  const created = await createKb(client, kbName, description);
-  return { kb: created, created: true };
-}
-async function uploadText(client, kbId, docName, text, mimeType = "text/plain", filePath) {
-  const body = {
-    knowledge_base_id: kbId,
-    name: docName,
-    text,
-    mime_type: mimeType
-  };
-  if (filePath !== void 0 && filePath !== "") body.file_path = filePath;
-  return tryNewThenLegacy(
-    DOCUMENTS,
-    () => client.postJson(DOCUMENTS, body),
-    () => {
-      const { knowledge_base_id: _drop, ...legacyBody } = body;
-      return client.postJson(`${KB_COLLECTION}/${encodeURIComponent(kbId)}/documents`, legacyBody);
-    }
-  );
-}
-async function uploadFile(client, kbId, localPath, options = {}) {
-  const MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
-  const expanded = expandHome(localPath);
-  if (!existsSync2(expanded)) throw new Error(`file not found: ${expanded}`);
-  const stat = statSync2(expanded);
-  if (!stat.isFile()) throw new Error(`not a file: ${expanded}`);
-  if (stat.size > MAX_UPLOAD_BYTES) {
-    throw new Error(
-      `file too large (${(stat.size / 1024 / 1024).toFixed(1)} MB), maximum is 100 MB`
-    );
+  if (!target && !customPath) {
+    process.stderr.write(HELP4);
+    return 2;
   }
-  const filename = basename(expanded);
-  const docName = options.docName ?? filename;
-  const content = readFileSync2(expanded);
-  const mime = guessMime(expanded);
-  const fields = {
-    knowledge_base_id: kbId,
-    name: docName
-  };
-  if (options.filePath !== void 0 && options.filePath !== "") {
-    fields.file_path = options.filePath;
-  }
-  const uploadOpts = { timeoutMs: options.timeoutMs };
-  return tryNewThenLegacy(
-    FILES,
-    () => client.postMultipart(
-      FILES,
-      fields,
-      { file: { filename, content, mimeType: mime } },
-      uploadOpts
-    ),
-    () => {
-      const { knowledge_base_id: _drop, ...legacyFields } = fields;
-      return client.postMultipart(
-        `${KB_COLLECTION}/${encodeURIComponent(kbId)}/files`,
-        legacyFields,
-        { file: { filename, content, mimeType: mime } },
-        uploadOpts
+  let targetRoot;
+  if (customPath) {
+    targetRoot = customPath;
+  } else {
+    const resolved = skillInstallTargetPath(target);
+    if (!resolved) {
+      fail(
+        `unknown --target: ${target} (supported: ${SUPPORTED_TARGETS.join(", ")})`,
+        2
       );
     }
-  );
-}
-function guessMime(path) {
-  const ext = extname(path).toLowerCase();
-  if (ext in MIME_BY_EXT) return MIME_BY_EXT[ext];
-  return "application/octet-stream";
-}
-async function getDocument(client, kbId, docId) {
-  return tryNewThenLegacy(
-    DOCUMENT_DETAIL,
-    () => client.get(DOCUMENT_DETAIL, {
-      knowledge_base_id: kbId,
-      document_id: docId
-    }),
-    () => client.get(
-      `${KB_COLLECTION}/${encodeURIComponent(kbId)}/documents/${encodeURIComponent(docId)}`
-    )
-  );
-}
-async function listDocuments(client, kbId) {
-  const resp = await tryNewThenLegacy(
-    DOCUMENTS,
-    () => client.get(DOCUMENTS, { knowledge_base_id: kbId }),
-    () => client.get(`${KB_COLLECTION}/${encodeURIComponent(kbId)}/documents`)
-  );
-  if (Array.isArray(resp)) return resp;
-  if (resp && typeof resp === "object") {
-    const o = resp;
-    return o.documents ?? o.results ?? [];
-  }
-  return [];
-}
-async function pollIngest(client, kbId, docId, options = {}) {
-  const timeoutMs = options.timeoutMs ?? DEFAULT_INGEST_TIMEOUT_MS;
-  const intervalMs = options.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
-  const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
-  const now = options.now ?? (() => performance.now());
-  const deadline = now() + timeoutMs;
-  let doc = await getDocument(client, kbId, docId);
-  let timedOut = false;
-  while (ingestInFlight(doc)) {
-    if (now() >= deadline) {
-      timedOut = true;
-      break;
-    }
-    await sleep(intervalMs);
-    try {
-      doc = await getDocument(client, kbId, docId);
-    } catch {
-      break;
-    }
-  }
-  if (doc && typeof doc === "object") {
-    return { ...doc, _pollingTimedOut: timedOut };
-  }
-  return { _pollingTimedOut: timedOut };
-}
-function ingestInFlight(doc) {
-  if (!doc || typeof doc !== "object") return false;
-  const status2 = doc.ingest_status;
-  return status2 === "processing" || status2 === "pending" || status2 === "in_progress";
-}
-function expandHome(p) {
-  if (p.startsWith("~/") || p === "~") {
-    return resolve(homedir3(), p.slice(2));
-  }
-  return resolve(p);
-}
-function compactChunk(raw) {
-  const c = raw ?? {};
-  const content = c.content_with_weight ?? c.content ?? c.chunk ?? c.text ?? "";
-  const doc_name = c.docnm_kwd ?? c.doc_name ?? c.docnm ?? "";
-  const kbRaw = c.kb_id ?? c.dataset_id;
-  const kb_id = Array.isArray(kbRaw) ? typeof kbRaw[0] === "string" ? kbRaw[0] : "" : typeof kbRaw === "string" ? kbRaw : "";
-  const docIdRaw = c.doc_id;
-  const scoreRaw = c.similarity ?? c.rerank_score;
-  const tagsRaw = c.tag_kwd;
-  const out = {
-    content,
-    doc_name,
-    kb_id,
-    score: typeof scoreRaw === "number" ? scoreRaw : 0
+    targetRoot = resolved;
+  }
+  const result = installSkillsTo(targetRoot);
+  const ok = result.ok;
+  const output = {
+    ok,
+    target: target ?? null,
+    path: targetRoot,
+    steps: result.steps
   };
-  if (typeof docIdRaw === "string" && docIdRaw.length > 0) {
-    out.doc_id = docIdRaw;
-  }
-  if (Array.isArray(tagsRaw) && tagsRaw.length > 0) {
-    out.tags = tagsRaw;
+  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 out;
-}
-function compactKbQueryResponse(raw) {
-  if (!raw || typeof raw !== "object") return { chunks: [] };
-  const r = raw;
-  const chunksIn = Array.isArray(r.chunks) ? r.chunks : [];
-  const out = {
-    chunks: chunksIn.map(compactChunk)
-  };
-  if (typeof r.total === "number") out.total = r.total;
-  return out;
-}
-function minimalChunk(raw) {
-  const c = compactChunk(raw);
-  return { content: c.content, score: c.score };
-}
-function minimalKbQueryResponse(raw) {
-  if (!raw || typeof raw !== "object") return { chunks: [] };
-  const r = raw;
-  const chunksIn = Array.isArray(r.chunks) ? r.chunks : [];
-  const out = {
-    chunks: chunksIn.map(minimalChunk)
-  };
-  if (typeof r.total === "number") out.total = r.total;
-  return out;
+  return ok ? 0 : 1;
 }
 
 // src/cli/memory.ts
@@ -1698,25 +1717,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) {
@@ -1727,23 +1741,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) {
@@ -1753,28 +1772,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) {
@@ -1785,16 +1800,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"]);
@@ -1811,31 +1820,32 @@ async function kbSearch(args) {
 }
 
 // src/cli/main.ts
-var HELP = `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
-  init [--agent <qoder|codex|claude>] [--api-key=K] [--base-url=URL] [--user-id=ID] [--no-validate]
-  status [--agent <qoder|codex|claude>] [--json]
-  ping [--agent <qoder|codex|claude>] [--json]
-  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] [--remove]
+        [--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
-  teardown [--purge-config] [--purge-logs] [--purge-all] [--json]
-                                 Removes hooks + skills for every agent.
+  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.
                                  --purge-config also deletes ~/.ctxdb/ctxdb.json.
                                  --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]
@@ -1849,13 +1859,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).
@@ -1864,19 +1875,33 @@ 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 = {
-  init,
+  setup,
   status,
   ping,
-  setup,
-  teardown,
+  uninstall,
+  teardown: uninstall,
   upgrade,
+  update: upgrade,
+  skill: {
+    install: skillInstall
+  },
   memory: {
     add: memoryAdd,
     search: memorySearch,
@@ -1886,6 +1911,7 @@ var ROUTES = {
     delete: memoryDelete
   },
   kb: {
+    create: kbCreate,
     "upload-text": kbUploadText,
     "upload-file": kbUploadFile,
     list: kbList,
@@ -1896,7 +1922,7 @@ var ROUTES = {
 };
 async function main(argv = process.argv.slice(2)) {
   if (argv.length === 0 || argv[0] === "-h" || argv[0] === "--help") {
-    process.stdout.write(HELP);
+    process.stdout.write(HELP5);
     return 0;
   }
   if (argv[0] === "-v" || argv[0] === "--version") {
@@ -1909,7 +1935,7 @@ async function main(argv = process.argv.slice(2)) {
   if (!route) {
     process.stderr.write(`unknown command: ${first}
 `);
-    process.stderr.write(HELP);
+    process.stderr.write(HELP5);
     return 2;
   }
   if (typeof route === "function") {
@@ -1922,6 +1948,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) {