ente-cli 0.4.69 → 0.4.70

package/README.md

@@ -401,3 +401,25 @@ Updating replaces agent assignees and preserves human assignees. Use
 `--clear-agent-assignees` to remove them. Only active agents with write access qualify.
 
 Scheduled runs also accept `runCondition: "new_chats"`: skip model execution unless this agent has new manual or recording chats since its previous scheduled check. Scheduled/reflection chats do not trigger it; explicit Run now bypasses the condition.
+
+## Bounded retrieval and machine failures
+
+Use `query --space <name-or-id> --entity <name-or-id> --since <epoch-ms>
+--until <epoch-ms> --limit 8 --json` for deterministic evidence without a model.
+Time filters apply to activity evidence. Resolve entity identity globally first.
+
+`activity list --entity <id> --compact --limit 10 --json` returns one compact
+history page. Follow `nextCursor` with `--cursor` and the same entity/time
+filters until `hasMore` is false. Compact pages retain the space/member envelope,
+record IDs, time/assignment metadata and continuation. Long bodies become
+240-character excerpts; attributes, derived data, attachments and content hashes
+are omitted. The `projection.fullDetail` references point to `activity get <id>`
+(CLI), `activities_get` (MCP), and `getActivity` (internal tools). Defaults stay
+unchanged. REST uses `compact=true`; MCP `activities_forEntity` and internal
+`listRecentActivities` use `compact: true`. These options apply to active
+entity-scoped pages, without client-side type/attribute/open/deadline filters.
+
+JSON failures use stdout `{ "error": { "message": "..." } }` with a nonzero
+exit. REST status and structured error fields survive. Check the exit before
+parsing; see [Retrieve bounded context](playbooks/retrieve-bounded-context.md).
+The unsupported `entity show` spelling gives a targeted `entity get` correction.

package/dist/SKILL.md

@@ -98,6 +98,47 @@ npm i -g ente-cli --registry https://registry.npmjs.org
 
 ---
 
