@allocator-one/harness-cli 1.3.0 → 1.4.1

package/README.md

@@ -2,8 +2,8 @@
 
 CLI and MCP server for [Harness](https://harness.infra.one), allocator.one's
 issue tracker. A standalone Node client — no backend checkout, no Erlang
-toolchain — that shares credentials with the Elixir escript (`bin/harness`
-in the `allocator-one` repo).
+toolchain, and no local issue state: issues live server-side, so there is
+nothing to commit or sync.
 
 ## Install
 
@@ -27,8 +27,8 @@ Requires Node >= 20.
 No setup needed: commands target `https://harness.infra.one` and start the
 browser login the first time. One login covers every shell, worktree, and
 agent slot on a machine — credentials are stored at
-`~/.config/harness/credentials.json` (0600), byte-compatible with the
-escript's, so either client can log in or out without breaking the other.
+`~/.config/harness/credentials.json` (0600) as a single `{url, token}` pair,
+and a token is only ever sent to the host that minted it.
 
 - `harness login` — browser flow (PKCE loopback); `--no-browser` prints the
   URL and prompts for a pasted token instead.
@@ -88,8 +88,7 @@ from the working directory, gives every clone of a repo its defaults:
 | `url` | Target host. `HARNESS_API_URL` wins. Tokens stay host-bound: a stored login only serves the host that minted it, an env `HARNESS_API_TOKEN` refuses to pair with a repo-named host (set `HARNESS_API_URL` explicitly), and before the interactive auto-login opens a browser at a host named only by the repo, the CLI asks once per host (remembered in `~/.config/harness/trusted-hosts.json`). |
 | `org` | Reserved for Harness org-scoping; parsed today, `url` wins meanwhile. |
 
-This is config, not state — issues stay server-side. The escript does not
-read this file (TS-CLI-only).
+This is config, not state — issues stay server-side.
 
 ## Development
 

package/dist/{chunk-3WR6YFU6.js → chunk-MF7MQ2L6.js}

@@ -557,13 +557,14 @@ async function list(ctx, opts) {
 }
 async function search(ctx, queryWords, opts) {
   if (queryWords.length === 0) throw new UsageError("usage: harness search <query>");
-  const params = {
-    search: queryWords.join(" "),
-    page_size: opts.limit ?? 50,
-    page: opts.page ?? 1
-  };
-  const { records, notice } = await fetchIssues(ctx, params, opts);
-  return { json: records, human: issuesTable(records), notice };
+  const deprecation = opts.page !== void 0 || opts.all === true ? "--page/--all are ignored: search returns one ranked list, capped at 20" : void 0;
+  let params = { q: queryWords.join(" ") };
+  if (opts.limit !== void 0) params = { ...params, limit: opts.limit };
+  const body = await ctx.client.get("/api/v1/issues/search", params);
+  const meta = body.meta ?? {};
+  const degraded = meta["mode"] === "lexical" ? "semantic search unavailable \u2014 showing lexical matches only" : void 0;
+  const notice = [deprecation, degraded].filter(Boolean).join("; ") || void 0;
+  return { json: body.data, human: issuesTable(body.data), notice };
 }
 async function show(ctx, identifier, opts) {
   requireIdentifiers([identifier]);

package/dist/cli.js

@@ -59,7 +59,7 @@ import {
   version,
   workflowStates,
   writeCredentials
-} from "./chunk-3WR6YFU6.js";
+} from "./chunk-MF7MQ2L6.js";
 
 // src/cli.ts
 import { createInterface as createInterface2 } from "readline";
@@ -372,6 +372,16 @@ function defaultOpenBrowser(url) {
   }
 }
 
