@brunyee-studio/onus-cli 2.30.0 → 2.31.0

package/README.md

@@ -204,12 +204,31 @@ onus project create --name <name> --team <teamId> [--status <status>] [--priorit
 onus project update <id> [--name <name>] [--status <status>] [--priority <priority>] [--lead <leadId>] [--target-date <date>] [--description <text>] [--description-file <path>] [--agent-context <text>] [--agent-context-file <path>] [--json]
 ```
 
+### `onus kb`
+
+Read-only knowledge base access: no write verbs exist under `onus kb`.
+
+```bash
+onus kb list [--team <id|KEY> | --project <id> | --repo <id>] [--kind <kind>] [--tag <tag>] [--limit <n>] [--cursor <cursor>] [--json]
+onus kb get <slug-or-id> [--json]
+onus kb search <query> [--mode <mode>] [--doc <slug-or-id>] [--limit <n>] [--json]
+onus kb related <slug-or-id> [--json]
+onus kb locate [--issue <issueId> | --query <text>] [--json]
+```
+
+`--kind` accepts `index | area | process | incident`; `--mode` accepts
+`string | semantic | hybrid | related` (default `string`; `related` requires
+`--doc`). Doc refs are slugs or UUIDs — slugs are unique per owner, so an
+ambiguous slug lists its candidate owners and exits 2; pass the doc UUID to
+resolve unambiguously. List rows and detail carry the staleness verdict
+(`stale`, `confidence`, `reason`).
+
 ### `onus issue`
 
 Issues are addressed by human reference (`ENG-42`); UUIDs are also accepted.
 
 ```bash
-onus issue list [--team <id>] [--project <id>] [--assignee <id>] [--parent <id>] [--status <status>] [--q <query>] [--limit <n>] [--cursor <cursor>] [--json]
+onus issue list [--team <id>] [--project <id>] [--assignee <id>] [--parent <id>] [--status <status>] [--priority <priority>] [--q <query>] [--limit <n>] [--cursor <cursor>] [--json]
 onus issue get <ref> [--json]
 onus issue create --title <title> --team <teamId> [-d <description>] [--description-file <path>] [--status <status>] [--priority <priority>] [--assignee <id>] [--project <id>] [--parent <id>] [--label <labelId>] [--json]
 onus issue update <ref> [--title <title>] [-d <description>] [--description-file <path>] [--status <status>] [--priority <priority>] [--assignee <id>] [--project <id>] [--parent <id>] [--add-label <labelId>] [--remove-label <labelId>] [--json]

package/dist/bin.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 import {
+  IssueListItemStatusEnum,
+  IssuesGetPriorityEnum,
   cliVersion,
   createApiClient,
   loginWithOAuth
-} from "./chunk-HJQGUY5T.js";
+} from "./chunk-35HNSEP2.js";
 import {
   clearConfig,
   getConfigDirectory,
@@ -786,7 +788,243 @@ function registerProjectCommands(program2) {
 // src/commands/issue.ts
 import { readFileSync as readFileSync2, statSync, writeFileSync } from "fs";
 import { basename } from "path";
+
+// src/search-query.ts
+var ME = "__me__";
+var QUERY_ATTRIBUTES = ["status", "priority", "assignee", "label", "project"];
+var QUERY_ATTRIBUTE_SET = new Set(QUERY_ATTRIBUTES);
 var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var ISSUE_STATUSES = new Set(Object.values(IssueListItemStatusEnum));
+var ISSUE_PRIORITIES = new Set(Object.values(IssuesGetPriorityEnum));
+function isIssuePriority(value) {
+  return ISSUE_PRIORITIES.has(value);
+}
+function canonicalEnumValue(value) {
+  return value.toLowerCase().replace(/[\s-]+/g, "_");
+}
+function mapTokenValues(attribute, values) {
+  if (attribute === "assignee") {
+    return {
+      clause: values.flatMap((v) => {
+        if (v.toLowerCase() === "me") return [ME];
+        return v === ME ? [] : [v];
+      }),
+      text: []
+    };
+  }
+  if (attribute === "status" || attribute === "priority") {
+    const isValidEnum = attribute === "status" ? ISSUE_STATUSES : ISSUE_PRIORITIES;
+    const clause2 = [];
+    const text = [];
+    for (const value of values) {
+      const canonical = canonicalEnumValue(value);
+      if (isValidEnum.has(canonical)) clause2.push(canonical);
+      else text.push(value);
+    }
+    return { clause: clause2, text };
+  }
+  return { clause: [...values], text: [] };
+}
+function tokenize(input) {
+  const tokens = [];
+  let i = 0;
+  while (i < input.length) {
+    if (/\s/.test(input.charAt(i))) {
+      i += 1;
+      continue;
+    }
+    if (input.charAt(i) === '"') {
+      const end = input.indexOf('"', i + 1);
+      if (end === -1) {
+        tokens.push({ kind: "text", value: input.slice(i + 1) });
+        break;
+      }
+      if (end > i + 1) tokens.push({ kind: "text", value: input.slice(i + 1, end) });
+      i = end + 1;
+      continue;
+    }
+    let j = i;
+    while (j < input.length && !/\s/.test(input.charAt(j))) j += 1;
+    let run = input.slice(i, j);
+    const colon = run.indexOf(":");
+    const attribute = colon > 0 ? run.slice(0, colon).toLowerCase() : "";
+    if (colon > 0 && run.charAt(colon + 1) === '"') {
+      const close = input.indexOf('"', i + colon + 2);
+      if (close !== -1) {
+        j = close + 1;
+        while (j < input.length && !/\s/.test(input.charAt(j))) j += 1;
+        run = input.slice(i, j);
+      }
+    }
+    if (QUERY_ATTRIBUTE_SET.has(attribute) && run.endsWith(",")) {
+      for (; ; ) {
+        let k = j;
+        while (k < input.length && /\s/.test(input.charAt(k))) k += 1;
+        if (k >= input.length || input.charAt(k) === '"') break;
+        let n = k;
+        while (n < input.length && !/\s/.test(input.charAt(n)) && input.charAt(n) !== ":") n += 1;
+        if (input.charAt(n) === ":") break;
+        let m = k;
+        while (m < input.length && !/\s/.test(input.charAt(m))) m += 1;
+        run += input.slice(j, m);
+        j = m;
+        if (!input.slice(k, m).endsWith(",")) break;
+      }
+    }
+    const rawValues = colon > 0 ? run.slice(colon + 1) : "";
+    const trimmedRaw = rawValues.trim();
+    const fullyQuoted = trimmedRaw.length >= 2 && trimmedRaw.startsWith('"') && trimmedRaw.endsWith('"');
+    let parts = fullyQuoted ? [trimmedRaw.slice(1, -1)] : rawValues.split(",");
+    if (!fullyQuoted) {
+      const merged = [];
+      for (const segment of parts) {
+        const last = merged[merged.length - 1];
+        if (last !== void 0 && last.startsWith('"') && (last.match(/"/g)?.length ?? 0) % 2 === 1) {
+          merged[merged.length - 1] = `${last},${segment}`;
+        } else {
+          merged.push(segment);
+        }
+      }
+      parts = merged;
+    }
+    const values = parts.map((v) => v.trim().replace(/^"(.*)"$/, "$1")).filter((v) => v.length > 0);
+    if (QUERY_ATTRIBUTE_SET.has(attribute) && values.length > 0) {
+      const mapped = mapTokenValues(attribute, values);
+      if (mapped.clause.length > 0) {
+        tokens.push({
+          kind: "clause",
+          attribute,
+          values: mapped.clause
+        });
+      }
+      for (const degraded of mapped.text) {
+        tokens.push({ kind: "text", value: degraded, degraded: true });
+      }
+      if (mapped.clause.length === 0 && mapped.text.length === 0) {
+        tokens.push({ kind: "text", value: run });
+      }
+    } else {
+      tokens.push({ kind: "text", value: run });
+    }
+    i = j;
+  }
+  return tokens;
+}
+function parseSearchQuery(input) {
+  if (input.trim().length === 0) return { clauses: [], text: "" };
+  const valuesByAttribute = /* @__PURE__ */ new Map();
+  const textParts = [];
+  const degradedParts = [];
+  for (const token of tokenize(input)) {
+    if (token.kind === "text") {
+      if (token.value.length > 0) {
+        textParts.push(token.value);
+        if (token.degraded) degradedParts.push(token.value);
+      }
+      continue;
+    }
+    const existing = valuesByAttribute.get(token.attribute) ?? [];
+    for (const value of token.values) {
+      if (!existing.includes(value)) existing.push(value);
+    }
+    valuesByAttribute.set(token.attribute, existing);
+  }
+  const clauseList = [];
+  for (const attribute of QUERY_ATTRIBUTES) {
+    const values = valuesByAttribute.get(attribute);
+    if (values) clauseList.push({ attribute, values });
+  }
+  return {
+    clauses: clauseList,
+    text: textParts.join(" "),
+    // Present only when non-empty (same shape convention as degradedTerms).
+    ...degradedParts.length > 0 ? { degraded: degradedParts } : {}
+  };
+}
+function nonEmptyFlag(value) {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : void 0;
+}
+function issueListQueryLookupsNeeded(parsed, flags) {
+  const assignee = nonEmptyFlag(flags.assignee) ? void 0 : clause(parsed, "assignee");
+  const project = nonEmptyFlag(flags.project) ? void 0 : clause(parsed, "project");
+  return {
+    // Multi-value clauses degrade to text without reading the viewer id, so
+    // only the single-value case warrants the `me` lookup.
+    viewerId: assignee?.values.length === 1 && assignee.values[0] === ME,
+    projects: project?.values.length === 1 && !UUID_RE.test(project.values[0] ?? "")
+  };
+}
+function clause(parsed, attribute) {
+  return parsed.clauses.find((c) => c.attribute === attribute);
+}
+function resolveAssigneeParam(assigneeClause, lookups, degraded) {
+  if (!assigneeClause) return void 0;
+  if (assigneeClause.values.length !== 1) {
+    degraded.push(...assigneeClause.values.map((v) => v === ME ? "me" : v));
+    return void 0;
+  }
+  const value = assigneeClause.values[0] ?? "";
+  if (value === ME) {
+    if (lookups.viewerId) return lookups.viewerId;
+    degraded.push("me");
+    return void 0;
+  }
+  if (UUID_RE.test(value)) return value;
+  degraded.push(value);
+  return void 0;
+}
+function resolveProjectParam(projectClause, lookups, degraded) {
+  if (!projectClause) return void 0;
+  if (projectClause.values.length !== 1) {
+    degraded.push(...projectClause.values);
+    return void 0;
+  }
+  const value = projectClause.values[0] ?? "";
+  if (UUID_RE.test(value)) return value;
+  const name = value.toLowerCase();
+  const match = lookups.projects?.find((p) => p.name.toLowerCase() === name);
+  if (match) return match.id;
+  degraded.push(value);
+  return void 0;
+}
+function translateIssueListQuery(parsed, flags, lookups = {}) {
+  const degraded = [];
+  const explicitStatus = nonEmptyFlag(flags.status);
+  const explicitPriority = flags.priority;
+  const explicitAssignee = nonEmptyFlag(flags.assignee);
+  const explicitProject = nonEmptyFlag(flags.project);
+  const explicitQ = nonEmptyFlag(flags.q);
+  const statusClause = explicitStatus ? void 0 : clause(parsed, "status");
+  const assigneeId = explicitAssignee ? void 0 : resolveAssigneeParam(clause(parsed, "assignee"), lookups, degraded);
+  const projectId = explicitProject ? void 0 : resolveProjectParam(clause(parsed, "project"), lookups, degraded);
+  degraded.push(...clause(parsed, "label")?.values ?? []);
+  const priorityValues = explicitPriority ? [] : clause(parsed, "priority")?.values ?? [];
+  const [onlyPriority] = priorityValues;
+  const priority = priorityValues.length === 1 && onlyPriority !== void 0 && isIssuePriority(onlyPriority) ? onlyPriority : void 0;
+  if (priorityValues.length > 1) degraded.push(...priorityValues);
+  const statusValues = statusClause?.values ?? [];
+  const textTerms = explicitQ !== void 0 ? [explicitQ] : [parsed.text];
+  const parseDegraded = parsed.degraded ?? [];
+  const degradedParts = explicitQ !== void 0 ? [...parseDegraded, ...degraded] : degraded;
+  const q = [.../* @__PURE__ */ new Set([...textTerms, ...degradedParts])].filter((p) => p.length > 0).join(" ");
+  const allDegraded = [...parseDegraded, ...degraded];
+  const degradedTerms = allDegraded.length > 0 ? [...new Set(allDegraded)] : void 0;
+  return {
+    status: explicitStatus ?? (statusValues.length > 0 ? statusValues.join(",") : void 0),
+    priority: explicitPriority ?? priority,
+    assigneeId: explicitAssignee ?? assigneeId,
+    projectId: explicitProject ?? projectId,
+    q: q.length > 0 ? q : void 0,
+    // Present only when non-empty; degradation drops filter intent, so
+    // callers can explain empty-looking results.
+    ...degradedTerms ? { degradedTerms } : {}
+  };
+}
+
+// src/commands/issue.ts
+var UUID_RE2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var ISSUE_PRIORITIES2 = Object.values(IssuesGetPriorityEnum);
 var CLEAR_SENTINELS = /* @__PURE__ */ new Set(["null", "none", ""]);
 function isClearSentinel(value) {
   return CLEAR_SENTINELS.has(value.trim().toLowerCase());
@@ -795,7 +1033,7 @@ function collect(value, previous) {
   return [...previous ?? [], value];
 }
 function refToRelationTarget(ref) {
-  return UUID_RE.test(ref) ? { related_issue_id: ref } : { related_issue_ref: ref };
+  return UUID_RE2.test(ref) ? { related_issue_id: ref } : { related_issue_ref: ref };
 }
 var MIME_BY_EXT = {
   ".jpg": "image/jpeg",
@@ -821,9 +1059,104 @@ function contentTypeFor(filename) {
   }
   return "application/octet-stream";
 }
+async function resolveIssueListQueryParams(client, opts, globals, teamId) {
+  if (!opts.query) {
+    return {
+      status: opts.status,
+      priority: opts.priority,
+      assigneeId: opts.assignee,
+      projectId: opts.project,
+      q: opts.q
+    };
+  }
+  const jsonMode = isJsonMode(globals.json);
+  const parsed = parseSearchQuery(opts.query);
+  const flags = {
+    status: opts.status,
+    priority: opts.priority,
+    assignee: opts.assignee,
+    project: opts.project,
+    q: opts.q
+  };
+  const lookups = {};
+  const needed = issueListQueryLookupsNeeded(parsed, flags);
+  const settle = (p) => p.then(
+    (value) => [value, void 0],
+    (err) => [void 0, err]
+  );
+  const describeLookupError = (err) => err instanceof Error ? err.message : String(err);
+  const [viewerResult, projectsResult] = await Promise.all([
+    needed.viewerId ? settle(client.meGet()) : void 0,
+    needed.projects ? settle(client.projectsGet()) : void 0
+  ]);
+  const [viewer, viewerLookupError] = viewerResult ?? [];
+  const [projects, projectsLookupError] = projectsResult ?? [];
+  const lookupFailures = [];
+  if (needed.viewerId && !viewer) {
+    lookupFailures.push({ part: "assignee:me", error: viewerLookupError });
+  }
+  if (needed.projects && !projects) {
+    lookupFailures.push({ part: "project name", error: projectsLookupError });
+  }
+  if (!jsonMode) {
+    for (const { part, error } of lookupFailures) {
+      process.stderr.write(
+        `warning: ${part} lookup failed (${sanitizeTerminal(describeLookupError(error))}); degrading to text search
+`
+      );
+    }
+  }
+  if (viewer) lookups.viewerId = viewer.id;
+  if (projects) {
+    const scoped = teamId ? projects.filter((p) => p.team_id === teamId) : projects;
+    const nameCounts = /* @__PURE__ */ new Map();
+    for (const p of scoped) {
+      const key = p.name.toLowerCase();
+      nameCounts.set(key, (nameCounts.get(key) ?? 0) + 1);
+    }
+    lookups.projects = scoped.filter((p) => (nameCounts.get(p.name.toLowerCase()) ?? 0) === 1).map((p) => ({ id: p.id, name: p.name }));
+  }
+  const translated = translateIssueListQuery(parsed, flags, lookups);
+  if (jsonMode) {
+    const diagnostics = {};
+    if (lookupFailures.length > 0) {
+      diagnostics.lookupFailures = lookupFailures.map(({ part }) => part);
+      diagnostics.lookupErrors = Object.fromEntries(
+        lookupFailures.map(({ part, error }) => [
+          part,
+          sanitizeTerminal(describeLookupError(error))
+        ])
+      );
+    }
+    if (translated.degradedTerms?.length) {
+      diagnostics.degradedTerms = translated.degradedTerms;
+    }
+    if (Object.keys(diagnostics).length > 0) {
+      process.stderr.write(`${JSON.stringify(diagnostics)}
+`);
+    }
+  } else if (translated.degradedTerms?.length) {
+    process.stderr.write(
+      `note: unsupported query parts (${sanitizeTerminal(
+        translated.degradedTerms.join(", ")
+      )}) were added to the text search
+`
+    );
+  }
+  return {
+    status: translated.status,
+    priority: translated.priority,
+    assigneeId: translated.assigneeId,
+    projectId: translated.projectId,
+    q: translated.q
+  };
+}
 function registerIssueCommands(program2) {
   const issue = program2.command("issue").description("Manage Onus issues");
-  issue.command("list").description("List and filter issues").option("-j, --json", "Output raw JSON").option("--team <team>", "Team UUID or KEY (e.g. ONUS)").option("--project <projectId>", "Filter by project UUID").option("--assignee <assigneeId>", "Filter by assignee UUID").option("--parent <parentId>", "Filter by parent issue UUID").option("--status <status>", "Filter by status (backlog|todo|in_progress|done|canceled)").option("--q <query>", "Free-text search query").option(
+  issue.command("list").description("List and filter issues").option("-j, --json", "Output raw JSON").option("--team <team>", "Team UUID or KEY (e.g. ONUS)").option("--project <projectId>", "Filter by project UUID").option("--assignee <assigneeId>", "Filter by assignee UUID").option("--parent <parentId>", "Filter by parent issue UUID").option("--status <status>", "Filter by status (backlog|todo|in_progress|done|canceled)").option("--priority <priority>", `Filter by priority (${ISSUE_PRIORITIES2.join("|")})`).option("--q <query>", "Free-text search query (supports display keys like ONUS-42)").option(
+    "--query <query>",
+    `Structured query mini-syntax, e.g. 'status:todo label:bug "rate limit"' (status/assignee/project and single-value priority map to /v1 filters; label, multi-value priority and unresolvable values degrade to text search; unsupported parts are appended to the text search; attribute values are single tokens (status:in_progress, not in progress) or a quoted span (status:"in progress"); text joins into ONE phrase; explicit --status/--priority/--assignee/--project/--q flags win on conflict)`
+  ).option(
     "--created-after <date>",
     "Inclusive lower bound on created_at (yyyy-MM-dd or ISO datetime)"
   ).option(
@@ -843,16 +1176,30 @@ function registerIssueCommands(program2) {
     "Inclusive upper bound on completed_at (yyyy-MM-dd or ISO datetime)"
   ).option("--due-after <date>", "Inclusive lower bound on due_date (yyyy-MM-dd)").option("--due-before <date>", "Inclusive upper bound on due_date (yyyy-MM-dd)").option("--limit <n>", "Limit result count", (v) => Number(v)).option("--cursor <cursor>", "Pagination cursor").action(async function(opts) {
     const globals = this.optsWithGlobals();
+    if (opts.priority !== void 0 && !ISSUE_PRIORITIES2.includes(opts.priority)) {
+      await handleApiError(
+        {
+          status: 400,
+          json: () => Promise.resolve({
+            error: "invalid_request",
+            message: `Invalid priority: ${sanitizeTerminal(opts.priority)} (valid values: ${ISSUE_PRIORITIES2.join("|")})`
+          })
+        },
+        globals.json
+      );
+    }
     try {
       const client = createApiClient({ token: globals.token, apiUrl: globals.apiUrl });
       const teamId = opts.team ? await resolveTeamId(client, opts.team) : void 0;
+      const resolved = await resolveIssueListQueryParams(client, opts, globals, teamId);
       const response = await client.issuesGet({
-        status: opts.status,
+        status: resolved.status,
+        priority: resolved.priority,
         teamId,
-        assigneeId: opts.assignee,
-        projectId: opts.project,
+        assigneeId: resolved.assigneeId,
+        projectId: resolved.projectId,
         parentId: opts.parent,
-        q: opts.q,
+        q: resolved.q,
         createdAfter: opts.createdAfter,
         createdBefore: opts.createdBefore,
         updatedAfter: opts.updatedAfter,
@@ -883,6 +1230,11 @@ function registerIssueCommands(program2) {
             console.log(`    ${parts.map((p) => sanitizeTerminal(String(p))).join(" \xB7 ")}`);
           }
         }
+        const count = `${items.length} ${items.length === 1 ? "issue" : "issues"}`;
+        console.log(
+          `
+${response?.next_cursor ? `${count} (this page; more available)` : count}`
+        );
         if (response?.next_cursor) {
           console.log(`
 Next cursor: ${sanitizeTerminal(response.next_cursor)}`);
@@ -1065,7 +1417,9 @@ Comments (${issue2.comments.length}):`);
     [
       "onus issue list",
       "onus issue list --status in_progress --team ONUS",
-      "onus issue list --json"
+      "onus issue list --q ONUS-42 --priority high",
+      "onus issue list --json",
+      "onus issue list --query 'assignee:me status:todo,in_progress'"
     ]
   );
   withExamples(
@@ -1638,6 +1992,210 @@ function registerLabelCommands(program2) {
   );
 }
 
+// src/commands/kb.ts
+var DOC_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function docRefError(status, message) {
+  const err = new Error(message);
+  err.status = status;
+  return err;
+}
+async function resolveDocRef(client, ref) {
+  if (DOC_UUID_RE.test(ref)) return ref;
+  const page = await client.kbDocsGet({ slug: ref, limit: 5 });
+  if (page.data.length === 0) {
+    throw docRefError(404, `doc not found: ${ref}`);
+  }
+  if (page.data.length > 1) {
+    const candidates = page.data.map((d) => `  ${d.ownerType}/${d.ownerId}: ${d.slug} \u2014 ${d.title}`).join("\n");
+    throw docRefError(
+      400,
+      `ambiguous slug "${ref}" matches ${page.data.length} docs:
+${candidates}
+Pass the doc UUID to resolve unambiguously.`
+    );
+  }
+  return page.data[0].id;
+}
+function renderResultRows(results) {
+  if (results.length === 0) {
+    console.log("No matching docs.");
+    return;
+  }
+  for (const r of results) {
+    console.log(`\u2022 ${sanitizeTerminal(r.slug)}  ${r.score}  ${sanitizeTerminal(r.title)}`);
+    const parts = [r.kind, `${r.ownerType}/${r.ownerId}`];
+    if (r.matchType) parts.push(r.matchType);
+    if (r.stale) parts.push(`stale (${r.confidence})`);
+    console.log(`    ${parts.map((p) => sanitizeTerminal(String(p))).join(" \xB7 ")}`);
+  }
+}
+function registerKbCommands(program2) {
+  const kb = program2.command("kb").description("Read-only knowledge base docs (list, get, search, related, locate)");
+  kb.command("list").description("List knowledge-base docs (owner/kind/tag filters, keyset pagination)").option("--team <team>", "Owner team UUID or KEY (e.g. ONUS)").option("--project <projectId>", "Owner project UUID").option("--repo <repoId>", "Owner repo UUID").option("--kind <kind>", "Doc kind (index|area|process|incident)").option("--tag <tag>", "Taxonomy tag").option("--limit <n>", "Limit result count (1-100)", (v) => Number(v)).option("--cursor <cursor>", "Pagination cursor").option("-j, --json", "Output raw JSON").action(async function(opts) {
+    const globals = this.optsWithGlobals();
+    if ([opts.team, opts.project, opts.repo].filter(Boolean).length > 1) {
+      console.error("Provide at most one of --team, --project, --repo.");
+      process.exit(2);
+      return;
+    }
+    try {
+      const client = createApiClient({ token: globals.token, apiUrl: globals.apiUrl });
+      const ownerType = opts.team ? "team" : opts.project ? "project" : opts.repo ? "repo" : void 0;
+      const ownerId = opts.team ? await resolveTeamId(client, opts.team) : opts.project ?? opts.repo;
+      const response = await client.kbDocsGet({
+        ownerType,
+        ownerId,
+        kind: opts.kind,
+        tag: opts.tag,
+        limit: opts.limit,
+        cursor: opts.cursor
+      });
+      const items = response.data ?? [];
+      printJsonOrFormatted(response, globals.json, () => {
+        if (items.length === 0) {
+          console.log("No KB docs found.");
+          return;
+        }
+        for (const doc of items) {
+          console.log(`\u2022 ${sanitizeTerminal(doc.slug)}  ${sanitizeTerminal(doc.title)}`);
+          const parts = [doc.kind, `${doc.ownerType}/${doc.ownerId}`, doc.status];
+          if (doc.tags.length > 0) parts.push(doc.tags.join(", "));
+          if (doc.staleness.stale) parts.push(`stale (${doc.staleness.confidence})`);
+          console.log(`    ${parts.map((p) => sanitizeTerminal(String(p))).join(" \xB7 ")}`);
+        }
+        if (response.next_cursor) {
+          console.log(`
+Next cursor: ${sanitizeTerminal(response.next_cursor)}`);
+        }
+      });
+    } catch (err) {
+      await handleApiError(err, globals.json);
+    }
+  });
+  kb.command("get <slug-or-id>").description("Get a KB doc by slug or UUID (content, metadata, staleness)").option("-j, --json", "Output raw JSON").action(async function(ref) {
+    const globals = this.optsWithGlobals();
+    try {
+      const client = createApiClient({ token: globals.token, apiUrl: globals.apiUrl });
+      const id = await resolveDocRef(client, ref);
+      const doc = await client.kbDocsIdGet({ id });
+      printJsonOrFormatted(doc, globals.json, () => {
+        console.log(
+          formatRecord([
+            { label: "ID", value: doc.id },
+            { label: "Slug", value: doc.slug },
+            { label: "Title", value: doc.title },
+            { label: "Kind", value: doc.kind },
+            { label: "Owner", value: `${doc.ownerType}/${doc.ownerId}` },
+            { label: "Tags", value: doc.tags.join(", ") },
+            { label: "Paths governed", value: doc.pathsGoverned.join(", ") },
+            { label: "Source", value: doc.sourceType },
+            { label: "Status", value: doc.status },
+            {
+              label: "Stale",
+              value: `${doc.staleness.stale} (confidence ${doc.staleness.confidence})`
+            },
+            { label: "Stale reason", value: doc.staleness.reason },
+            { label: "Updated", value: doc.updatedAt }
+          ])
+        );
+        if (doc.content) {
+          console.log(`
+Content:
+${sanitizeTerminal(doc.content)}`);
+        }
+      });
+    } catch (err) {
+      await handleApiError(err, globals.json);
+    }
+  });
+  kb.command("search <query>").description("Search KB docs (scored results + snippets)").option("--mode <mode>", "Retrieval mode (string|semantic|hybrid|related)").option("--doc <slug-or-id>", "Seed doc (required with --mode related)").option("--limit <n>", "Limit result count", (v) => Number(v)).option("-j, --json", "Output raw JSON").action(async function(query, opts) {
+    const globals = this.optsWithGlobals();
+    if (opts.mode === "related" && !opts.doc) {
+      console.error("--doc is required when --mode related.");
+      process.exit(2);
+      return;
+    }
+    try {
+      const client = createApiClient({ token: globals.token, apiUrl: globals.apiUrl });
+      const docId = opts.doc ? await resolveDocRef(client, opts.doc) : void 0;
+      const response = await client.kbSearchGet({
+        q: query,
+        mode: opts.mode,
+        docId,
+        limit: opts.limit
+      });
+      printJsonOrFormatted(response, globals.json, () => {
+        console.log(`Mode: ${response.mode}`);
+        renderResultRows(response.results);
+      });
+    } catch (err) {
+      await handleApiError(err, globals.json);
+    }
+  });
+  kb.command("related <slug-or-id>").description("Expand docs related to a seed doc (slug or UUID)").option("-j, --json", "Output raw JSON").action(async function(ref) {
+    const globals = this.optsWithGlobals();
+    try {
+      const client = createApiClient({ token: globals.token, apiUrl: globals.apiUrl });
+      const id = await resolveDocRef(client, ref);
+      const response = await client.kbDocsIdRelatedGet({ id });
+      printJsonOrFormatted(response, globals.json, () => {
+        console.log(`Mode: ${response.mode}`);
+        renderResultRows(response.results);
+      });
+    } catch (err) {
+      await handleApiError(err, globals.json);
+    }
+  });
+  kb.command("locate").description("Locate docs for an issue or free-text query (agent routing)").option("--issue <issueId>", "Issue UUID to route from").option("--query <text>", "Free-text query to route from").option("-j, --json", "Output raw JSON").action(async function(opts) {
+    const globals = this.optsWithGlobals();
+    if ((opts.issue ? 1 : 0) + (opts.query ? 1 : 0) !== 1) {
+      console.error("Provide exactly one of --issue or --query.");
+      process.exit(2);
+      return;
+    }
+    try {
+      const client = createApiClient({ token: globals.token, apiUrl: globals.apiUrl });
+      const response = await client.kbLocateGet({ issue: opts.issue, q: opts.query });
+      printJsonOrFormatted(response, globals.json, () => {
+        console.log(`Mode: ${response.mode}`);
+        renderResultRows(response.results);
+      });
+    } catch (err) {
+      await handleApiError(err, globals.json);
+    }
+  });
+  withExamples(
+    kb.commands.find((c) => c.name() === "list"),
+    [
+      "onus kb list",
+      "onus kb list --team ONUS --kind area --tag auth --json",
+      "onus kb list --cursor <cursor>"
+    ]
+  );
+  withExamples(
+    kb.commands.find((c) => c.name() === "get"),
+    ["onus kb get auth-overview", "onus kb get 44444444-4444-4444-8444-444444444444"]
+  );
+  withExamples(
+    kb.commands.find((c) => c.name() === "search"),
+    [
+      'onus kb search "auth flow" --mode hybrid --limit 10',
+      'onus kb search "runbook" --mode related --doc auth-overview'
+    ]
+  );
+  withExamples(
+    kb.commands.find((c) => c.name() === "related"),
+    ["onus kb related auth-overview"]
+  );
+  withExamples(
+    kb.commands.find((c) => c.name() === "locate"),
+    [
+      "onus kb locate --issue 33333333-3333-4333-8333-333333333333",
+      'onus kb locate --query "how do rotations work"'
+    ]
+  );
+}
+
 // src/commands/dsn.ts
 function registerDsnCommands(program2) {
   const dsn = program2.command("dsn").description("Manage team ingest keys (DSNs) \u2014 errors + analytics ingestion credentials");
@@ -2250,7 +2808,7 @@ function registerWatchCommand(program2) {
     const opts = this.opts();
     let teamId = opts.team;
     if (teamId) {
-      const { createApiClient: createApiClient2 } = await import("./client-QNEDGCP7.js");
+      const { createApiClient: createApiClient2 } = await import("./client-R7T5S6RN.js");
       const client = createApiClient2({ token, apiUrl });
       teamId = await resolveTeamId(client, teamId);
     }
@@ -2275,6 +2833,7 @@ function buildProgram() {
   registerIssueCommands(program2);
   registerCommentCommands(program2);
   registerLabelCommands(program2);
+  registerKbCommands(program2);
   registerDsnCommands(program2);
   registerSkillCommands(program2);
   registerTemplateCommands(program2);