+## Retrieve a bounded page
+
+Search entities globally first to resolve identity. Use the returned ID and an
+explicit space for evidence when the task specifies a space. Preserve `spaces`,
+record `spaceId`/`spaceIds`, scope, warnings and pagination when selecting fields;
+access to a record is not permission to copy it into another space.
+
+```bash
+# Deterministic evidence; no hosted model. Time filters constrain activities.
+if ente query "launch decisions" --space "Work" --entity "Apollo" --since 1791763200000 --until 1792368000000 --limit 8 --json > evidence.json; then
+  jq '{data: {scope: .data.scope, evidence: [.data.evidence[] | {id, title, activityId, entityId, spaceIds, spaceNames}], warnings: .data.warnings, truncated: .data.truncated}, spaces: .data.spaces}' evidence.json
+fi
+# One entity-history page with body excerpts and an explicit full-detail path.
+ente activity list --entity <entity-id> --after 1791763200000 --before 1792368000000 --min-count 0 --limit 10 --compact --json
+# Continue with identical entity/time filters; never replace the cursor with a timestamp.
+ente activity list --entity <entity-id> --after 1791763200000 --before 1792368000000 --min-count 0 --limit 10 --compact --cursor '<nextCursor>' --json
+ente activity get <activity-id> --json
+```
+
+`--compact` currently applies to active entity-scoped activity pages only. It
+keeps space names, scopes, member emails, record IDs and `hasMore`/`nextCursor`.
+It replaces long bodies with 240-character excerpts and omits attributes,
+derived payloads, attachments and content hashes. `projection.fullDetail` names
+the complete read on each interface. Omit `--compact` for the existing output.
+Do not combine compact/cursor pages with client-side `--type`, `--attr`,
+`--only-open` or deadline sorting. Those filters need full reads.
+
+`--json` failures return `{ "error": { "message": "..." } }` on stdout and a
+nonzero exit; REST failures also retain `statusCode` and structured error fields.
+Check the exit before parsing. Do not append a successful help command and treat
+its exit as the preceding command's result. `entity show` reports the supported
+`entity get` command and fails without making a request.
+
+For inbox coverage, page the unfiltered `agent mail threads` list to completion,
+then inspect thread messages, including updates to older threads. `--unread`
+and `--needs-reply` answer different questions; unread alone misses read but
+unanswered mail. Keep each view's cursor separate and retain workflow versions.
+An unfiltered list is not an atomic merged snapshot with internal agent chats.
+
+---
+
 ## Quick Reference
 
 ```bash
@@ -111,7 +152,7 @@ ente auth profiles
 # Search & ask
 ente search "Alice" [--type person] [--json]
 ente ask "What's open with Erik?" [--space <name>] [--entity <name>] [--evidence] [--json]   # AI answer + citations
-ente query "QM system export" [--space <name>] [--entity <name>] [--verbose] [--json]         # evidence only, no AI
+ente query "QM system export" [--space <name>] [--entity <name>] [--since <epoch-ms>] [--until <epoch-ms>] [--limit 12] [--verbose] [--json]         # evidence only, no AI
 
 # Entities
 ente entity list [--query <text>] [--type person|org|project|topic|place|object] [--space <name>] [--limit 50] [--archived] [--json]
@@ -128,7 +169,7 @@ ente entity archive "Old Project" [--json]
 ente entity restore <entity-id> [--share-parents --parent-space-grant-fingerprint <token>] [--json]
 
 # Activities
-ente activity list [--entity "Jane"] [--type note|conversation|meeting|call|message|task] [--attr k=v] [--only-open] [--hours 168] [--limit 20] [--sort deadline|created] [--json]
+ente activity list [--entity "Jane"] [--compact] [--cursor <nextCursor>] [--min-count 0] [--type note|conversation|meeting|call|message|task] [--attr k=v] [--only-open] [--hours 168] [--limit 20] [--sort deadline|created] [--json]
 ente activity create --type meeting --title "Call with Jane" --entity "Jane Doe" --entity "Acme Corp" --space "Work" [--content "…"] [--content-file ./notes.md] [--auto-link --entity-space-grant-fingerprint <token>] [--json]
 ente activity search "quarterly review" [--entity "Acme"] [--type meeting] [--limit 10] [--json]
 ente activity get <activityId> [--json]                # complete detail: body, full nested agenda, messages/replies, entities, attachments

package/dist/cli.mjs

@@ -3710,8 +3710,97 @@ function warn(opts, latest) {
   );
 }
 
+// core/errors.ts
+var ApiError = class extends Error {
+  statusCode;
+  error;
+  constructor(statusCode, message, error) {
+    super(`HTTP ${statusCode}: ${message}`);
+    this.name = "ApiError";
+    this.statusCode = statusCode;
+    this.detail = message;
+    this.error = error ?? {};
+  }
+  /** The backend's human message, without the `HTTP <code>:` prefix. */
+  detail;
+};
+var ExitWithCode = class extends Error {
+  code;
+  constructor(code2) {
+    super(`exit ${code2}`);
+    this.name = "ExitWithCode";
+    this.code = code2;
+  }
+};
+
+// core/output.ts
+function emit(stdout, data, json, rowsFn, headers) {
+  if (json || !rowsFn) {
+    stdout.write(`${JSON.stringify(data, null, 2)}
+`);
+    return;
+  }
+  stdout.write(`${renderTable(rowsFn(data), headers)}
+`);
+}
+function errorMessage(err) {
+  if (!(err instanceof Error)) return String(err);
+  const data = err.data;
+  if (typeof data === "string" && data.length > 0) return data;
+  if (data && typeof data === "object") {
+    const { message, code: code2 } = data;
+    if (typeof message === "string" && message.length > 0) {
+      return typeof code2 === "string" ? `${message} (${code2})` : message;
+    }
+    return `${err.message}: ${JSON.stringify(data)}`;
+  }
+  return err.message;
+}
+function renderTable(rows, headers) {
+  if (rows.length === 0) return "(none)";
+  const cols = headers ?? Object.keys(rows[0] ?? {});
+  const widths = cols.map((c) => Math.max(c.length, ...rows.map((r) => (r[c] ?? "").length)));
+  const line = (cells) => cells.map((cell, i) => cell.padEnd(widths[i] ?? 0)).join("  ").trimEnd();
+  const out = [line(cols), line(cols.map((_, i) => "\u2500".repeat(widths[i] ?? 0)))];
+  for (const r of rows) out.push(line(cols.map((c) => r[c] ?? "")));
+  return out.join("\n");
+}
+
+// core/errorOutput.ts
+function writeCommandError(stdout, stderr, json, error) {
+  if (!json) {
+    stderr.write(`Error: ${errorMessage(error)}
+`);
+    return;
+  }
+  const data = error instanceof ApiError ? error.error : error instanceof Error && "data" in error ? error.data : void 0;
+  const details = data && typeof data === "object" && !Array.isArray(data) ? data : {};
+  stdout.write(`${JSON.stringify({ error: {
+    ...details,
+    message: errorMessage(error),
+    ...error instanceof ApiError ? { statusCode: error.statusCode } : {}
+  } }, null, 2)}
+`);
+}
+
+// core/run.ts
+async function runCli(cli2, argv, context) {
+  try {
+    const command = cli2.process(argv, context);
+    return await cli2.run(command, context);
+  } catch (error) {
+    writeCommandError(
+      context.stdout,
+      context.stderr,
+      argv.includes("--json"),
+      argv.includes("--json") ? new Error("Invalid command or options. Run 'ente <command> --help' for usage.") : error
+    );
+    return 1;
+  }
+}
+
 // ente/version.ts
-var VERSION = "0.4.69";
+var VERSION = "0.4.70";
 
 // ente/branding.ts
 var NPM_REGISTRY = "https://registry.npmjs.org";
@@ -3842,62 +3931,6 @@ function deleteJwt(cacheDir, key) {
   return true;
 }
 
-// core/errors.ts
-var ApiError = class extends Error {
-  statusCode;
-  error;
-  constructor(statusCode, message, error) {
-    super(`HTTP ${statusCode}: ${message}`);
-    this.name = "ApiError";
-    this.statusCode = statusCode;
-    this.detail = message;
-    this.error = error ?? {};
-  }
-  /** The backend's human message, without the `HTTP <code>:` prefix. */
-  detail;
-};
-var ExitWithCode = class extends Error {
-  code;
-  constructor(code2) {
-    super(`exit ${code2}`);
-    this.name = "ExitWithCode";
-    this.code = code2;
-  }
-};
-
-// core/output.ts
-function emit(stdout, data, json, rowsFn, headers) {
-  if (json || !rowsFn) {
-    stdout.write(`${JSON.stringify(data, null, 2)}
-`);
-    return;
-  }
-  stdout.write(`${renderTable(rowsFn(data), headers)}
-`);
-}
-function errorMessage(err) {
-  if (!(err instanceof Error)) return String(err);
-  const data = err.data;
-  if (typeof data === "string" && data.length > 0) return data;
-  if (data && typeof data === "object") {
-    const { message, code: code2 } = data;
-    if (typeof message === "string" && message.length > 0) {
-      return typeof code2 === "string" ? `${message} (${code2})` : message;
-    }
-    return `${err.message}: ${JSON.stringify(data)}`;
-  }
-  return err.message;
-}
-function renderTable(rows, headers) {
-  if (rows.length === 0) return "(none)";
-  const cols = headers ?? Object.keys(rows[0] ?? {});
-  const widths = cols.map((c) => Math.max(c.length, ...rows.map((r) => (r[c] ?? "").length)));
-  const line = (cells) => cells.map((cell, i) => cell.padEnd(widths[i] ?? 0)).join("  ").trimEnd();
-  const out = [line(cols), line(cols.map((_, i) => "\u2500".repeat(widths[i] ?? 0)))];
-  for (const r of rows) out.push(line(cols.map((c) => r[c] ?? "")));
-  return out.join("\n");
-}
-
 // core/command.ts
 var BaseCommand = class extends Command {
   json = options_exports.Boolean("--json", false, {
@@ -3935,8 +3968,7 @@ var BaseCommand = class extends Command {
       return typeof code2 === "number" ? code2 : 0;
     } catch (err) {
       if (err instanceof ExitWithCode) return err.code;
-      this.context.stderr.write(`Error: ${errorMessage(err)}
-`);
+      writeCommandError(this.context.stdout, this.context.stderr, this.json, err);
       return 1;
     }
   }
@@ -4750,6 +4782,12 @@ ${footer}` : body;
   }
   // --- shared: activity list (used by `activity list` and `tasks`) --------
   async runActivityList(opts) {
+    if ((opts.compact || opts.cursor !== void 0) && (!opts.entity || opts.typeFilter || opts.onlyOpen || opts.attrFilter?.length || opts.sort && opts.sort !== "created")) {
+      throw new Error("--compact/--cursor require --entity and cannot combine with --type, --only-open, --attr or --sort deadline. Use an unfiltered page, then inspect full details.");
+    }
+    if (opts.minCount !== void 0 && (!Number.isSafeInteger(opts.minCount) || opts.minCount < 0 || !opts.entity || opts.typeFilter || opts.onlyOpen || opts.attrFilter?.length)) {
+      throw new Error("--min-count requires an unfiltered entity-scoped page and a nonnegative integer. Use 0 for a strict time window.");
+    }
     if (opts.sort && !VALID_SORT.has(opts.sort)) {
       throw new Error(`Invalid --sort value '${opts.sort}'. Allowed: deadline, created`);
     }
@@ -4795,6 +4833,8 @@ ${footer}` : body;
     const hasClientFilters = !!(opts.typeFilter || opts.onlyOpen || opts.attrFilter && opts.attrFilter.length);
     let activities;
     let serverHasMore;
+    let nextCursor;
+    let projection;
     if (hasClientFilters) {
       const hoursCutoff = opts.hours ? Date.now() - opts.hours * 36e5 : void 0;
       activities = [];
@@ -4840,9 +4880,14 @@ ${footer}` : body;
       if (opts.limit) params.limit = String(opts.limit);
       if (opts.before !== void 0) params.before = String(opts.before);
       if (opts.after !== void 0) params.after = String(opts.after);
+      if (opts.cursor !== void 0) params.cursor = opts.cursor;
+      if (opts.compact) params.compact = "true";
+      if (opts.minCount !== void 0) params.minCount = String(opts.minCount);
       const res = await client.listActivities(params);
       activities = res.data ?? [];
       serverHasMore = res.hasMore;
+      nextCursor = res.nextCursor;
+      projection = res.projection;
     }
     if (opts.typeFilter) activities = activities.filter((a) => a.type === opts.typeFilter);
     if (opts.onlyOpen) activities = activities.filter((a) => !a.completed);