+// src/core/stdio.ts
+var BROKEN_PIPE_CODES = /* @__PURE__ */ new Set(["EPIPE", "ERR_STREAM_DESTROYED"]);
+function guardBrokenPipes(streams = [process.stdout, process.stderr]) {
+  for (const stream of streams) {
+    stream.on("error", (error) => {
+      if (!BROKEN_PIPE_CODES.has(error.code ?? "")) throw error;
+    });
+  }
+}
+
 // src/core/upgrade.ts
 import { spawn, spawnSync } from "child_process";
 import {
@@ -390,6 +400,7 @@ import {
 import { basename, dirname, join as join2, parse, sep } from "path";
 import { fileURLToPath } from "url";
 var PACKAGE_NAME = "@allocator-one/harness-cli";
+var UPGRADE_INSTALL_SPEC = `${PACKAGE_NAME}@latest`;
 var UPDATE_CHECK_COMMAND = "__update-check";
 var REEXEC_SENTINEL = "HARNESS_UPGRADED";
 var DEFAULT_REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
@@ -399,7 +410,11 @@ var NPM_ROOT_TIMEOUT_MS = 15e3;
 var INSTALL_TIMEOUT_MS = 12e4;
 var LOCK_STALE_MS = NPM_ROOT_TIMEOUT_MS + INSTALL_TIMEOUT_MS + 6e4;
 function detectInstall(from = fileURLToPath(import.meta.url)) {
-  const unknown = { kind: "unknown", packageRoot: null, nodeModules: null };
+  const unknown = {
+    kind: "unknown",
+    packageRoot: null,
+    nodeModules: null
+  };
   if (from.split(sep).includes("_npx")) return { ...unknown, kind: "npx" };
   const packageRoot = findPackageRoot(from);
   if (packageRoot === null) return unknown;
@@ -432,7 +447,9 @@ function packageNameAt(path) {
 }
 function versionAt(packageRoot) {
   try {
-    const parsed = JSON.parse(readFileSync(join2(packageRoot, "package.json"), "utf8"));
+    const parsed = JSON.parse(
+      readFileSync(join2(packageRoot, "package.json"), "utf8")
+    );
     if (typeof parsed !== "object" || parsed === null) return null;
     const version2 = parsed["version"];
     return typeof version2 === "string" ? version2 : null;
@@ -463,7 +480,8 @@ function isNewer(candidate, current) {
   const b = parseVersion(current);
   if (a === null || b === null) return false;
   for (let index = 0; index < 3; index++) {
-    if (a.parts[index] !== b.parts[index]) return a.parts[index] > b.parts[index];
+    if (a.parts[index] !== b.parts[index])
+      return a.parts[index] > b.parts[index];
   }
   if (a.pre === b.pre) return false;
   if (a.pre === null) return true;
@@ -499,7 +517,8 @@ function readStamp(env = process.env) {
     if (typeof parsed !== "object" || parsed === null) return null;
     const record = parsed;
     const checkedAt = record["checkedAt"];
-    if (typeof checkedAt !== "number" || !Number.isFinite(checkedAt)) return null;
+    if (typeof checkedAt !== "number" || !Number.isFinite(checkedAt))
+      return null;
     const latest = record["latest"];
     return { checkedAt, latest: typeof latest === "string" ? latest : null };
   } catch {
@@ -571,7 +590,8 @@ async function fetchLatestVersion(env) {
     const parsed = await response.json();
     if (typeof parsed !== "object" || parsed === null) return null;
     const version2 = parsed["version"];
-    if (typeof version2 !== "string" || parseVersion(version2) === null) return null;
+    if (typeof version2 !== "string" || parseVersion(version2) === null)
+      return null;
     return version2;
   } catch {
     return null;
@@ -581,10 +601,18 @@ function selfHeal(options = {}) {
   const env = options.env ?? process.env;
   const argv2 = options.argv ?? process.argv;
   if (truthy(env[REEXEC_SENTINEL])) {
-    return { kind: "skipped", reason: "already upgraded once for this command" };
+    return {
+      kind: "skipped",
+      reason: "already upgraded once for this command"
+    };
   }
-  if (!autoUpgradeEnabled(env)) return { kind: "skipped", reason: "automatic upgrades are off" };
-  if (argv2[2] === "mcp") return { kind: "skipped", reason: "an MCP session must not be replaced mid-stream" };
+  if (!autoUpgradeEnabled(env))
+    return { kind: "skipped", reason: "automatic upgrades are off" };
+  if (argv2[2] === "mcp")
+    return {
+      kind: "skipped",
+      reason: "an MCP session must not be replaced mid-stream"
+    };
   const install = options.install ?? detectInstall();
   if (install.kind !== "global" || install.packageRoot === null) {
     return { kind: "skipped", reason: describeInstall(install.kind) };
@@ -595,17 +623,27 @@ function selfHeal(options = {}) {
     return { kind: "upgraded", code: reexec(options, env, argv2) };
   }
   const lock = takeLock(env);
-  if (lock === null) return { kind: "skipped", reason: "another harness process is already upgrading" };
+  if (lock === null)
+    return {
+      kind: "skipped",
+      reason: "another harness process is already upgrading"
+    };
   try {
     const stillHeld = () => readHolder(lock.path)?.pid === lock.pid;
     const result = (options.runInstall ?? npmInstallGlobal)(install, stillHeld);
     if (!result.ok) return { kind: "failed", reason: result.detail };
     const after = versionAt(packageRoot);
     if (after !== null && after === installed) {
-      return { kind: "failed", reason: `still ${after} after upgrading \u2014 no newer release is published` };
+      return {
+        kind: "failed",
+        reason: `still ${after} after upgrading \u2014 no newer release is published`
+      };
     }
     if (after !== null && installed !== null && !isNewer(after, installed)) {
-      return { kind: "failed", reason: `npm left ${after} installed, which is not newer than ${installed}` };
+      return {
+        kind: "failed",
+        reason: `npm left ${after} installed, which is not newer than ${installed}`
+      };
     }
   } finally {
     releaseLock(lock);
@@ -613,7 +651,10 @@ function selfHeal(options = {}) {
   return { kind: "upgraded", code: reexec(options, env, argv2) };
 }
 function reexec(options, env, argv2) {
-  return (options.reexec ?? reexecSelf)({ ...env, [REEXEC_SENTINEL]: "1" }, argv2);
+  return (options.reexec ?? reexecSelf)(
+    { ...env, [REEXEC_SENTINEL]: "1" },
+    argv2
+  );
 }
 function describeInstall(kind) {
   switch (kind) {
@@ -629,9 +670,13 @@ function describeInstall(kind) {
 }
 function npmInstallGlobal(install, stillHeld) {
   const globalRoot = npmGlobalRoot();
-  if (globalRoot === null) return { ok: false, detail: "npm did not say where its global root is" };
+  if (globalRoot === null)
+    return { ok: false, detail: "npm did not say where its global root is" };
   if (globalRoot.includes("***")) {
-    return { ok: false, detail: "npm redacted its own global root, so this copy's location cannot be confirmed" };
+    return {
+      ok: false,
+      detail: "npm redacted its own global root, so this copy's location cannot be confirmed"
+    };
   }
   if (install.nodeModules === null || !samePath(globalRoot, install.nodeModules)) {
     return {
@@ -642,10 +687,16 @@ function npmInstallGlobal(install, stillHeld) {
   try {
     accessSync2(globalRoot, constants.W_OK);
   } catch {
-    return { ok: false, detail: `${globalRoot} is not writable \u2014 upgrade it yourself` };
+    return {
+      ok: false,
+      detail: `${globalRoot} is not writable \u2014 upgrade it yourself`
+    };
   }
   if (!stillHeld()) {
-    return { ok: false, detail: "lost the upgrade lock while preparing \u2014 another process took over" };
+    return {
+      ok: false,
+      detail: "lost the upgrade lock while preparing \u2014 another process took over"
+    };
   }
   process.stderr.write(`harness: upgrading ${PACKAGE_NAME} \u2026
 `);
@@ -657,7 +708,7 @@ function npmInstallGlobal(install, stillHeld) {
     "--no-fund",
     "--no-update-notifier",
     "--loglevel=error",
-    `${PACKAGE_NAME}@latest`
+    UPGRADE_INSTALL_SPEC
   ];
   const result = spawnSync(npmCommand(), args, {
     // npm's diagnostics belong on stderr with ours; stdout stays the
@@ -666,9 +717,13 @@ function npmInstallGlobal(install, stillHeld) {
     timeout: INSTALL_TIMEOUT_MS,
     ...npmSpawnOptions()
   });
-  if (result.error !== void 0) return { ok: false, detail: result.error.message };
+  if (result.error !== void 0)
+    return { ok: false, detail: result.error.message };
   if (result.status !== 0) {
-    return { ok: false, detail: `npm install exited ${result.status ?? `on ${String(result.signal)}`}` };
+    return {
+      ok: false,
+      detail: `npm install exited ${result.status ?? `on ${String(result.signal)}`}`
+    };
   }
   return { ok: true, detail: "" };
 }
@@ -710,8 +765,10 @@ function reexecSelf(env, argv2) {
     env
   });
   if (result.error !== void 0) {
-    process.stderr.write(`harness: upgraded, but re-running failed: ${result.error.message}
-`);
+    process.stderr.write(
+      `harness: upgraded, but re-running failed: ${result.error.message}
+`
+    );
     return 1;
   }
   return result.status ?? 1;
@@ -794,7 +851,10 @@ function autoUpgradeEnabled(env) {
 
 // src/cli.ts
 function promptLine(question) {
-  const readline = createInterface2({ input: process.stdin, output: process.stderr });
+  const readline = createInterface2({
+    input: process.stdin,
+    output: process.stderr
+  });
   return new Promise((resolve) => {
     readline.question(question, (answer) => {
       readline.close();
@@ -804,15 +864,19 @@ function promptLine(question) {
 }
 function exitWith(code) {
   const drain = (stream) => new Promise((resolve) => stream.write("", () => resolve()));
-  return Promise.all([drain(process.stdout), drain(process.stderr)]).then(() => process.exit(code));
+  return Promise.all([drain(process.stdout), drain(process.stderr)]).then(
+    () => process.exit(code)
+  );
 }
+guardBrokenPipes();
 var program = new Command();
 program.name("harness").description("issue tracking for humans and agents (harness.infra.one)").exitOverride().configureOutput({
   writeOut: (text) => process.stdout.write(text),
   writeErr: (text) => process.stderr.write(text)
 });
 function integer(value) {
-  if (!/^\d+$/.test(value)) throw new InvalidArgumentError("expected a non-negative integer");
+  if (!/^\d+$/.test(value))
+    throw new InvalidArgumentError("expected a non-negative integer");
   return Number.parseInt(value, 10);
 }
 function collect(value, previous) {
@@ -858,8 +922,10 @@ async function withConfig(jsonFlag, mutating, run) {
     process.stderr.write(loginResult.human);
     const again = resolveConfig();
     if (again.kind !== "ok") {
-      process.stderr.write(`harness: still not signed in to ${resolved.baseUrl} after logging in
-`);
+      process.stderr.write(
+        `harness: still not signed in to ${resolved.baseUrl} after logging in
+`
+      );
       return exitWith(1);
     }
     return execute(again.config, jsonFlag, mutating, run);
@@ -891,16 +957,20 @@ async function fail(error, hostNotice) {
     return exitWith(1);
   }
   if (error instanceof TransportError) {
-    process.stderr.write(hostNotice + `harness: cannot reach the API: ${clean(error.message)}
-`);
+    process.stderr.write(
+      hostNotice + `harness: cannot reach the API: ${clean(error.message)}
+`
+    );
     return exitWith(3);
   }
   if (error instanceof UpgradeRequiredError) {
     const healed = selfHeal();
     if (healed.kind === "upgraded") return exitWith(healed.code);
     const why = healed.kind === "failed" ? ` (tried to upgrade: ${clean(healed.reason)})` : "";
-    process.stderr.write(hostNotice + `harness: ${clean(error.message)} (HTTP 426)${why}
-`);
+    process.stderr.write(
+      hostNotice + `harness: ${clean(error.message)} (HTTP 426)${why}
+`
+    );
     return exitWith(1);
   }
   if (error instanceof HttpError) {
@@ -919,7 +989,8 @@ async function fail(error, hostNotice) {
 }
 function errorDetails(body) {
   const details = body["details"];
-  if (typeof details !== "object" || details === null || Array.isArray(details)) return "";
+  if (typeof details !== "object" || details === null || Array.isArray(details))
+    return "";
   return Object.entries(details).map(([field, messages]) => {
     const text = Array.isArray(messages) ? messages.map(String).join("; ") : String(messages);
     return `
@@ -927,24 +998,53 @@ function errorDetails(body) {
   }).join("");
 }
 program.command("ready").description("issues ready to work, highest priority first").option("--claim", "atomically claim the first claimable issue").option("--team <key>", "team filter").option("--limit <n>", "page size", integer).option("--page <n>", "page number", integer).option("--all", "follow every page").option("--json", "emit JSON").action(async (opts) => {
-  await withConfig(opts.json === true, opts.claim === true, (ctx) => ready(ctx, opts));
+  await withConfig(
+    opts.json === true,
+    opts.claim === true,
+    (ctx) => ready(ctx, opts)
+  );
 });
 program.command("blocked").description("issues waiting on a blocker").option("--team <key>", "team filter").option("--limit <n>", "page size", integer).option("--page <n>", "page number", integer).option("--all", "follow every page").option("--json", "emit JSON").action(async (opts) => {
-  await withConfig(opts.json === true, false, (ctx) => blocked(ctx, opts));
-});
-program.command("list").description("list issues with filters").option("--status <status>", "open | in_progress | closed").option("--assignee <who>", 'me, a user id, an email, or a full name; "" for unassigned').option("--priority <name>", "urgent | high | medium | low | none").option("--label <name>", "label filter").option("--type <type>", "task | bug | feature | epic").option("--search <query>", "full-text search").option("--team <key>", "team filter").option("--parent <id>", "children of an epic").option("--scope <scope>", "all | archived").option("--limit <n>", "page size", integer).option("--page <n>", "page number", integer).option("--all", "follow every page").option("--json", "emit JSON").action(async (opts) => {
-  await withConfig(opts.json === true, false, (ctx) => list(ctx, opts));
+  await withConfig(
+    opts.json === true,
+    false,
+    (ctx) => blocked(ctx, opts)
+  );
 });
-program.command("search").description("full-text search").argument("[query...]").option("--limit <n>", "page size", integer).option("--page <n>", "page number", integer).option("--all", "follow every page").option("--json", "emit JSON").action(async (query, opts) => {
-  await withConfig(opts.json === true, false, (ctx) => search(ctx, query, opts));
-});
-program.command("show").description("full issue detail; downloads attached images locally").argument("[id]").option("--no-images", "skip attachment downloads").option("--json", "emit JSON").action(async (id, opts) => {
-  await withConfig(opts.json === true, false, (ctx) => {
-    if (id === void 0) throw new UsageError("usage: harness show <id>");
-    requireIdentifiers2([id]);
-    return show(ctx, id, opts);
-  });
+program.command("list").description("list issues with filters").option("--status <status>", "open | in_progress | closed").option(
+  "--assignee <who>",
+  'me, a user id, an email, or a full name; "" for unassigned'
+).option("--priority <name>", "urgent | high | medium | low | none").option("--label <name>", "label filter").option("--type <type>", "task | bug | feature | epic").option("--search <query>", "full-text search").option("--team <key>", "team filter").option("--parent <id>", "children of an epic").option("--scope <scope>", "all | archived").option("--limit <n>", "page size", integer).option("--page <n>", "page number", integer).option("--all", "follow every page").option("--json", "emit JSON").action(async (opts) => {
+  await withConfig(
+    opts.json === true,
+    false,
+    (ctx) => list(ctx, opts)
+  );
 });
+program.command("search").description(
+  "search by meaning \u2014 ranked, exact identifier first; use list --search for paginated filtering"
+).argument("[query...]").option("--limit <n>", "maximum results (default 10, capped at 20)", integer).option(
+  "--page <n>",
+  "(deprecated, ignored \u2014 results are ranked and capped)",
+  integer
+).option("--all", "(deprecated, ignored \u2014 results are ranked and capped)").option("--json", "emit JSON").action(
+  async (query, opts) => {
+    await withConfig(
+      opts.json === true,
+      false,
+      (ctx) => search(ctx, query, opts)
+    );
+  }
+);
+program.command("show").description("full issue detail; downloads attached images locally").argument("[id]").option("--no-images", "skip attachment downloads").option("--json", "emit JSON").action(
+  async (id, opts) => {
+    await withConfig(opts.json === true, false, (ctx) => {
+      if (id === void 0) throw new UsageError("usage: harness show <id>");
+      requireIdentifiers2([id]);
+      return show(ctx, id, opts);
+    });
+  }
+);
 program.command("stats").description("per-team and total counts").option("--json", "emit JSON").action(async (opts) => {
   await withConfig(opts.json === true, false, (ctx) => stats(ctx));
 });
@@ -956,195 +1056,322 @@ program.command("version").description("print CLI and server API versions").opti
   let config = null;
   if (resolved.kind === "ok") config = resolved.config;
   else if (resolved.kind === "needs-login") {
-    config = { baseUrl: resolved.baseUrl, token: "", actor: null, team: null, cacheDir: "" };
+    config = {
+      baseUrl: resolved.baseUrl,
+      token: "",
+      actor: null,
+      team: null,
+      cacheDir: ""
+    };
   }
   const output = await version(config);
-  process.stdout.write(opts.json === true ? json(output.json) : output.human);
+  process.stdout.write(
+    opts.json === true ? json(output.json) : output.human
+  );
   await exitWith(0);
 });
-program.command("create").description("create an issue").option("--title <text>", "issue title (required)").option("--description <text>", "problem statement").option("--design <text>", "design notes").option("--notes <text>", "working notes").option("--acceptance <text>", "acceptance criteria").option("--type <type>", "task | bug | feature | epic (applied as a type/ label)").option("--priority <name>", "urgent | high | medium | low | none").option("--due-date <date>", "YYYY-MM-DD").option("--parent <id>", "parent epic").option("--assignee <who>", "me, a user id, an email, or a full name").option("--team <key>", "team key (or HARNESS_TEAM)").option("--label <name>", "label to apply (repeatable)", collect, []).option("--json", "emit JSON").action(async (opts) => {
-  await withConfig(opts.json === true, true, (ctx) => create(ctx, opts));
-});
-program.command("update").description("update an issue; --claim takes it atomically").argument("[id]").option("--claim", "claim atomically and move to the first started state").option("--state <name>", "workflow state by name or type").option("--title <text>").option("--description <text>").option("--design <text>").option("--notes <text>", "replace the notes").option("--append-notes <text>", "append to the notes").option("--acceptance <text>").option("--priority <name>", "urgent | high | medium | low | none").option("--due-date <date>", 'YYYY-MM-DD; "" clears').option("--parent <id>").option("--assignee <who>", 'me, a user id, an email, or a full name; "" unassigns').option("--json", "emit JSON").action(async (id, opts) => {
-  await withConfig(opts.json === true, true, (ctx) => {
-    if (id === void 0) {
-      throw new UsageError("usage: harness update <id> --claim | --title \u2026 | --state <name> | \u2026");
-    }
-    requireIdentifiers2([id]);
-    return update(ctx, id, opts);
-  });
-});
-program.command("close").description("close issues; the response lists newly unblocked issues").argument("[ids...]").option("--reason <text>", "why it is done (e.g. the commit hash)").option("--cancel", "close as canceled instead of completed").option("--json", "emit JSON").action(async (ids, opts) => {
-  await withConfig(opts.json === true, true, (ctx) => {
-    if (ids.length === 0) {
-      throw new UsageError("usage: harness close <id> [<id>\u2026] [--reason <text>] [--cancel]");
-    }
-    requireIdentifiers2(ids);
-    return close(ctx, ids, opts);
-  });
-});
-program.command("archive").description("archive issues; --restore brings them back").argument("[ids...]").option("--restore", "restore instead of archive").option("--json", "emit JSON").action(async (ids, opts) => {
-  await withConfig(opts.json === true, true, (ctx) => {
-    if (ids.length === 0) throw new UsageError("usage: harness archive <id> [<id>\u2026] [--restore]");
-    requireIdentifiers2(ids);
-    return archive(ctx, ids, opts);
-  });
+program.command("create").description("create an issue").option("--title <text>", "issue title (required)").option("--description <text>", "problem statement").option("--design <text>", "design notes").option("--notes <text>", "working notes").option("--acceptance <text>", "acceptance criteria").option(
+  "--type <type>",
+  "task | bug | feature | epic (applied as a type/ label)"
+).option("--priority <name>", "urgent | high | medium | low | none").option("--due-date <date>", "YYYY-MM-DD").option("--parent <id>", "parent epic").option("--assignee <who>", "me, a user id, an email, or a full name").option("--team <key>", "team key (or HARNESS_TEAM)").option("--label <name>", "label to apply (repeatable)", collect, []).option("--json", "emit JSON").action(async (opts) => {
+  await withConfig(
+    opts.json === true,
+    true,
+    (ctx) => create(ctx, opts)
+  );
 });
+program.command("update").description("update an issue; --claim takes it atomically").argument("[id]").option("--claim", "claim atomically and move to the first started state").option("--state <name>", "workflow state by name or type").option("--title <text>").option("--description <text>").option("--design <text>").option("--notes <text>", "replace the notes").option("--append-notes <text>", "append to the notes").option("--acceptance <text>").option("--priority <name>", "urgent | high | medium | low | none").option("--due-date <date>", 'YYYY-MM-DD; "" clears').option("--parent <id>").option(
+  "--assignee <who>",
+  'me, a user id, an email, or a full name; "" unassigns'
+).option("--json", "emit JSON").action(
+  async (id, opts) => {
+    await withConfig(opts.json === true, true, (ctx) => {
+      if (id === void 0) {
+        throw new UsageError(
+          "usage: harness update <id> --claim | --title \u2026 | --state <name> | \u2026"
+        );
+      }
+      requireIdentifiers2([id]);
+      return update(ctx, id, opts);
+    });
+  }
+);
+program.command("close").description("close issues; the response lists newly unblocked issues").argument("[ids...]").option("--reason <text>", "why it is done (e.g. the commit hash)").option("--cancel", "close as canceled instead of completed").option("--json", "emit JSON").action(
+  async (ids, opts) => {
+    await withConfig(opts.json === true, true, (ctx) => {
+      if (ids.length === 0) {
+        throw new UsageError(
+          "usage: harness close <id> [<id>\u2026] [--reason <text>] [--cancel]"
+        );
+      }
+      requireIdentifiers2(ids);
+      return close(ctx, ids, opts);
+    });
+  }
+);
+program.command("archive").description("archive issues; --restore brings them back").argument("[ids...]").option("--restore", "restore instead of archive").option("--json", "emit JSON").action(
+  async (ids, opts) => {
+    await withConfig(opts.json === true, true, (ctx) => {
+      if (ids.length === 0)
+        throw new UsageError(
+          "usage: harness archive <id> [<id>\u2026] [--restore]"
+        );
+      requireIdentifiers2(ids);
+      return archive(ctx, ids, opts);
+    });
+  }
+);
 program.command("comments").description("an issue's full comment thread, untruncated").argument("[id]").option("--json", "emit JSON").action(async (id, opts) => {
   await withConfig(opts.json === true, false, (ctx) => {
-    if (id === void 0) throw new UsageError("usage: harness comments <id>");
+    if (id === void 0)
+      throw new UsageError("usage: harness comments <id>");
     requireIdentifiers2([id]);
     return comments(ctx, id);
   });
 });
-program.command("dep").description("blocking dependencies: dep add|rm <issue> <blocker>").argument("[verb]").argument("[issue]").argument("[blocker]").option("--json", "emit JSON").action(async (verb, issue, blocker, opts) => {
-  await withConfig(opts.json === true, true, (ctx) => {
-    if (verb === void 0 || issue === void 0 || blocker === void 0) {
-      throw new UsageError("usage: harness dep add|rm <issue> <blocker>");
-    }
-    requireIdentifiers2([issue, blocker]);
-    return dep(ctx, verb, issue, blocker);
-  });
-});
-program.command("comment").description("comment on an issue").argument("[id]").argument("[text...]").option("--mention <name>", "notify a person (repeatable)", collect, []).option("--json", "emit JSON").action(async (id, text, opts) => {
-  await withConfig(opts.json === true, true, (ctx) => {
-    if (id === void 0 || text.length === 0) {
-      throw new UsageError("usage: harness comment <id> <text> [--mention NAME]\u2026");
-    }
-    requireIdentifiers2([id]);
-    const mentions = opts.mention.filter((name) => name.trim() !== "");
-    return comment(ctx, id, text, mentions);
-  });
-});
+program.command("dep").description("blocking dependencies: dep add|rm <issue> <blocker>").argument("[verb]").argument("[issue]").argument("[blocker]").option("--json", "emit JSON").action(
+  async (verb, issue, blocker, opts) => {
+    await withConfig(opts.json === true, true, (ctx) => {
+      if (verb === void 0 || issue === void 0 || blocker === void 0) {
+        throw new UsageError("usage: harness dep add|rm <issue> <blocker>");
+      }
+      requireIdentifiers2([issue, blocker]);
+      return dep(ctx, verb, issue, blocker);
+    });
+  }
+);
+program.command("comment").description("comment on an issue").argument("[id]").argument("[text...]").option("--mention <name>", "notify a person (repeatable)", collect, []).option("--json", "emit JSON").action(
+  async (id, text, opts) => {
+    await withConfig(opts.json === true, true, (ctx) => {
+      if (id === void 0 || text.length === 0) {
+        throw new UsageError(
+          "usage: harness comment <id> <text> [--mention NAME]\u2026"
+        );
+      }
+      requireIdentifiers2([id]);
+      const mentions = opts.mention.filter((name) => name.trim() !== "");
+      return comment(ctx, id, text, mentions);
+    });
+  }
+);
 program.command("attach-image").description("upload an image; prints markdown to reference it").argument("[path]").option("--json", "emit JSON").action(async (path, opts) => {
   await withConfig(opts.json === true, true, (ctx) => {
     if (path === void 0) {
-      throw new UsageError("usage: harness attach-image <path>  (one png, jpg, webp or gif, up to 25 MB)");
+      throw new UsageError(
+        "usage: harness attach-image <path>  (one png, jpg, webp or gif, up to 25 MB)"
+      );
     }
     return attachImage(ctx, path);
   });
 });
 var project = program.command("project").description("projects");
 project.command("list").option("--search <query>", "full-text search").option("--state <state>", "project state filter").option("--limit <n>", "page size", integer).option("--page <n>", "page number", integer).option("--all", "follow every page").option("--json", "emit JSON").action(async (opts) => {
-  await withConfig(opts.json === true, false, (ctx) => projectList(ctx, opts));
+  await withConfig(
+    opts.json === true,
+    false,
+    (ctx) => projectList(ctx, opts)
+  );
 });
 project.command("show").argument("[id]").option("--json", "emit JSON").action(async (id, opts) => {
   await withConfig(opts.json === true, false, (ctx) => {
-    if (id === void 0) throw new UsageError("usage: harness project show <id>");
+    if (id === void 0)
+      throw new UsageError("usage: harness project show <id>");
     return projectShow(ctx, id);
   });
 });
 project.command("create").option("--name <name>", "project name (required)").option("--description <text>").option("--summary <text>").option("--state <state>").option("--lead <user-id>", "lead by user id").option("--start-date <date>", "YYYY-MM-DD").option("--target-date <date>", "YYYY-MM-DD").option("--json", "emit JSON").action(async (opts) => {
-  await withConfig(opts.json === true, true, (ctx) => projectCreate(ctx, opts));
-});
-project.command("update").argument("[id]").option("--name <name>").option("--description <text>").option("--summary <text>").option("--state <state>").option("--lead <user-id>", "lead by user id").option("--start-date <date>", 'YYYY-MM-DD; "" clears').option("--target-date <date>", 'YYYY-MM-DD; "" clears').option("--json", "emit JSON").action(async (id, opts) => {
-  await withConfig(opts.json === true, true, (ctx) => {
-    if (id === void 0) throw new UsageError("usage: harness project update <id> --name \u2026 | --state \u2026 | \u2026");
-    return projectUpdate(ctx, id, opts);
-  });
+  await withConfig(
+    opts.json === true,
+    true,
+    (ctx) => projectCreate(ctx, opts)
+  );
 });
+project.command("update").argument("[id]").option("--name <name>").option("--description <text>").option("--summary <text>").option("--state <state>").option("--lead <user-id>", "lead by user id").option("--start-date <date>", 'YYYY-MM-DD; "" clears').option("--target-date <date>", 'YYYY-MM-DD; "" clears').option("--json", "emit JSON").action(
+  async (id, opts) => {
+    await withConfig(opts.json === true, true, (ctx) => {
+      if (id === void 0)
+        throw new UsageError(
+          "usage: harness project update <id> --name \u2026 | --state \u2026 | \u2026"
+        );
+      return projectUpdate(ctx, id, opts);
+    });
+  }
+);
 var milestone = program.command("milestone").description("project milestones");
 milestone.command("list").option("--project <id>", "project id (required)").option("--json", "emit JSON").action(async (opts) => {
-  await withConfig(opts.json === true, false, (ctx) => milestoneList(ctx, opts.project));
+  await withConfig(
+    opts.json === true,
+    false,
+    (ctx) => milestoneList(ctx, opts.project)
+  );
 });
 milestone.command("create").option("--project <id>", "project id (required)").option("--name <name>", "milestone name (required)").option("--description <text>").option("--target-date <date>", "YYYY-MM-DD").option("--json", "emit JSON").action(async (opts) => {
-  await withConfig(opts.json === true, true, (ctx) => milestoneCreate(ctx, opts));
+  await withConfig(
+    opts.json === true,
+    true,
+    (ctx) => milestoneCreate(ctx, opts)
+  );
 });
 var doc = program.command("doc").description("documents");
 doc.command("list").option("--search <query>", "full-text search").option("--limit <n>", "page size", integer).option("--page <n>", "page number", integer).option("--all", "follow every page").option("--json", "emit JSON").action(async (opts) => {
-  await withConfig(opts.json === true, false, (ctx) => docList(ctx, opts));
+  await withConfig(
+    opts.json === true,
+    false,
+    (ctx) => docList(ctx, opts)
+  );
 });
 doc.command("show").argument("[id]").option("--json", "emit JSON").action(async (id, opts) => {
   await withConfig(opts.json === true, false, (ctx) => {
-    if (id === void 0) throw new UsageError("usage: harness doc show <id>");
+    if (id === void 0)
+      throw new UsageError("usage: harness doc show <id>");
     return docShow(ctx, id);
   });
 });
 doc.command("create").option("--title <title>", "document title (required)").option("--content <text>").option("--project <id>", "attach to a project").option("--json", "emit JSON").action(async (opts) => {
-  await withConfig(opts.json === true, true, (ctx) => docCreate(ctx, opts));
-});
-doc.command("update").argument("[id]").option("--title <title>").option("--content <text>").option("--project <id>").option("--json", "emit JSON").action(async (id, opts) => {
-  await withConfig(opts.json === true, true, (ctx) => {
-    if (id === void 0) throw new UsageError("usage: harness doc update <id> --title \u2026 | --content \u2026 | --project \u2026");
-    return docUpdate(ctx, id, opts);
-  });
+  await withConfig(
+    opts.json === true,
+    true,
+    (ctx) => docCreate(ctx, opts)
+  );
 });
+doc.command("update").argument("[id]").option("--title <title>").option("--content <text>").option("--project <id>").option("--json", "emit JSON").action(
+  async (id, opts) => {
+    await withConfig(opts.json === true, true, (ctx) => {
+      if (id === void 0)
+        throw new UsageError(
+          "usage: harness doc update <id> --title \u2026 | --content \u2026 | --project \u2026"
+        );
+      return docUpdate(ctx, id, opts);
+    });
+  }
+);
 var link = program.command("link").description("URLs attached to an issue (distinct from dep relations)");
 link.command("list").argument("[issue]").option("--json", "emit JSON").action(async (issue, opts) => {
   await withConfig(opts.json === true, false, (ctx) => {
-    if (issue === void 0) throw new UsageError("usage: harness link list <issue>");
+    if (issue === void 0)
+      throw new UsageError("usage: harness link list <issue>");
     requireIdentifiers2([issue]);
     return linkList(ctx, issue);
   });
 });
-link.command("add").argument("[issue]").argument("[url]").option("--title <title>", "link title").option("--json", "emit JSON").action(async (issue, url, opts) => {
-  await withConfig(opts.json === true, true, (ctx) => {
-    if (issue === void 0 || url === void 0) {
-      throw new UsageError("usage: harness link add <issue> <url> [--title <title>]");
-    }
-    requireIdentifiers2([issue]);
-    return linkAdd(ctx, issue, url, opts.title);
-  });
-});
-link.command("rm").argument("[issue]").argument("[id-or-url]").option("--json", "emit JSON").action(async (issue, idOrUrl, opts) => {
-  await withConfig(opts.json === true, true, (ctx) => {
-    if (issue === void 0 || idOrUrl === void 0) {
-      throw new UsageError("usage: harness link rm <issue> <link-id-or-url>");
-    }
-    requireIdentifiers2([issue]);
-    return linkRm(ctx, issue, idOrUrl);
-  });
-});
+link.command("add").argument("[issue]").argument("[url]").option("--title <title>", "link title").option("--json", "emit JSON").action(
+  async (issue, url, opts) => {
+    await withConfig(opts.json === true, true, (ctx) => {
+      if (issue === void 0 || url === void 0) {
+        throw new UsageError(
+          "usage: harness link add <issue> <url> [--title <title>]"
+        );
+      }
+      requireIdentifiers2([issue]);
+      return linkAdd(ctx, issue, url, opts.title);
+    });
+  }
+);
+link.command("rm").argument("[issue]").argument("[id-or-url]").option("--json", "emit JSON").action(
+  async (issue, idOrUrl, opts) => {
+    await withConfig(opts.json === true, true, (ctx) => {
+      if (issue === void 0 || idOrUrl === void 0) {
+        throw new UsageError(
+          "usage: harness link rm <issue> <link-id-or-url>"
+        );
+      }
+      requireIdentifiers2([issue]);
+      return linkRm(ctx, issue, idOrUrl);
+    });
+  }
+);
 var label = program.command("label").description("labels");
 label.command("list").option("--json", "emit JSON").action(async (opts) => {
-  await withConfig(opts.json === true, false, (ctx) => labelList(ctx));
-});
-label.command("create").argument("[name]").option("--color <color>", "label color").option("--json", "emit JSON").action(async (name, opts) => {
-  await withConfig(opts.json === true, true, (ctx) => labelCreate(ctx, name, opts.color));
+  await withConfig(
+    opts.json === true,
+    false,
+    (ctx) => labelList(ctx)
+  );
 });
+label.command("create").argument("[name]").option("--color <color>", "label color").option("--json", "emit JSON").action(
+  async (name, opts) => {
+    await withConfig(
+      opts.json === true,
+      true,
+      (ctx) => labelCreate(ctx, name, opts.color)
+    );
+  }
+);
 var team = program.command("team").description("teams");
 team.command("list").option("--json", "emit JSON").action(async (opts) => {
-  await withConfig(opts.json === true, false, (ctx) => teamList(ctx));
+  await withConfig(
+    opts.json === true,
+    false,
+    (ctx) => teamList(ctx)
+  );
 });
-team.command("create").description("create a team, seeded with the default workflow states").option("--key <key>", "identifier prefix for the team's issues, e.g. IOS (required)").option("--name <name>", "display name (required)").option("--json", "emit JSON").action(async (opts) => {
-  await withConfig(opts.json === true, true, (ctx) => teamCreate(ctx, opts));
+team.command("create").description("create a team, seeded with the default workflow states").option(
+  "--key <key>",
+  "identifier prefix for the team's issues, e.g. IOS (required)"
+).option("--name <name>", "display name (required)").option("--json", "emit JSON").action(async (opts) => {
+  await withConfig(
+    opts.json === true,
+    true,
+    (ctx) => teamCreate(ctx, opts)
+  );
 });
 program.command("states").description("a team's workflow states").option("--team <key>", "team key (or HARNESS_TEAM)").option("--json", "emit JSON").action(async (opts) => {
-  await withConfig(opts.json === true, false, (ctx) => workflowStates(ctx, opts.team));
+  await withConfig(
+    opts.json === true,
+    false,
+    (ctx) => workflowStates(ctx, opts.team)
+  );
 });
 var user = program.command("user").description("users");
 user.command("list").option("--json", "emit JSON").action(async (opts) => {
-  await withConfig(opts.json === true, false, (ctx) => userList(ctx));
+  await withConfig(
+    opts.json === true,
+    false,
+    (ctx) => userList(ctx)
+  );
 });
 program.command("upload").description("upload a file; prints markdown to reference it").argument("[path]").option("--json", "emit JSON").action(async (path, opts) => {
   await withConfig(opts.json === true, true, (ctx) => {
-    if (path === void 0) throw new UsageError("usage: harness upload <path>  (png/jpg/webp/gif, up to 25 MB)");
+    if (path === void 0)
+      throw new UsageError(
+        "usage: harness upload <path>  (png/jpg/webp/gif, up to 25 MB)"
+      );
     return upload(ctx, path);
   });
 });
 program.command("mcp").description("run the MCP server over stdio (for agents)").action(async () => {
-  const { startMcpServer } = await import("./server-TK2KFAOQ.js");
+  const { startMcpServer } = await import("./server-LJXJLWNK.js");
   await startMcpServer();
 });
-program.command("login").description("sign in via the browser (infra.one session)").option("--url <url>", "host to sign in to").option("--no-browser", "print the URL and prompt for a pasted token instead").option("--timeout <ms>", "how long to wait for the browser callback", integer).option("--json", "emit JSON").action(async (opts) => {
-  const repoLookup = findRepoConfig();
-  for (const warning of repoLookup.warnings) process.stderr.write(warning + "\n");
-  const repoUrl = repoLookup.config?.url;
-  const url = opts.url ?? blankToUndefined(process.env["HARNESS_API_URL"]) ?? repoUrl ?? storedLoginUrl() ?? DEFAULT_BASE_URL;
-  if (url === repoUrl && opts.url === void 0 && blankToUndefined(process.env["HARNESS_API_URL"]) === void 0) {
-    process.stderr.write(`harness: host ${url} comes from ${repoLookup.config?.path}
-`);
+program.command("login").description("sign in via the browser (infra.one session)").option("--url <url>", "host to sign in to").option("--no-browser", "print the URL and prompt for a pasted token instead").option(
+  "--timeout <ms>",
+  "how long to wait for the browser callback",
+  integer
+).option("--json", "emit JSON").action(
+  async (opts) => {
+    const repoLookup = findRepoConfig();
+    for (const warning of repoLookup.warnings)
+      process.stderr.write(warning + "\n");
+    const repoUrl = repoLookup.config?.url;
+    const url = opts.url ?? blankToUndefined(process.env["HARNESS_API_URL"]) ?? repoUrl ?? storedLoginUrl() ?? DEFAULT_BASE_URL;
+    if (url === repoUrl && opts.url === void 0 && blankToUndefined(process.env["HARNESS_API_URL"]) === void 0) {
+      process.stderr.write(
+        `harness: host ${url} comes from ${repoLookup.config?.path}
+`
+      );
+    }
+    const options = { noBrowser: !opts.browser };
+    if (opts.timeout !== void 0) options.timeoutMs = opts.timeout;
+    await finishAuth(await login(url, options), opts.json === true);
   }
-  const options = { noBrowser: !opts.browser };
-  if (opts.timeout !== void 0) options.timeoutMs = opts.timeout;
-  await finishAuth(await login(url, options), opts.json === true);
-});
+);
 program.command("logout").description("revoke and forget the stored login").option("--json", "emit JSON").action(async (opts) => {
   await finishAuth(await logout(), opts.json === true);
 });
 program.command("whoami").description("show the resolved host and credential source").option("--json", "emit JSON").action(async (opts) => {
   const resolved = resolveConfig();
-  for (const warning of resolved.warnings) process.stderr.write(warning + "\n");
+  for (const warning of resolved.warnings)
+    process.stderr.write(warning + "\n");
   if (resolved.kind === "error") {
     process.stderr.write(`harness: ${resolved.message}
 `);

package/dist/{server-TK2KFAOQ.js → server-LJXJLWNK.js}

@@ -30,6 +30,7 @@ import {
   projectUpdate,
   ready,
   resolveConfig,
+  search,
   show,
   stats,
   teamCreate,
@@ -38,7 +39,7 @@ import {
   upload,
   userList,
   workflowStates
-} from "./chunk-3WR6YFU6.js";
+} from "./chunk-MF7MQ2L6.js";
 
 // src/mcp/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -116,6 +117,19 @@ var TOOLS = [
       return list(ctx, args);
     }
   },
+  {
+    name: "issue_search",
+    description: "Search issues by meaning: ranked results across a lexical and a semantic signal, so describing a problem in your own words finds issues that share none of them. Pass the question as asked \u2014 plain language works better than keywords. An exact identifier always ranks first. Returns at most 20 results, no pagination; use issue_list with search for paginated lexical filtering.",
+    readOnly: true,
+    shape: {
+      query: z.string().describe("the question or phrase to search for"),
+      limit: z.number().int().optional().describe("maximum results (default 10, capped at 20)")
+    },
+    handler: (ctx, args) => {
+      const limit = args["limit"] === void 0 ? {} : { limit: args["limit"] };
+      return search(ctx, [String(args["query"])], limit);
+    }
+  },
   {
     name: "issue_show",
     description: "Full issue detail: fields, relations, children, comments. images=true downloads attached images to the local cache and includes their paths as local_images.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allocator-one/harness-cli",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "CLI and MCP server for Harness, allocator.one's issue tracker",
   "type": "module",
   "license": "MIT",

package/spec/openapi.json

@@ -517,6 +517,55 @@
         "tags": []
       }
     },
+    "/api/v1/issues/search": {
+      "get": {
+        "callbacks": {},
+        "deprecated": false,
+        "description": "Requires the `harness:read` scope. Ranked hybrid search: an exact identifier always comes first, then results ordered by relevance across a lexical and a semantic (embedding) signal — a query can match issues that share none of its words. Returns at most 20 results; there is no pagination. `meta.mode` is `hybrid` when the semantic side ran and `lexical` when it degraded (embeddings disabled or the provider unavailable). Unarchived issues only. For paginated, filterable listings use `GET /api/v1/issues` instead.",
+        "parameters": [
+          {
+            "description": "The question or phrase to search for — plain language works better than keywords",
+            "in": "query",
+            "name": "q",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "description": "Maximum results (default 10, capped at 20)",
+            "in": "query",
+            "name": "limit",
+            "required": false,
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success"
+          },
+          "400": {
+            "description": "Bad request"
+          },
+          "401": {
+            "description": "Missing or invalid token"
+          },
+          "403": {
+            "description": "Token not permitted (org-scoped, non-admin, or missing scope)"
+          },
+          "404": {
+            "description": "Not found"
+          },
+          "422": {
+            "description": "Validation error"
+          }
+        },
+        "summary": "Search issues by meaning",
+        "tags": []
+      }
+    },
     "/api/v1/issues/{identifier}": {
       "get": {
         "callbacks": {},
@@ -524,7 +573,7 @@
         "description": "Requires the `harness:read` scope. The payload always carries `blocked` and `blocked_by` (identifiers of open blockers); `include` embeds relations (direction-aware), children, and recent comments in one response.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -571,7 +620,7 @@
         "description": "Requires the `harness:write` scope.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -656,7 +705,7 @@
         "description": "Requires the `harness:write` scope.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -711,7 +760,7 @@
         "description": "Requires the `harness:write` scope. Atomic compare-and-swap: assigns the caller and moves the issue to the team's first started-type state. Idempotent for the current claimant.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -754,7 +803,7 @@
         "description": "Requires the `harness:write` scope. Moves the issue to the team's first completed-type state (canceled-type with `cancel`), posting `reason` as a comment first. The response's `unblocked` lists identifiers of issues that became ready because this one closed.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -818,7 +867,7 @@
         "description": "Requires the `harness:read` scope.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -856,7 +905,7 @@
         "description": "Requires the `harness:write` scope.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -915,7 +964,7 @@
         "description": "Requires the `harness:write` scope.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -973,7 +1022,7 @@
         "description": "Requires the `harness:read` scope.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -1011,7 +1060,7 @@
         "description": "Requires the `harness:write` scope.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -1070,7 +1119,7 @@
         "description": "Requires the `harness:write` scope.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -1119,7 +1168,7 @@
         "description": "Requires the `harness:read` scope.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -1157,7 +1206,7 @@
         "description": "Requires the `harness:write` scope.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -1225,7 +1274,7 @@
         "description": "Requires the `harness:write` scope.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -1274,7 +1323,7 @@
         "description": "Requires the `harness:write` scope.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -1870,7 +1919,7 @@
       "post": {
         "callbacks": {},
         "deprecated": false,
-        "description": "Requires the `harness:write` scope. Creates a team seeded with the default workflow states (Backlog, Todo, In Progress, Done, Canceled), so it is immediately usable for the full issue lifecycle. The key is upcased, must match `^[A-Z][A-Z0-9]*$`, and `IO` is reserved for the issues Harness mints.",
+        "description": "Requires the `harness:write` scope. Creates a team seeded with the default workflow states (Backlog, Todo, In Progress, Done, Canceled), so it is immediately usable for the full issue lifecycle. The key is upcased and must match `^[A-Z][A-Z0-9]*$`; numbering starts above any issues that already carry the key as their prefix.",
         "parameters": [],
         "requestBody": {
           "content": {
@@ -1878,7 +1927,7 @@
               "schema": {
                 "properties": {
                   "key": {
-                    "description": "Identifier prefix for issues imported under the team (e.g. ALL). Upcased; create-only.",
+                    "description": "Identifier prefix for the team's issues (e.g. ALL in ALL-4901). Upcased; create-only.",
                     "type": "string"
                   },
                   "name": {
@@ -2143,4 +2192,4 @@
   ],
   "servers": [],
   "tags": []
-}
+}