@sma1lboy/kobe 0.7.2 → 0.7.3

package/dist/cli/index.js

@@ -70,7 +70,7 @@ var init_package = __esm(() => {
   package_default = {
     $schema: "https://json.schemastore.org/package.json",
     name: "@sma1lboy/kobe",
-    version: "0.7.2",
+    version: "0.7.3",
     description: "TUI orchestrator for Claude Code (codename)",
     type: "module",
     packageManager: "bun@1.3.13",
@@ -6327,32 +6327,74 @@ var init_worktree_changes = __esm(() => {
 // src/cli/api-cmd.ts
 var exports_api_cmd = {};
 __export(exports_api_cmd, {
+  verbSchema: () => verbSchema,
+  verbHelp: () => verbHelp,
+  validateAgainstSpec: () => validateAgainstSpec,
+  schemaIndex: () => schemaIndex,
   runApiSubcommand: () => runApiSubcommand,
   parseFlags: () => parseFlags,
   parseAgentsSpec: () => parseAgentsSpec,
+  fullSchema: () => fullSchema,
+  findVerb: () => findVerb,
   apiUsage: () => apiUsage,
+  VERB_GROUPS: () => VERB_GROUPS,
+  VERBS: () => VERBS,
   FANOUT_CAP: () => FANOUT_CAP,
   ApiError: () => ApiError,
-  API_VERBS: () => API_VERBS
+  API_VERBS: () => API_VERBS,
+  API_SCHEMA_VERSION: () => API_SCHEMA_VERSION
 });
 import { resolve as resolve4 } from "path";
-function parseFlags(argv) {
+function groupOf(verbName) {
+  for (const [group, names] of Object.entries(VERB_GROUPS)) {
+    if (names.includes(verbName))
+      return group;
+  }
+  return "other";
+}
+async function handleSchema(_client, parsed) {
+  const { flags } = parsed;
+  const verbName = optional(flags, "verb");
+  if (verbName) {
+    const v = findVerb(verbName);
+    if (!v)
+      throw new ApiError(`unknown verb: ${verbName}`, "BAD_VERB");
+    return verbSchema(v);
+  }
+  const group = optional(flags, "group");
+  if (group)
+    return groupSchema(group);
+  if (optionalBool(flags, "all"))
+    return fullSchema();
+  return schemaIndex();
+}
+function findVerb(name) {
+  const canonical = VERB_ALIASES[name] ?? name;
+  return VERBS.find((v) => v.name === canonical);
+}
+function parseFlags(argv, booleanFlags = new Set) {
   const flags = new Map;
   let pretty = false;
+  let help = false;
   for (let i = 0;i < argv.length; i++) {
     const arg = argv[i];
-    if (!arg.startsWith("--")) {
+    if (!arg.startsWith("--") && arg !== "-h") {
       throw new ApiError(`unexpected positional arg: ${arg}`, "BAD_FLAG");
     }
+    if (arg === "-h") {
+      help = true;
+      continue;
+    }
     const eq = arg.indexOf("=");
     if (eq !== -1) {
       const key2 = arg.slice(2, eq);
       const value = arg.slice(eq + 1);
-      if (key2 === "pretty") {
+      if (key2 === "pretty")
         pretty = value !== "false" && value !== "0";
-      } else {
+      else if (key2 === "help")
+        help = value !== "false" && value !== "0";
+      else
         flags.set(key2, value);
-      }
       continue;
     }
     const key = arg.slice(2);
@@ -6360,6 +6402,14 @@ function parseFlags(argv) {
       pretty = true;
       continue;
     }
+    if (key === "help") {
+      help = true;
+      continue;
+    }
+    if (booleanFlags.has(key)) {
+      flags.set(key, "true");
+      continue;
+    }
     const next = argv[i + 1];
     if (next === undefined || next.startsWith("--")) {
       throw new ApiError(`flag --${key} requires a value`, "BAD_FLAG");
@@ -6367,19 +6417,50 @@ function parseFlags(argv) {
     flags.set(key, next);
     i += 1;
   }
-  return { flags, pretty };
+  return { flags, pretty, help };
+}
+function validateAgainstSpec(verb, flags) {
+  const known = new Set(verb.flags.map((f) => f.name));
+  for (const key of flags.keys()) {
+    if (!known.has(key)) {
+      throw new ApiError(`unknown flag --${key} for "${verb.name}". Run \`kobe api ${verb.name} --help\``, "BAD_FLAG");
+    }
+  }
+  for (const f of verb.flags) {
+    if (f.required && !flags.get(f.name))
+      throw new ApiError(`--${f.name} is required for "${verb.name}"`, "MISSING_FLAG");
+    if (f.type === "enum" && f.values) {
+      const raw = flags.get(f.name);
+      if (raw !== undefined && !f.values.includes(raw)) {
+        throw new ApiError(`--${f.name} must be one of ${f.values.join(", ")}`, "BAD_FLAG");
+      }
+    }
+    if (f.type === "int") {
+      const raw = flags.get(f.name);
+      if (raw !== undefined) {
+        const n = Number.parseInt(raw, 10);
+        if (!Number.isInteger(n) || n <= 0)
+          throw new ApiError(`--${f.name} must be a positive integer`, "BAD_FLAG");
+      }
+    }
+  }
 }
 function required(flags, key) {
   const v = flags.get(key);
-  if (v === undefined || v.length === 0) {
+  if (v === undefined || v.length === 0)
     throw new ApiError(`--${key} is required`, "MISSING_FLAG");
-  }
   return v;
 }
 function optional(flags, key) {
   const v = flags.get(key);
   return v && v.length > 0 ? v : undefined;
 }
+function requireEnum(flags, key, values) {
+  const v = required(flags, key);
+  if (!values.includes(v))
+    throw new ApiError(`--${key} must be one of ${values.join(", ")}`, "BAD_FLAG");
+  return v;
+}
 function optionalVendor2(flags) {
   const raw = optional(flags, "vendor");
   if (raw === undefined)
@@ -6389,16 +6470,28 @@ function optionalVendor2(flags) {
   }
   return raw;
 }
+function optionalBool(flags, key) {
+  const raw = optional(flags, key);
+  if (raw === undefined)
+    return;
+  if (["true", "1", "yes"].includes(raw))
+    return true;
+  if (["false", "0", "no"].includes(raw))
+    return false;
+  throw new ApiError(`--${key} must be a boolean (true/false)`, "BAD_FLAG");
+}
 function optionalPositiveInt(flags, key) {
   const raw = optional(flags, key);
   if (raw === undefined)
     return;
   const n = Number.parseInt(raw, 10);
-  if (!Number.isInteger(n) || n <= 0) {
+  if (!Number.isInteger(n) || n <= 0)
     throw new ApiError(`--${key} must be a positive integer`, "BAD_FLAG");
-  }
   return n;
 }
+function resolveRepoFlag(repo) {
+  return resolve4(process.cwd(), repo);
+}
 function parseAgentsSpec(spec) {
   const out = [];
   for (const part of spec.split(",")) {
@@ -6423,19 +6516,102 @@ function parseAgentsSpec(spec) {
     throw new ApiError('--agents specified no agents (e.g. "claude:2,codex:1")', "BAD_FLAG");
   return out;
 }
+function flagJson(f) {
+  return {
+    name: f.name,
+    type: f.type,
+    required: f.required ?? false,
+    ...f.values ? { values: f.values } : {},
+    ...f.default !== undefined ? { default: f.default } : {},
+    ...f.placeholder ? { placeholder: f.placeholder } : {},
+    description: f.description
+  };
+}
+function verbSchema(v) {
+  return {
+    name: v.name,
+    group: groupOf(v.name),
+    summary: v.summary,
+    offline: v.offline ?? false,
+    flags: v.flags.map(flagJson)
+  };
+}
+function schemaIndex() {
+  return {
+    apiVersion: API_SCHEMA_VERSION,
+    kobeVersion: CURRENT_VERSION,
+    hint: "Compact index. Drill into ONE verb: `kobe api schema --verb <name>` (or `kobe api <verb> --help`). One group: `--group <g>`. Whole spec: `--all`.",
+    groups: VERB_GROUPS,
+    verbs: VERBS.map((v) => ({ name: v.name, group: groupOf(v.name), summary: v.summary })),
+    globalFlags: GLOBAL_FLAGS,
+    aliases: VERB_ALIASES
+  };
+}
+function groupSchema(group) {
+  const names = VERB_GROUPS[group];
+  if (!names) {
+    throw new ApiError(`unknown group: ${group}. Groups: ${Object.keys(VERB_GROUPS).join(", ")}`, "BAD_FLAG");
+  }
+  return {
+    group,
+    verbs: names.map((n) => {
+      const v = findVerb(n);
+      return { name: n, summary: v?.summary ?? "" };
+    })
+  };
+}
+function fullSchema() {
+  return {
+    apiVersion: API_SCHEMA_VERSION,
+    kobeVersion: CURRENT_VERSION,
+    output: {
+      success: "one JSON object on stdout, newline-terminated, exit 0",
+      error: '{"error":{"message","code"}} on stderr, exit != 0',
+      pretty: "--pretty indents stdout JSON"
+    },
+    globalFlags: GLOBAL_FLAGS,
+    aliases: VERB_ALIASES,
+    groups: VERB_GROUPS,
+    verbs: VERBS.map(verbSchema)
+  };
+}
+function flagSignature(verb) {
+  return verb.flags.map((f) => {
+    const meta = f.type === "enum" && f.values ? f.values.join("|") : f.placeholder ?? (f.type === "bool" ? "" : "X");
+    const core = meta ? `--${f.name} ${meta}` : `--${f.name}`;
+    return f.required ? core : `[${core}]`;
+  }).join(" ");
+}
+function verbHelp(verb) {
+  const lines = [`kobe api ${verb.name} ${flagSignature(verb)}`.trimEnd(), "", verb.summary, ""];
+  const alias = Object.entries(VERB_ALIASES).find(([, canon]) => canon === verb.name)?.[0];
+  if (alias)
+    lines.push(`Alias: ${alias}`, "");
+  if (verb.flags.length > 0) {
+    lines.push("Flags:");
+    for (const f of verb.flags) {
+      const req = f.required ? " (required)" : "";
+      const def = f.default !== undefined ? ` [default: ${f.default}]` : "";
+      const vals = f.type === "enum" && f.values ? ` {${f.values.join("|")}}` : "";
+      lines.push(`  --${f.name}${vals}${req}${def}  ${f.description}`);
+    }
+    lines.push("");
+  }
+  lines.push("Global: [--pretty] [--help]");
+  return lines.join(`
+`);
+}
 function apiUsage() {
+  const rows = VERBS.map((v) => `  ${v.name.padEnd(18)} ${v.summary}`);
   return [
-    "usage: kobe api <verb> [flags] [--pretty]",
+    "usage: kobe api <verb> [flags] [--pretty] [--help]",
+    "",
+    "Explore the full surface (names, flags, types) with:  kobe api schema",
     "",
     "verbs:",
-    "  spawn-task  --repo PATH [--prompt TEXT] [--title T] [--base-branch B] [--vendor V]",
-    "  fan-out     --repo PATH --prompt TEXT [--count N | --agents claude:2,codex:1] [--base-branch B]",
-    "  send        [--task-id ID] --prompt TEXT",
-    "  get-task    --task-id ID",
-    "  collect     --task-ids a,b,c | --repo PATH",
-    "  list",
+    ...rows,
     "",
-    "Output is one JSON object on stdout (exit 0); errors are JSON on stderr (exit \u2260 0)."
+    "Output is one JSON object on stdout (exit 0); errors are JSON on stderr (exit != 0)."
   ].join(`
 `);
 }
@@ -6492,12 +6668,22 @@ async function resolveActiveTaskId(client) {
   }
   return activeId;
 }
-async function spawnTask(client, parsed) {
+async function simpleRpc(client, name, payload) {
+  if (!client)
+    throw new ApiError("daemon required", "BAD_DAEMON");
+  return client.request(name, payload);
+}
+async function add(client, parsed) {
+  if (!client)
+    throw new ApiError("daemon required", "BAD_DAEMON");
   const { flags } = parsed;
-  const payload = { repo: required(flags, "repo") };
+  const payload = { repo: resolveRepoFlag(required(flags, "repo")) };
   const title = optional(flags, "title");
   if (title)
     payload.title = title;
+  const branch = optional(flags, "branch");
+  if (branch)
+    payload.branch = branch;
   const baseRef = optional(flags, "base-branch");
   if (baseRef)
     payload.baseRef = baseRef;
@@ -6505,25 +6691,26 @@ async function spawnTask(client, parsed) {
   if (vendor)
     payload.vendor = vendor;
   const res = await client.request("task.create", payload);
-  const prompt = optional(flags, "prompt");
-  if (!prompt) {
-    return { taskId: res.taskId, task: res.task, started: false };
+  const taskId = res.taskId;
+  const status = optional(flags, "status");
+  if (status)
+    await client.request("task.status", { taskId, status: requireEnum(flags, "status", TASK_STATUSES) });
+  const pin = optionalBool(flags, "pin");
+  if (pin !== undefined)
+    await client.request("task.pin", { taskId, pinned: pin });
+  let task = res.task;
+  if (status || pin !== undefined) {
+    task = (await client.request("task.get", { taskId })).task;
   }
-  const delivered = await deliverPrompt(client, {
-    id: res.taskId,
-    worktreePath: res.task.worktreePath,
-    vendor: res.task.vendor,
-    repo: res.task.repo
-  }, prompt);
-  return {
-    taskId: res.taskId,
-    task: res.task,
-    started: delivered.started,
-    engineReady: delivered.engineReady,
-    session: delivered.session
-  };
+  const prompt = optional(flags, "prompt");
+  if (!prompt)
+    return { taskId, task, started: false };
+  const delivered = await deliverPrompt(client, { id: taskId, worktreePath: task.worktreePath, vendor: task.vendor, repo: task.repo }, prompt);
+  return { taskId, task, started: delivered.started, engineReady: delivered.engineReady, session: delivered.session };
 }
 async function send(client, parsed) {
+  if (!client)
+    throw new ApiError("daemon required", "BAD_DAEMON");
   const { flags } = parsed;
   const prompt = required(flags, "prompt");
   let taskId = optional(flags, "task-id");
@@ -6550,17 +6737,50 @@ async function send(client, parsed) {
   };
 }
 async function getTask(client, parsed) {
+  if (!client)
+    throw new ApiError("daemon required", "BAD_DAEMON");
   const taskId = required(parsed.flags, "task-id");
   const res = await client.request("task.get", { taskId });
   const running = await sessionExists(tmuxSessionName(taskId));
   return { task: res.task, running };
 }
 async function list(client) {
+  if (!client)
+    throw new ApiError("daemon required", "BAD_DAEMON");
   return client.request("task.list");
 }
+async function setActive(client, parsed) {
+  if (!client)
+    throw new ApiError("daemon required", "BAD_DAEMON");
+  const none = optionalBool(parsed.flags, "none");
+  const taskId = none ? null : required(parsed.flags, "task-id");
+  await client.request("task.setActive", { taskId });
+  return { ok: true, activeTaskId: taskId };
+}
+async function adopt(client, parsed) {
+  if (!client)
+    throw new ApiError("daemon required", "BAD_DAEMON");
+  const { flags } = parsed;
+  const input = {
+    repo: resolveRepoFlag(required(flags, "repo")),
+    worktreePath: resolveRepoFlag(required(flags, "worktree"))
+  };
+  const branch = optional(flags, "branch");
+  if (branch)
+    input.branch = branch;
+  const vendor = optionalVendor2(flags);
+  if (vendor)
+    input.vendor = vendor;
+  const title = optional(flags, "title");
+  if (title)
+    input.title = title;
+  return client.request("worktree.adopt", input);
+}
 async function fanOut(client, parsed) {
+  if (!client)
+    throw new ApiError("daemon required", "BAD_DAEMON");
   const { flags } = parsed;
-  const repo = required(flags, "repo");
+  const repo = resolveRepoFlag(required(flags, "repo"));
   const prompt = required(flags, "prompt");
   const title = optional(flags, "title");
   const baseRef = optional(flags, "base-branch");
@@ -6589,6 +6809,8 @@ async function fanOut(client, parsed) {
   return { count: tasks.length, tasks };
 }
 async function collect(client, parsed) {
+  if (!client)
+    throw new ApiError("daemon required", "BAD_DAEMON");
   const { flags } = parsed;
   const idsFlag = optional(flags, "task-ids");
   const repoFlag = optional(flags, "repo");
@@ -6597,7 +6819,7 @@ async function collect(client, parsed) {
     taskIds = idsFlag.split(",").map((s) => s.trim()).filter(Boolean);
   } else if (repoFlag) {
     const { resolveRepoRoot: resolveRepoRoot2 } = await Promise.resolve().then(() => (init_repos(), exports_repos));
-    const target = resolveRepoRoot2(resolve4(process.cwd(), repoFlag));
+    const target = resolveRepoRoot2(resolveRepoFlag(repoFlag));
     const { tasks } = await client.request("task.list");
     taskIds = tasks.filter((t) => !t.archived && resolveRepoRoot2(t.repo) === target).map((t) => t.id);
   } else {
@@ -6623,72 +6845,67 @@ async function collect(client, parsed) {
   return { tasks: out };
 }
 async function runApiSubcommand(argv) {
-  const [verb, ...rest] = argv;
-  if (!verb || verb === "--help" || verb === "-h" || verb === "help") {
-    if (!verb) {
+  const [verbName, ...rest] = argv;
+  if (!verbName || verbName === "--help" || verbName === "-h" || verbName === "help") {
+    if (!verbName)
       fail(apiUsage(), "MISSING_VERB", 2);
-    }
     process.stdout.write(`${apiUsage()}
 `);
     return;
   }
-  if (!API_VERBS.includes(verb)) {
-    fail(`unknown verb: ${verb}
+  const verb = findVerb(verbName);
+  if (!verb)
+    fail(`unknown verb: ${verbName}
 ${apiUsage()}`, "BAD_VERB", 2);
-  }
+  const booleanFlags = new Set(verb.flags.filter((f) => f.type === "bool").map((f) => f.name));
   let parsed;
   try {
-    parsed = parseFlags(rest);
+    parsed = parseFlags(rest, booleanFlags);
   } catch (err) {
     if (err instanceof ApiError)
       fail(err.message, err.code, 2);
     fail(err instanceof Error ? err.message : String(err), "BAD_FLAG", 2);
   }
-  let client;
+  if (parsed.help) {
+    process.stdout.write(`${verbHelp(verb)}
+`);
+    return;
+  }
   try {
-    client = await connectOrStartDaemon();
+    validateAgainstSpec(verb, parsed.flags);
   } catch (err) {
-    fail(`could not reach or start the kobe daemon: ${err instanceof Error ? err.message : String(err)}`, "BAD_DAEMON", 2);
+    if (err instanceof ApiError)
+      fail(err.message, err.code, 2);
+    fail(err instanceof Error ? err.message : String(err), "BAD_FLAG", 2);
   }
-  try {
-    let result;
-    switch (verb) {
-      case "spawn-task":
-        result = await spawnTask(client, parsed);
-        break;
-      case "fan-out":
-        result = await fanOut(client, parsed);
-        break;
-      case "send":
-        result = await send(client, parsed);
-        break;
-      case "get-task":
-        result = await getTask(client, parsed);
-        break;
-      case "collect":
-        result = await collect(client, parsed);
-        break;
-      case "list":
-        result = await list(client);
-        break;
+  let client = null;
+  if (!verb.offline) {
+    try {
+      client = await connectOrStartDaemon();
+    } catch (err) {
+      fail(`could not reach or start the kobe daemon: ${err instanceof Error ? err.message : String(err)}`, "BAD_DAEMON", 2);
     }
+  }
+  try {
+    const result = await verb.handler(client, parsed);
     emit(result, parsed.pretty);
   } catch (err) {
     if (err instanceof ApiError)
       fail(err.message, err.code, 1);
     fail(err instanceof Error ? err.message : String(err), "RPC_ERROR", 1);
   } finally {
-    client.close();
+    client?.close();
   }
 }
-var API_VERBS, FANOUT_CAP = 10, ApiError;
+var API_SCHEMA_VERSION = 2, FANOUT_CAP = 10, TASK_STATUSES, ApiError, F, VERB_ALIASES, VERB_GROUPS, VERBS, API_VERBS, GLOBAL_FLAGS;
 var init_api_cmd = __esm(() => {
   init_daemon_process();
   init_interactive_command();
   init_client2();
   init_prompt_delivery();
   init_vendor();
-  API_VERBS = ["spawn-task", "fan-out", "send", "get-task", "collect", "list"];
+  init_version();
+  TASK_STATUSES = ["backlog", "in_progress", "in_review", "done", "canceled", "error"];
   ApiError = class ApiError extends Error {
     code;
     constructor(message, code) {
@@ -6696,6 +6913,241 @@ var init_api_cmd = __esm(() => {
       this.code = code;
     }
   };
+  F = {
+    repo: (required = true) => ({
+      name: "repo",
+      type: "string",
+      required,
+      placeholder: "PATH",
+      description: "Repo root (git toplevel). Relative paths resolve against $PWD."
+    }),
+    taskId: (required = true) => ({
+      name: "task-id",
+      type: "string",
+      required,
+      placeholder: "ID",
+      description: "Target task id (from `list` / `add`)."
+    }),
+    vendor: () => ({
+      name: "vendor",
+      type: "enum",
+      values: ALL_VENDORS,
+      placeholder: "V",
+      description: "Engine vendor for the task."
+    }),
+    title: () => ({ name: "title", type: "string", placeholder: "T", description: "Human task title." }),
+    prompt: (required, desc) => ({
+      name: "prompt",
+      type: "string",
+      required,
+      placeholder: "TEXT",
+      description: desc
+    })
+  };
+  VERB_ALIASES = { "spawn-task": "add" };
+  VERB_GROUPS = {
+    discover: ["schema"],
+    read: ["list", "get-task", "collect"],
+    create: ["add", "fan-out"],
+    drive: ["send", "set-active"],
+    edit: ["rename", "set-branch", "set-vendor", "set-status"],
+    lifecycle: ["archive", "pin", "delete"],
+    worktree: ["ensure-worktree", "adopt", "discover-adoptable"]
+  };
+  VERBS = [
+    {
+      name: "schema",
+      summary: "Explore the API. Default = a COMPACT index (groups + verb summaries, no flags). Drill in with --verb / --group; --all for the full spec.",
+      flags: [
+        { name: "verb", type: "string", placeholder: "NAME", description: "Full flag detail for ONE verb." },
+        { name: "group", type: "string", placeholder: "G", description: "List the verbs in one group (compact)." },
+        {
+          name: "all",
+          type: "bool",
+          description: "The COMPLETE spec \u2014 every verb AND every flag (large; avoid by default)."
+        }
+      ],
+      offline: true,
+      handler: handleSchema
+    },
+    { name: "list", summary: "List all tasks (incl. archived). Returns { tasks }.", flags: [], handler: list },
+    {
+      name: "get-task",
+      summary: "Read one task's metadata. `.running` = its tmux session is live.",
+      flags: [F.taskId()],
+      handler: getTask
+    },
+    {
+      name: "add",
+      summary: "Create a task (shows in the sidebar immediately). With --prompt it also starts the engine and delivers it. Alias: spawn-task.",
+      flags: [
+        F.repo(),
+        F.title(),
+        {
+          name: "branch",
+          type: "string",
+          placeholder: "B",
+          description: "Explicit branch name (else auto kobe/<slug>-<id>)."
+        },
+        { name: "base-branch", type: "string", placeholder: "B", description: "Base ref the worktree branches from." },
+        F.vendor(),
+        {
+          name: "status",
+          type: "enum",
+          values: TASK_STATUSES,
+          default: "backlog",
+          description: "Initial lifecycle status."
+        },
+        { name: "pin", type: "bool", description: "Pin the task to the top of the sidebar." },
+        F.prompt(false, "Optional first message \u2014 when set, materializes the worktree, starts the engine, and pastes it.")
+      ],
+      handler: add
+    },
+    {
+      name: "fan-out",
+      summary: `Spawn N tasks of ONE prompt in a single call (parallel attempts). Capped at ${FANOUT_CAP}.`,
+      flags: [
+        F.repo(),
+        F.prompt(true, "Shared prompt delivered to every spawned task."),
+        { name: "count", type: "int", placeholder: "N", description: "Number of tasks of one vendor (with --vendor)." },
+        {
+          name: "agents",
+          type: "string",
+          placeholder: "claude:2,codex:1",
+          description: "Per-vendor counts (alternative to --count)."
+        },
+        F.vendor(),
+        F.title(),
+        { name: "base-branch", type: "string", placeholder: "B", description: "Base ref for every worktree." }
+      ],
+      handler: fanOut
+    },
+    {
+      name: "send",
+      summary: "Paste a follow-up prompt into a task's running engine (one full turn). Defaults to the active task.",
+      flags: [F.taskId(false), F.prompt(true, "Text pasted + submitted into the engine pane.")],
+      handler: send
+    },
+    {
+      name: "collect",
+      summary: "Read-only comparison snapshot of several tasks (identity, branch, .running, uncommitted .changes).",
+      flags: [
+        { name: "task-ids", type: "csv", placeholder: "a,b,c", description: "Comma-separated task ids." },
+        F.repo(false)
+      ],
+      handler: collect
+    },
+    {
+      name: "rename",
+      summary: "Set a task's title.",
+      flags: [F.taskId(), { name: "title", type: "string", required: true, placeholder: "T", description: "New title." }],
+      handler: (c, p) => simpleRpc(c, "task.rename", { taskId: required(p.flags, "task-id"), title: required(p.flags, "title") })
+    },
+    {
+      name: "set-branch",
+      summary: "Rename a task's branch (git branch -m if materialized, else recorded).",
+      flags: [
+        F.taskId(),
+        { name: "branch", type: "string", required: true, placeholder: "B", description: "New branch name." }
+      ],
+      handler: (c, p) => simpleRpc(c, "task.setBranch", { taskId: required(p.flags, "task-id"), branch: required(p.flags, "branch") })
+    },
+    {
+      name: "set-vendor",
+      summary: "Change a task's engine vendor (takes effect on next session rebuild).",
+      flags: [F.taskId(), { ...F.vendor(), required: true }],
+      handler: (c, p) => simpleRpc(c, "task.setVendor", {
+        taskId: required(p.flags, "task-id"),
+        vendor: requireEnum(p.flags, "vendor", ALL_VENDORS)
+      })
+    },
+    {
+      name: "set-status",
+      summary: "Set a task's lifecycle status.",
+      flags: [
+        F.taskId(),
+        { name: "status", type: "enum", required: true, values: TASK_STATUSES, description: "New status." }
+      ],
+      handler: (c, p) => simpleRpc(c, "task.status", {
+        taskId: required(p.flags, "task-id"),
+        status: requireEnum(p.flags, "status", TASK_STATUSES)
+      })
+    },
+    {
+      name: "archive",
+      summary: "Archive (or with --archived=false, unarchive) a task. Non-destructive: worktree/branch/history stay.",
+      flags: [
+        F.taskId(),
+        { name: "archived", type: "bool", default: "true", description: "true to archive, false to unarchive." }
+      ],
+      handler: (c, p) => simpleRpc(c, "task.archive", {
+        taskId: required(p.flags, "task-id"),
+        archived: optionalBool(p.flags, "archived") ?? true
+      })
+    },
+    {
+      name: "pin",
+      summary: "Pin (or with --pinned=false, unpin) a task to the top of the sidebar.",
+      flags: [F.taskId(), { name: "pinned", type: "bool", default: "true", description: "true to pin, false to unpin." }],
+      handler: (c, p) => simpleRpc(c, "task.pin", {
+        taskId: required(p.flags, "task-id"),
+        pinned: optionalBool(p.flags, "pinned") ?? true
+      })
+    },
+    {
+      name: "set-active",
+      summary: "Set the shared active task (the focus every Tasks pane highlights). Pass --none to clear.",
+      flags: [
+        F.taskId(false),
+        { name: "none", type: "bool", description: "Clear the active task instead of setting one." }
+      ],
+      handler: setActive
+    },
+    {
+      name: "ensure-worktree",
+      summary: "Materialize a task's git worktree on disk now (without starting an engine). Returns { worktreePath }.",
+      flags: [F.taskId()],
+      handler: (c, p) => simpleRpc(c, "task.ensureWorktree", { taskId: required(p.flags, "task-id") })
+    },
+    {
+      name: "delete",
+      summary: "Permanently remove a task (and its worktree). DESTRUCTIVE \u2014 prefer `archive`. Needs --force on a dirty worktree.",
+      flags: [F.taskId(), { name: "force", type: "bool", description: "Delete even with uncommitted changes." }],
+      handler: (c, p) => simpleRpc(c, "task.delete", {
+        taskId: required(p.flags, "task-id"),
+        force: optionalBool(p.flags, "force") ?? false
+      })
+    },
+    {
+      name: "discover-adoptable",
+      summary: "List existing git worktrees in a repo not yet tracked as kobe tasks. Returns { worktrees }.",
+      flags: [F.repo()],
+      handler: (c, p) => simpleRpc(c, "worktree.discoverAdoptable", { repo: resolveRepoFlag(required(p.flags, "repo")) })
+    },
+    {
+      name: "adopt",
+      summary: "Import an existing git worktree as a kobe task. Returns { task }.",
+      flags: [
+        F.repo(),
+        {
+          name: "worktree",
+          type: "string",
+          required: true,
+          placeholder: "PATH",
+          description: "Path of the worktree to adopt."
+        },
+        { name: "branch", type: "string", placeholder: "B", description: "Branch override (else the worktree's own)." },
+        F.vendor(),
+        F.title()
+      ],
+      handler: adopt
+    }
+  ];
+  API_VERBS = VERBS.map((v) => v.name);
+  GLOBAL_FLAGS = [
+    { name: "pretty", type: "bool", description: "Pretty-print stdout JSON." },
+    { name: "help", type: "bool", description: "Show usage for the verb and exit." }
+  ];
 });
 
 // src/cli/update.ts
@@ -7206,31 +7658,66 @@ var init_daemon_cmd = __esm(() => {
 });
 
 // src/lib/skill-install.ts
-import { existsSync as existsSync4 } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync6 } from "fs";
 import { homedir as homedir9 } from "os";
 import { join as join7 } from "path";
+function npxSkillsArgv(opts = {}) {
+  return ["skills", "add", SKILL_SOURCE_SLUG, "--skill", "kobe", "--agent", opts.agent ?? DEFAULT_SKILL_AGENT];
+}
+function npxSkillsCommand(opts = {}) {
+  return `npx ${npxSkillsArgv(opts).join(" ")}`;
+}
 function kobeSkillPaths(opts = {}) {
   const home = opts.home ?? homedir9();
   const cwd = opts.cwd ?? process.cwd();
   return [join7(home, SKILL_REL_PATH), join7(cwd, SKILL_REL_PATH)];
 }
-function isKobeSkillInstalled(opts) {
-  return kobeSkillPaths(opts).some((p) => existsSync4(p));
+function parseSkillVersion(content) {
+  const m = content.match(/kobe-skill-version:\s*(\d+)/);
+  return m ? Number.parseInt(m[1], 10) : null;
+}
+function kobeSkillState(opts) {
+  const path6 = kobeSkillPaths(opts).find((p) => existsSync4(p));
+  if (!path6) {
+    return { installed: false, installedVersion: null, currentVersion: KOBE_SKILL_VERSION, stale: false };
+  }
+  let installedVersion = null;
+  try {
+    installedVersion = parseSkillVersion(readFileSync6(path6, "utf8"));
+  } catch {
+    installedVersion = null;
+  }
+  const stale = installedVersion === null || installedVersion < KOBE_SKILL_VERSION;
+  return { installed: true, installedVersion, currentVersion: KOBE_SKILL_VERSION, stale };
 }
 function maybeHintSkillInstall() {
-  if (isKobeSkillInstalled())
-    return;
-  if (getPersistedString(HINT_SEEN_KEY) === "1")
+  const state = kobeSkillState();
+  if (!state.installed) {
+    if (getPersistedString(HINT_SEEN_KEY) === "1")
+      return;
+    setPersistedString(HINT_SEEN_KEY, "1");
+    process.stderr.write(`
+kobe: the kobe agent skill isn't installed \u2014 install it so your coding agent can drive kobe via \`kobe api\`:
+  ${SKILL_INSTALL_COMMAND}
+  (wraps \`${npxSkillsCommand()}\`; check anytime with \`kobe doctor\`)
+
+`);
     return;
-  setPersistedString(HINT_SEEN_KEY, "1");
-  process.stderr.write(`
-kobe: the kobe agent skill isn't installed \u2014 install it so Claude Code can fan out parallel tasks via \`kobe api\`:
+  }
+  if (state.stale) {
+    const key = `${HINT_SEEN_KEY}:v${state.currentVersion}`;
+    if (getPersistedString(key) === "1")
+      return;
+    setPersistedString(key, "1");
+    const was = state.installedVersion === null ? "an older" : `v${state.installedVersion}`;
+    process.stderr.write(`
+kobe: your kobe agent skill is out of date (${was}; this kobe wants v${state.currentVersion}) \u2014 refresh it so \`kobe api\` guidance matches:
   ${SKILL_INSTALL_COMMAND}
-  (check anytime with \`kobe doctor\`)
 
 `);
+  }
 }
-var SKILL_REL_PATH = ".claude/skills/kobe/SKILL.md", SKILL_INSTALL_COMMAND = "npx skills add Sma1lboy/kobe --skill kobe --agent claude-code", HINT_SEEN_KEY = "skillHintSeen";
+var KOBE_SKILL_VERSION = 1, SKILL_REL_PATH = ".claude/skills/kobe/SKILL.md", SKILL_INSTALL_COMMAND = "kobe skill install", SKILL_SOURCE_SLUG = "Sma1lboy/kobe", DEFAULT_SKILL_AGENT = "claude-code", HINT_SEEN_KEY = "skillHintSeen";
 var init_skill_install = __esm(() => {
   init_repos();
 });
@@ -7242,7 +7729,7 @@ __export(exports_maintenance, {
   runReloadSubcommand: () => runReloadSubcommand,
   runDoctorSubcommand: () => runDoctorSubcommand
 });
-import { existsSync as existsSync5, readFileSync as readFileSync6, statSync } from "fs";
+import { existsSync as existsSync5, readFileSync as readFileSync7, statSync } from "fs";
 import { unlink as unlink6 } from "fs/promises";
 import { join as join8 } from "path";
 import { createInterface } from "readline";
@@ -7291,7 +7778,7 @@ function describeFile(path6) {
 }
 function taskCount(tasksPath) {
   try {
-    const parsed = JSON.parse(readFileSync6(tasksPath, "utf8"));
+    const parsed = JSON.parse(readFileSync7(tasksPath, "utf8"));
     return Array.isArray(parsed.tasks) ? parsed.tasks.length : null;
   } catch {
     return null;
@@ -7299,7 +7786,7 @@ function taskCount(tasksPath) {
 }
 function tailFile(path6, n) {
   try {
-    const lines = readFileSync6(path6, "utf8").split(`
+    const lines = readFileSync7(path6, "utf8").split(`
 `).filter((l) => l.trim().length > 0);
     return lines.slice(-n).join(`
 `);
@@ -7379,11 +7866,16 @@ async function runDoctorSubcommand(argv = []) {
     out.push("tmux:    \u2717 not found on PATH (task sessions need tmux)");
   }
   out.push("");
-  if (isKobeSkillInstalled()) {
-    out.push("skill:   \u2713 kobe agent skill installed");
-  } else {
-    out.push("skill:   \u2717 kobe agent skill not installed (optional \u2014 lets Claude Code drive `kobe api`)");
+  const skill = kobeSkillState();
+  if (!skill.installed) {
+    out.push("skill:   \u2717 kobe agent skill not installed (optional \u2014 lets a coding agent drive `kobe api`)");
     out.push(`         \u2192 ${SKILL_INSTALL_COMMAND}`);
+  } else if (skill.stale) {
+    const was = skill.installedVersion === null ? "unstamped" : `v${skill.installedVersion}`;
+    out.push(`skill:   \u26A0 kobe agent skill out of date (${was}; this kobe wants v${skill.currentVersion})`);
+    out.push(`         \u2192 ${SKILL_INSTALL_COMMAND}`);
+  } else {
+    out.push(`skill:   \u2713 kobe agent skill installed (v${skill.installedVersion})`);
   }
   out.push("");
   const count = taskCount(tasksPath);
@@ -7551,6 +8043,106 @@ var init_maintenance = __esm(() => {
   init_client2();
 });
 
+// src/cli/skill-cmd.ts
+var exports_skill_cmd = {};
+__export(exports_skill_cmd, {
+  runSkillSubcommand: () => runSkillSubcommand
+});
+function skillUsage() {
+  return [
+    "usage: kobe skill <verb>",
+    "",
+    "verbs:",
+    "  install [--agent NAME]   Install the kobe agent skill (wraps `npx skills add`)",
+    "  status                   Show whether the skill is installed",
+    "  command [--agent NAME]   Print the underlying npx command without running it",
+    "",
+    `The skill teaches a coding agent how to drive \`kobe api\`. Default agent: ${DEFAULT_SKILL_AGENT}.`
+  ].join(`
+`);
+}
+function parseAgent(rest) {
+  let agent = DEFAULT_SKILL_AGENT;
+  for (let i = 0;i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === "--agent") {
+      const v = rest[i + 1];
+      if (!v || v.startsWith("--")) {
+        process.stderr.write(`kobe skill: --agent requires a value
+`);
+        process.exit(2);
+      }
+      agent = v;
+      i++;
+    } else if (arg.startsWith("--agent=")) {
+      agent = arg.slice("--agent=".length);
+    } else {
+      process.stderr.write(`kobe skill: unknown flag "${arg}"
+
+${skillUsage()}
+`);
+      process.exit(2);
+    }
+  }
+  return agent;
+}
+async function runSkillSubcommand(argv) {
+  const [verb, ...rest] = argv;
+  if (!verb || verb === "--help" || verb === "-h" || verb === "help") {
+    process.stdout.write(`${skillUsage()}
+`);
+    if (!verb)
+      process.exitCode = 2;
+    return;
+  }
+  if (!SKILL_VERBS.includes(verb)) {
+    process.stderr.write(`kobe skill: unknown verb "${verb}"
+
+${skillUsage()}
+`);
+    process.exit(2);
+  }
+  if (verb === "status") {
+    const state = kobeSkillState();
+    const [userPath, projectPath] = kobeSkillPaths();
+    const head = !state.installed ? "\u2717 not installed" : state.stale ? `\u26A0 out of date (installed ${state.installedVersion === null ? "unstamped" : `v${state.installedVersion}`}, this kobe wants v${state.currentVersion})` : `\u2713 installed (v${state.installedVersion})`;
+    process.stdout.write([
+      `kobe skill: ${head}`,
+      `  looked in: ${userPath}`,
+      `             ${projectPath}`,
+      state.installed && !state.stale ? "" : "  \u2192 run `kobe skill install` to install / refresh",
+      ""
+    ].join(`
+`));
+    return;
+  }
+  if (verb === "command") {
+    process.stdout.write(`${npxSkillsCommand({ agent: parseAgent(rest) })}
+`);
+    return;
+  }
+  const agent = parseAgent(rest);
+  const args = npxSkillsArgv({ agent });
+  process.stdout.write(`kobe skill: running \`npx ${args.join(" ")}\`
+`);
+  const proc = Bun.spawn(["npx", ...args], { stdin: "inherit", stdout: "inherit", stderr: "inherit" });
+  const code = await proc.exited;
+  if (code !== 0) {
+    process.stderr.write(`
+kobe skill install failed (npx exited ${code}). Is \`npx\` on PATH and are you online?
+` + `You can run it yourself: ${npxSkillsCommand({ agent })}
+`);
+    process.exit(code || 1);
+  }
+  process.stdout.write(`kobe skill: installed.
+`);
+}
+var SKILL_VERBS;
+var init_skill_cmd = __esm(() => {
+  init_skill_install();
+  SKILL_VERBS = ["install", "status", "command"];
+});
+
 // ../../node_modules/.bun/entities@7.0.1/node_modules/entities/dist/esm/decode-codepoint.js
 function replaceCodePoint(codePoint) {
   var _a2;
@@ -13021,7 +13613,7 @@ var init_binary3 = __esm(() => {
 });
 
 // src/engine/account-detect.ts
-import { readFileSync as readFileSync7, statSync as statSync6 } from "fs";
+import { readFileSync as readFileSync8, statSync as statSync6 } from "fs";
 import { homedir as homedir14 } from "os";
 import path10 from "path";
 function claudeGlobalConfigPath(env, home) {
@@ -13234,7 +13826,7 @@ var init_account_detect = __esm(() => {
           return null;
         throw err;
       }
-      return readFileSync7(p, "utf8");
+      return readFileSync8(p, "utf8");
     },
     env(name) {
       return process.env[name];
@@ -14785,12 +15377,12 @@ var init_focus = __esm(() => {
 });
 
 // src/tui/context/kv.tsx
-import { mkdirSync as mkdirSync4, readFileSync as readFileSync8, renameSync as renameSync2, writeFileSync as writeFileSync3 } from "fs";
+import { mkdirSync as mkdirSync4, readFileSync as readFileSync9, renameSync as renameSync2, writeFileSync as writeFileSync3 } from "fs";
 import { dirname as dirname6 } from "path";
 function loadInitial() {
   const statePath2 = kvStatePath();
   try {
-    const text = readFileSync8(statePath2, "utf8");
+    const text = readFileSync9(statePath2, "utf8");
     const parsed = JSON.parse(text);
     if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
       return parsed;
@@ -14886,10 +15478,10 @@ var init_kv = __esm(() => {
 });
 
 // src/tui/lib/persisted-ui-prefs.ts
-import { readFileSync as readFileSync9 } from "fs";
+import { readFileSync as readFileSync10 } from "fs";
 function readPersistedUiPrefs(fallbackTheme) {
   try {
-    const parsed = JSON.parse(readFileSync9(kvStatePath(), "utf8"));
+    const parsed = JSON.parse(readFileSync10(kvStatePath(), "utf8"));
     const theme = typeof parsed.activeTheme === "string" && hasTheme(parsed.activeTheme) ? parsed.activeTheme : fallbackTheme;
     const transparent = parsed.transparentBackground === true;
     const focusAccent = typeof parsed.focusAccent === "string" && FOCUS_ACCENT_SLOTS.includes(parsed.focusAccent) ? parsed.focusAccent : null;
@@ -22260,6 +22852,7 @@ function topLevelUsage() {
     "  api <verb>              Scriptable RPC surface for agents (see `kobe api --help`)",
     "  daemon <verb>           Manage the daemon (start|stop|status|restart)",
     "  theme <verb>            Manage user themes (list|add|remove)",
+    "  skill <verb>            Install the kobe agent skill (install|status|command)",
     "  update [target]         Self-update kobe",
     "  doctor                  Diagnose daemon / tmux / state (read-only)",
     "  reset [--hard]          Recover a wedged install",
@@ -22521,6 +23114,11 @@ async function main() {
     await runReloadSubcommand2(rest);
     return;
   }
+  if (subcommand === "skill") {
+    const { runSkillSubcommand: runSkillSubcommand2 } = await Promise.resolve().then(() => (init_skill_cmd(), exports_skill_cmd));
+    await runSkillSubcommand2(rest);
+    return;
+  }
   if (subcommand === "new-chattab") {
     const flags = parseOpsFlags(rest);
     const session = flags.session;

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@sma1lboy/kobe",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "TUI orchestrator for Claude Code (codename)",
   "type": "module",
   "packageManager": "bun@1.3.13",