@@ -4863,14 +4908,20 @@ ${footer}` : body;
     const hasMore = hasClientFilters ? void 0 : serverHasMore;
     const jsonData = { data: activities };
     if (hasMore !== void 0) jsonData.hasMore = hasMore;
+    if (nextCursor !== void 0) jsonData.nextCursor = nextCursor;
+    if (projection !== void 0) jsonData.projection = projection;
     this.emitText(jsonWithSpaces(jsonData, spaces), () => {
       let body = formatActivityList(activities);
-      if (hasMore && activities.length) {
-        const oldest = activities[activities.length - 1];
+      if (hasMore && nextCursor) {
+        body += `
+
+(more results available \u2014 use --cursor '${nextCursor.replaceAll("'", "'\\''")}' with the same --entity and filters)`;
+      } else if (hasMore && activities.length) {
         body += `
 
-(more results available \u2014 use --before ${oldest.createdAt})`;
+(more results available \u2014 use --before ${activities[activities.length - 1].createdAt})`;
       }
+      if (projection) body += "\n\nCompact excerpts. Full detail: ente activity get <activityId> --json";
       return this.withFooter(body, spaces);
     });
   }
@@ -11115,14 +11166,12 @@ var AuthLogin = class extends BaseCommand {
     try {
       resp = await validateExternalCredential(cleanUrl, key, controller.signal);
     } catch {
-      this.err(`Could not reach ${cleanUrl}`);
-      return 1;
+      throw new Error(`Could not reach ${cleanUrl}`);
     } finally {
       clearTimeout(timer);
     }
     if (resp.status >= 400) {
-      this.err(`Authentication failed: ${resp.status} ${resp.statusText}`);
-      return 1;
+      throw new Error(`Authentication failed: ${resp.status} ${resp.statusText}`);
     }
     const previous = readCredentialsForCleanup(this.profile);
     if (previous) {
@@ -11818,6 +11867,7 @@ var EntityCreate = class extends ProfileCommand {
     const spaces = await spacesFooterFromMemberships(caller);
     const jsonOut = { data: { entityId } };
     if (pinFailures.length) {
+      jsonOut.error = { message: "Entity created, but some parent relationships failed.", code: "PARTIAL_SUCCESS" };
       jsonOut.data = {
         entityId,
         pinFailures: pinFailures.map(([target, error]) => ({ target, error })),
@@ -11843,6 +11893,13 @@ Pinned to: ${pinSucceeded.join(", ")}`;
     }
   }
 };
+var EntityShowCorrection = class extends ProfileCommand {
+  static paths = [["entity", "show"]];
+  nameOrId = options_exports.String();
+  async run() {
+    throw new Error("Use 'ente entity get <name-or-id>' to read entity details.");
+  }
+};
 var EntityGet = class extends ProfileCommand {
   static paths = [["entity", "get"]];
   static usage = Command.Usage({ category: "Entity", description: "Get entity details" });
@@ -11926,10 +11983,9 @@ var EntityUpdate = class extends ProfileCommand {
       didSomething = true;
     }
     if (!didSomething) {
-      this.err(
+      throw new Error(
         "Nothing to update. Specify --name, --alias-add, --alias-remove, --attr, --tag, or --description."
       );
-      return 1;
     }
     const spaces = await spacesFooterFromMemberships(caller);
     this.emitText(
@@ -12215,6 +12271,7 @@ var EntityHtmlUpdate = class extends ProfileCommand {
   }
 };
 var ENTITY_COMMANDS = [
+  EntityShowCorrection,
   EntityList,
   EntityCreate,
   EntityGet,
@@ -12538,6 +12595,9 @@ var ActivityList = class extends ClientCommand {
   static paths = [["activity", "list"]];
   static usage = Command.Usage({ category: "Activity", description: "List activities" });
   entity = options_exports.String("--entity", { description: "Filter by entity (name or ID)" });
+  compact = options_exports.Boolean("--compact", false, { description: "Entity-scoped compact page; preserves spaces and continuation. Read full detail with activity get." });
+  cursor = options_exports.String("--cursor", { description: "Opaque nextCursor from the previous entity-scoped page; keep the same entity and filters" });
+  minCount = options_exports.String("--min-count", { description: "Minimum entity history entries, even outside the time window (default 5). Use 0 for a strict window." });
   type = options_exports.String("--type", { description: "Filter by type (task, call, note, message, conversation, meeting)" });
   attr = options_exports.Array("--attr", { description: "Filter by attribute key=value" });
   onlyOpen = options_exports.Boolean("--only-open", false, { description: "Only show non-completed activities" });
@@ -12551,6 +12611,7 @@ var ActivityList = class extends ClientCommand {
   });
   async run() {
     if (this.archived) {
+      if (this.compact || this.cursor !== void 0 || this.minCount !== void 0) throw new Error("--compact/--cursor/--min-count require an active entity-scoped activity list.");
       const client = this.client();
       const params = { archived: "true" };
       if (this.limit) params.limit = this.limit;
@@ -12563,6 +12624,9 @@ var ActivityList = class extends ClientCommand {
       return;
     }
     await this.runActivityList({
+      compact: this.compact,
+      cursor: this.cursor,
+      minCount: this.minCount !== void 0 ? Number(this.minCount) : void 0,
       entity: this.entity,
       typeFilter: this.type,
       attrFilter: this.attr,
@@ -12776,8 +12840,7 @@ var ActivityUpdate = class extends ProfileCommand {
     const deadline = deadlineChange(this.deadline, this.clearDeadline);
     const hasEntityChange = !!(this.entityAdd && this.entityAdd.length || this.entityRemove && this.entityRemove.length);
     if (this.content === void 0 && this.contentFile === void 0 && this.title === void 0 && deadline === null && !hasEntityChange && !this.agentAssignee?.length && !this.clearAgentAssignees) {
-      this.err("Nothing to update. Specify content, title, deadline, entity links or agent assignees.");
-      return 1;
+      throw new Error("Nothing to update. Specify content, title, deadline, entity links or agent assignees.");
     }
     if (this.clearAgentAssignees && this.agentAssignee?.length) throw new Error("Choose --agent-assignee or --clear-agent-assignees");
     const caller = await resolveCaller();
@@ -12798,8 +12861,7 @@ var ActivityUpdate = class extends ProfileCommand {
       const newIds = currentIds.filter((eid) => !removeSet.has(eid));
       for (const eid of addIds) if (!currentIds.includes(eid)) newIds.push(eid);
       if (newIds.length === 0) {
-        this.err("Cannot remove all entities \u2014 an activity must have at least one.");
-        return 1;
+        throw new Error("Cannot remove all entities \u2014 an activity must have at least one.");
       }
       await caller.mutation(activitiesUpdateEntities, { activityId: this.id, entities: newIds });
     }
@@ -12974,8 +13036,7 @@ var ActivityMessageAdd = class extends ProfileCommand {
   async run() {
     const markdown = readContentOption(this.content, this.contentFile);
     if (!markdown?.trim()) {
-      this.err("Message content is required. Specify --content or --content-file.");
-      return 1;
+      throw new Error("Message content is required. Specify --content or --content-file.");
     }
     const caller = await resolveCaller();
     const messageId = await caller.mutation(messagesCreateFromMarkdown, {
@@ -13344,8 +13405,7 @@ var TaskListCmd = class extends ClientCommand {
     else if (this.due === "today") params.dueBy = String(endOfTodayBerlin());
     else if (this.due === "overdue") params.dueBy = String(Date.now());
     else if (this.due) {
-      this.err(`Unknown --due value: '${this.due}'. Use: today, overdue, or all.`);
-      return 1;
+      throw new Error(`Unknown --due value: '${this.due}'. Use: today, overdue, or all.`);
     }
     const res = await client.listTasks(params);
     const tasks = (res.data ?? []).slice();
@@ -13478,8 +13538,7 @@ var TaskUpdate = class extends ProfileCommand {
     const attributes = parseAttrs(this.attr);
     const deadline = deadlineChange(this.deadline, this.clearDeadline);
     if (this.title === void 0 && this.content === void 0 && deadline === null && Object.keys(attributes).length === 0) {
-      this.err("Nothing to update. Specify --title, --content, --attr, --deadline, or --clear-deadline.");
-      return 1;
+      throw new Error("Nothing to update. Specify --title, --content, --attr, --deadline, or --clear-deadline.");
     }
     const caller = await resolveCaller();
     const activityId = await resolveTaskIdC(caller, this.id);
@@ -14997,7 +15056,7 @@ var RecordingRerunCommand = class extends ProfileCommand {
       audioPreserved
     };
     if (after.processingStatus === "error") {
-      this.emitText(data, () => `Pipeline failed for ${after.id}: ${after.processingError}`);
+      this.emitText({ ...data, error: { message: `Pipeline failed for ${after.id}: ${after.processingError}` } }, () => `Pipeline failed for ${after.id}: ${after.processingError}`);
       return 1;
     }
     this.emitText(
@@ -15940,7 +15999,7 @@ Commands:
   ente guide [topic]           This help
 
 Run \`ente <command> --help\` for detailed usage on any command.
-Run \`ente guide <topic>\` for deep dives: entities, tasks, activities, search, patterns, limits`
+Run \`ente guide <topic>\` for deep dives: entities, tasks, activities, search, retrieval, patterns, limits`
   },
   entities: {
     title: "Entities",
@@ -16067,6 +16126,26 @@ Archiving (trash):
   ente activity delete <activity-id>        # move to trash (soft delete)
   ente activity list --archived             # list trashed activities
   ente activity restore <activity-id>       # restore from trash`
+  },
+  retrieval: {
+    title: "Bounded retrieval",
+    content: `Resolve entities globally first: ente search "Apollo" --json
+Use an explicit space when the task specifies one:
+  ente query "launch decisions" --space "Work" --entity "Apollo" --since 1791763200000 --until 1792368000000 --limit 8 --json
+Time filters apply to activity evidence; query uses no model.
+
+Read one compact entity-history page:
+  ente activity list --entity <id> --after 1791763200000 --min-count 0 --limit 10 --compact --json
+Continue with --cursor <nextCursor>, keeping the entity and time filters.
+Compact pages retain spaces/member context, IDs, hasMore and nextCursor.
+Bodies are excerpts; projection.fullDetail names the complete read.
+  ente activity get <activityId> --json
+
+Keep spaces, spaceId/spaceIds, scope, warnings and continuation when selecting
+fields. Access does not authorize copying records into another space.
+Check command exits before parsing JSON. JSON failures use an error envelope
+on stdout and a nonzero exit. Use entity get, not entity show.
+For examples: playbooks/retrieve-bounded-context.md`
   },
   search: {
     title: "Search \u2014 Fuzzy, Multi-Strategy",
@@ -16159,8 +16238,7 @@ var GuideCmd = class extends BaseCommand {
     }
     const entry = TOPICS[this.topic.toLowerCase()];
     if (!entry) {
-      this.err(`Unknown topic: '${this.topic}'. Available: ${TOPIC_NAMES.join(", ")}`);
-      return 1;
+      throw new Error(`Unknown topic: '${this.topic}'. Available: ${TOPIC_NAMES.join(", ")}`);
     }
     this.out(`
   ${entry.title}
@@ -17211,7 +17289,7 @@ async function main() {
       upgradeCommand: ENTE_BRANDING.upgradeCommand
     });
   }
-  await cli.runExit(argv);
+  process.exitCode = await runCli(cli, argv, { stdout: process.stdout, stderr: process.stderr });
 }
 void main();
 /*! Bundled license information: