papiers 0.1.2 → 0.1.3

package/dist/index.js

@@ -268,7 +268,7 @@ function resolveCliConfig(params) {
   const token = firstNonEmpty([params.env[TOKEN_ENV_VAR]]) ?? null;
   return {
     apiBaseUrl: normalizedBaseUrl,
-    apiBaseUrlSource: params.apiBaseUrlOverride ? "--api-base-url" : params.env[API_BASE_URL_ENV_VAR]?.trim() ? API_BASE_URL_ENV_VAR : "default",
+    apiBaseUrlSource: params.apiBaseUrlOverride ? "--api-url" : params.env[API_BASE_URL_ENV_VAR]?.trim() ? API_BASE_URL_ENV_VAR : "default",
     token,
     tokenSource: token ? TOKEN_ENV_VAR : null,
     tokenPreview: token ? redactPapiersToken(token) : null
@@ -420,16 +420,6 @@ var PUBLIC_KINDS = [
   "conversation",
   "equation"
 ];
-var EXPECTED_DOCUMENT_QUERY_IN = [
-  "title",
-  "metadata"
-];
-var EXPECTED_CONTENT_QUERY_IN = [
-  "content"
-];
-var EXPECTED_EQUATION_QUERY_IN = [
-  "latex"
-];
 var EXPECTED_DOCUMENT_READ_FORMATS = [
   "metadata",
   "markdown",
@@ -478,10 +468,13 @@ var EXPECTED_DOCUMENT_FILTERS = [
   "engaged",
   "lastEngagedAt"
 ];
+var EXPECTED_CONVERSATION_FILTERS = [
+  "lastEngagedAt"
+];
 var EXPECTED_DOCUMENT_FILTER_OPERATORS = {
   id: ["eq", "in"],
   title: ["eq", "contains", "prefix", "in"],
-  author: ["eq"],
+  author: ["eq", "contains"],
   venue: ["eq", "contains", "prefix", "in"],
   publishedDate: ["eq", "gte", "gt", "lte", "lt", "between"],
   publishedYear: ["eq", "gte", "gt", "lte", "lt", "between", "in"],
@@ -598,6 +591,25 @@ var PAPIERS_SEARCH_QUALITY_SIGNALS = [
   "low",
   "empty"
 ];
+var PAPIERS_SEARCH_RESULT_KINDS = [
+  "document",
+  "conversation"
+];
+var PAPIERS_SEARCH_EVIDENCE_KINDS = [
+  "passage",
+  "highlight",
+  "equation"
+];
+var PAPIERS_SEARCH_MATCH_REASONS = [
+  "title",
+  "doi",
+  "arxivId",
+  "pmid",
+  "passage",
+  "highlight",
+  "equation",
+  "conversation"
+];
 var PAPIERS_PUBLIC_NOT_READY_REASONS_BY_FEATURE = {
   document_content_read: ["explicit_enablement_required"],
   non_document_kinds: ["public_id_projection_not_ready"],
@@ -613,7 +625,10 @@ var PAPIERS_PUBLIC_NOT_READY_REASONS_BY_FEATURE = {
   read_section_scopes: ["section_scoped_read_not_ready"],
   read_context: ["read_context_not_ready"],
   ranked_search_cursors: ["search_sessions_not_ready"],
-  search_results_browse: ["content_search_not_ready"]
+  search_results_browse: [
+    "content_search_not_ready",
+    "search_sessions_not_ready"
+  ]
 };
 var PAPIERS_PUBLIC_ERROR_CODES = [
   "api_disabled",
@@ -746,7 +761,7 @@ var SEARCH_RESPONSE_KEYS = /* @__PURE__ */ new Set([
   "requestId",
   "query",
   "quality",
-  "items",
+  "results",
   "page",
   "ranking",
   "warnings"
@@ -760,6 +775,9 @@ var SEARCH_RANKING_KEYS = /* @__PURE__ */ new Set([
 ]);
 var SEARCH_QUALITY_KEYS = /* @__PURE__ */ new Set(["signal", "suggestions"]);
 var SEARCH_QUALITY_SIGNALS = new Set(PAPIERS_SEARCH_QUALITY_SIGNALS);
+var SEARCH_RESULT_KINDS = new Set(PAPIERS_SEARCH_RESULT_KINDS);
+var SEARCH_EVIDENCE_KINDS = new Set(PAPIERS_SEARCH_EVIDENCE_KINDS);
+var SEARCH_MATCH_REASONS = new Set(PAPIERS_SEARCH_MATCH_REASONS);
 var PUBLIC_WARNING_KEYS = /* @__PURE__ */ new Set(["code", "message"]);
 var DOCUMENT_SEARCH_WARNING_CODE = "metadata_only_search";
 var DOCUMENT_SEARCH_WARNING_MESSAGE = "Public document search currently searches catalog title and metadata, not document body content.";
@@ -821,6 +839,32 @@ var SEARCH_DOCUMENT_ITEM_KEYS = /* @__PURE__ */ new Set([
   "metadata",
   "updatedAt"
 ]);
+var SEARCH_RESULT_BASE_KEYS = [
+  "id",
+  "kind",
+  "rank",
+  "score",
+  "matchedBy",
+  "title"
+];
+var SEARCH_DOCUMENT_RESULT_KEYS = /* @__PURE__ */ new Set([
+  ...SEARCH_RESULT_BASE_KEYS,
+  "source",
+  "metadata",
+  "evidence",
+  "evidenceTotal"
+]);
+var SEARCH_CONVERSATION_RESULT_KEYS = /* @__PURE__ */ new Set([
+  ...SEARCH_RESULT_BASE_KEYS,
+  "snippet"
+]);
+var SEARCH_EVIDENCE_KEYS = /* @__PURE__ */ new Set([
+  "kind",
+  "id",
+  "rank",
+  "snippet",
+  "score"
+]);
 var READ_SUCCESS_DOCUMENT_ITEM_KEYS = /* @__PURE__ */ new Set([
   "id",
   "kind",
@@ -1050,17 +1094,12 @@ function assertPapiersSearchResponse(label, body, expectedQuery, options = {}) {
       `${label} did not echo the requested query.`
     );
   }
-  const itemCount = validateListSearchItems(label, value.items, {
-    expectedKind: options.expectedKind,
-    expectedKinds: options.expectedKinds,
-    mode: "search",
-    requireRank: true
-  });
-  const searchItems = value.items;
-  for (const [index, item] of searchItems.entries()) {
-    if (item.rank !== index + 1) {
+  const itemCount = validateSearchResults(label, value.results, options);
+  const searchResults = value.results;
+  for (const [index, result] of searchResults.entries()) {
+    if (result.rank !== index + 1) {
       throw new PapiersCliResponseValidationError(
-        `${label} item ${index} rank was not contiguous from 1.`
+        `${label} result ${index} rank was not contiguous from 1.`
       );
     }
   }
@@ -1080,10 +1119,7 @@ function assertPapiersSearchResultsResponse(label, body, request) {
   rejectUnexpectedKeys(label, value, SEARCH_RESPONSE_KEYS);
   assertPublicRequestId(`${label} requestId`, value.requestId);
   assertNonEmptyString(`${label} query`, value.query);
-  const itemCount = validateListSearchItems(label, value.items, {
-    mode: "search",
-    requireRank: true
-  });
+  const itemCount = validateSearchResults(label, value.results);
   validatePage(label, value.page, itemCount, { cursor: "none" });
   validateOptionalSearchQuality(`${label} quality`, value.quality);
   if (value.ranking === void 0) {
@@ -1118,12 +1154,12 @@ function assertPapiersSearchResultsResponse(label, body, request) {
       `${label} returned more items than the consumed ranking window.`
     );
   }
-  const items = value.items;
+  const items = value.results;
   let previousRank = expectedOffset;
   for (const [index, item] of items.entries()) {
     if (typeof item.rank !== "number" || item.rank <= previousRank || item.rank > consumedBound) {
       throw new PapiersCliResponseValidationError(
-        `${label} item ${index} rank was not strictly increasing within the frozen ranking window.`
+        `${label} result ${index} rank was not strictly increasing within the frozen ranking window.`
       );
     }
     previousRank = item.rank;
@@ -1332,6 +1368,164 @@ function validateTokenSummary(label, rawToken) {
   validateOptionalTimestamp(`${label} revokedAt`, token.revokedAt);
   validateOptionalTimestamp(`${label} lastUsedAt`, token.lastUsedAt);
 }
+function validateSearchResults(label, results, options = {}) {
+  const values = assertArray(`${label} results`, results);
+  for (const [index, rawResult] of values.entries()) {
+    const result = assertRecord(`${label} result ${index}`, rawResult);
+    rejectUnexpectedContent(`${label} result ${index}`, result);
+    const kind = validateSearchResultKind(
+      `${label} result ${index} kind`,
+      result.kind,
+      result.id
+    );
+    if (options.expectedKind !== void 0 && kind !== options.expectedKind) {
+      throw new PapiersCliResponseValidationError(
+        `${label} result ${index} kind did not match the requested kind.`
+      );
+    }
+    if (options.expectedKinds !== void 0 && !options.expectedKinds.has(kind)) {
+      throw new PapiersCliResponseValidationError(
+        `${label} result ${index} kind was not one of the requested kinds.`
+      );
+    }
+    if (kind === "document") {
+      validateSearchDocumentResult(`${label} result ${index}`, result);
+    } else {
+      validateSearchConversationResult(`${label} result ${index}`, result);
+    }
+  }
+  return values.length;
+}
+function validateSearchResultKind(label, value, id) {
+  if (typeof id !== "string") {
+    throw new PapiersCliResponseValidationError(`${label} id was invalid.`);
+  }
+  if (!SEARCH_RESULT_KINDS.has(String(value))) {
+    throw new PapiersCliResponseValidationError(
+      `${label} was not a top-level search result kind.`
+    );
+  }
+  if (value === "document") {
+    assertDocId(`${label} id`, id);
+    return "document";
+  }
+  if (value === "conversation" && isPublicIdForKind(id, "conversation")) {
+    return "conversation";
+  }
+  throw new PapiersCliResponseValidationError(
+    `${label} did not match the public id kind.`
+  );
+}
+function validateSearchDocumentResult(label, result) {
+  rejectUnexpectedKeys(label, result, SEARCH_DOCUMENT_RESULT_KEYS);
+  assertDocId(`${label} id`, result.id);
+  assertPositiveInteger(`${label} rank`, result.rank);
+  validateSearchScore(`${label} score`, result.score);
+  validateSearchMatchedBy(`${label} matchedBy`, result.matchedBy, {
+    allow: /* @__PURE__ */ new Set([
+      "title",
+      "doi",
+      "arxivId",
+      "pmid",
+      "passage",
+      "highlight",
+      "equation"
+    ])
+  });
+  validateOptionalNullableString(`${label} title`, result.title);
+  validateOptionalDocumentCatalogMetadata(`${label} metadata`, result.metadata);
+  validateOptionalMetadataReadSource(`${label} source`, result.source);
+  const evidenceCount = validateSearchEvidenceList(
+    `${label} evidence`,
+    result.evidence
+  );
+  const evidenceTotal = assertNonNegativeInteger(
+    `${label} evidenceTotal`,
+    result.evidenceTotal
+  );
+  if (evidenceTotal < evidenceCount) {
+    throw new PapiersCliResponseValidationError(
+      `${label} evidenceTotal was smaller than evidence.length.`
+    );
+  }
+}
+function validateSearchConversationResult(label, result) {
+  rejectUnexpectedKeys(label, result, SEARCH_CONVERSATION_RESULT_KEYS);
+  const id = assertNonEmptyString(`${label} id`, result.id);
+  if (!isPublicIdForKind(id, "conversation")) {
+    throw new PapiersCliResponseValidationError(
+      `${label} id was not a cnv_* public id.`
+    );
+  }
+  assertPositiveInteger(`${label} rank`, result.rank);
+  validateSearchScore(`${label} score`, result.score);
+  validateSearchMatchedBy(`${label} matchedBy`, result.matchedBy, {
+    allow: /* @__PURE__ */ new Set(["conversation"])
+  });
+  validateOptionalNullableString(`${label} title`, result.title);
+  validateOptionalPublicExcerpt(`${label} snippet`, result.snippet);
+}
+function validateSearchEvidenceList(label, value) {
+  const evidence = assertArray(label, value);
+  for (const [index, rawEvidence] of evidence.entries()) {
+    const item = assertRecord(`${label} ${index}`, rawEvidence);
+    rejectUnexpectedKeys(`${label} ${index}`, item, SEARCH_EVIDENCE_KEYS);
+    validateSearchEvidenceKind(`${label} ${index} kind`, item.kind, item.id);
+    assertPositiveInteger(`${label} ${index} rank`, item.rank);
+    if (item.rank !== index + 1) {
+      throw new PapiersCliResponseValidationError(
+        `${label} ${index} rank was not contiguous from 1.`
+      );
+    }
+    validateOptionalPublicExcerpt(`${label} ${index} snippet`, item.snippet);
+    validateSearchScore(`${label} ${index} score`, item.score);
+  }
+  return evidence.length;
+}
+function validateSearchEvidenceKind(label, value, id) {
+  if (typeof id !== "string") {
+    throw new PapiersCliResponseValidationError(`${label} id was invalid.`);
+  }
+  if (!SEARCH_EVIDENCE_KINDS.has(String(value))) {
+    throw new PapiersCliResponseValidationError(
+      `${label} was not a search evidence kind.`
+    );
+  }
+  if (value === "passage" && isPublicIdForKind(id, "passage") || value === "highlight" && isPublicIdForKind(id, "highlight") || value === "equation" && isPublicIdForKind(id, "equation")) {
+    return value;
+  }
+  throw new PapiersCliResponseValidationError(
+    `${label} did not match the public id kind.`
+  );
+}
+function validateSearchMatchedBy(label, value, options) {
+  const values = assertArray(label, value);
+  if (values.length === 0) {
+    throw new PapiersCliResponseValidationError(`${label} was empty.`);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const [index, rawReason] of values.entries()) {
+    const reason = assertNonEmptyString(`${label} ${index}`, rawReason);
+    if (!SEARCH_MATCH_REASONS.has(reason) || !options.allow.has(reason)) {
+      throw new PapiersCliResponseValidationError(
+        `${label} ${index} was not an allowed search match reason.`
+      );
+    }
+    if (seen.has(reason)) {
+      throw new PapiersCliResponseValidationError(
+        `${label} contained duplicate match reasons.`
+      );
+    }
+    seen.add(reason);
+  }
+}
+function validateSearchScore(label, value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
+    throw new PapiersCliResponseValidationError(
+      `${label} was not a finite score in [0, 1].`
+    );
+  }
+}
 function assertNoInternalResponseKeys(label, value, options = {}) {
   const stack = [
     { value, isRoot: true }
@@ -2709,22 +2903,18 @@ function expectedKindForListSearchRequest(request) {
 function expectedKindsForSearchRequest(request) {
   const kinds = request.kinds;
   if (kinds === void 0) {
-    return {
-      expectedKinds: /* @__PURE__ */ new Set([
-        "document",
-        "passage",
-        "highlight",
-        "conversation"
-      ])
-    };
+    return { expectedKinds: /* @__PURE__ */ new Set(["document", "conversation"]) };
   }
-  if (!Array.isArray(kinds) || kinds.length <= 1) {
-    return { expectedKind: expectedKindForListSearchRequest(request) };
+  if (!Array.isArray(kinds) || kinds.length === 0) {
+    throw new CliUsageError(
+      "Public search requests must specify at least one supported kind."
+    );
   }
-  for (const kind of kinds) {
-    if (kind === "document" || kind === "equation") {
+  const rawKinds = kinds;
+  for (const kind of rawKinds) {
+    if (kind === "document") {
       throw new CliUsageError(
-        `Multi-kind public search does not support kind ${kind}; request it separately.`
+        "Unified public search does not support kind document; omit kinds to search titles plus content."
       );
     }
     if (!PUBLIC_KINDS.includes(kind)) {
@@ -2733,14 +2923,16 @@ function expectedKindsForSearchRequest(request) {
       );
     }
   }
-  return {
-    expectedKinds: new Set(kinds)
-  };
+  const normalizedKinds = new Set(rawKinds);
+  if (normalizedKinds.size === 1 && normalizedKinds.has("conversation")) {
+    return { expectedKind: "conversation" };
+  }
+  return normalizedKinds.has("conversation") ? { expectedKinds: /* @__PURE__ */ new Set(["document", "conversation"]) } : { expectedKind: "document" };
 }
 async function requestPapiersApi(config, fetchImpl, path, init) {
   if (!config.token) {
     throw new CliUsageError(
-      `${TOKEN_ENV_VAR} is required for public Papiers API commands.`
+      `${TOKEN_ENV_VAR} is not set. Run papiers auth login, or set ${TOKEN_ENV_VAR}, then retry.`
     );
   }
   return requestPapiersApiWithBearer(
@@ -2862,7 +3054,7 @@ var PMID_PATTERN = /^\d+$/u;
 var YEAR_PATTERN = /^\d{4}$/u;
 var MIN_PUBLIC_YEAR = 1;
 var MAX_PUBLIC_YEAR = 9999;
-var DOCUMENT_FILTER_FIELD_ALIASES = {
+var FORMER_FILTER_FIELD_ALIASES = {
   arxiv_id: "arxivId",
   last_engaged_at: "lastEngagedAt",
   published_date: "publishedDate",
@@ -2871,13 +3063,27 @@ var DOCUMENT_FILTER_FIELD_ALIASES = {
   source_family: "sourceFamily",
   year: "publishedYear"
 };
-var DOCUMENT_FILTER_FIELD_ALIAS_NAMES = Object.keys(
-  DOCUMENT_FILTER_FIELD_ALIASES
-).sort();
+function didYouMeanFilterField(field) {
+  const suggestion = FORMER_FILTER_FIELD_ALIASES[field];
+  return suggestion ? ` Did you mean "${suggestion}"?` : "";
+}
 function parseDocumentFilterExpression(expression) {
+  if (isImplicitAuthorEqualityFilterExpression(expression)) {
+    throw new CliUsageError(
+      'Use "author.contains=<name-or-handle>" for author searches, or "author.eq=<full-author-key>" for exact author-key matches.'
+    );
+  }
   const filter = parseFilterExpression(expression);
   return normalizeSupportedDocumentFilter(filter);
 }
+function isImplicitAuthorEqualityFilterExpression(expression) {
+  const trimmed = expression.trim();
+  const equalsIndex = trimmed.indexOf("=");
+  if (equalsIndex < 0) {
+    return false;
+  }
+  return trimmed.slice(0, equalsIndex).trim() === "author";
+}
 function parseFilterExpression(expression) {
   const parsed = parseFilterParts(expression);
   const field = parsed.field.trim();
@@ -2903,57 +3109,52 @@ function parseFilterExpression(expression) {
   };
 }
 function normalizeSupportedDocumentFilter(filter) {
-  const canonicalField = canonicalDocumentFilterField(filter.field);
-  const canonicalFilter = canonicalField === filter.field ? filter : { ...filter, field: canonicalField };
-  const allowedOperators = EXPECTED_DOCUMENT_FILTER_OPERATORS[canonicalField];
+  const field = filter.field;
+  const allowedOperators = EXPECTED_DOCUMENT_FILTER_OPERATORS[field];
   if (!allowedOperators) {
     throw new CliUsageError(
       `Unsupported public document filter field "${filter.field}". Supported fields: ${Object.keys(
         EXPECTED_DOCUMENT_FILTER_OPERATORS
-      ).join(", ")}.`
+      ).join(", ")}.${didYouMeanFilterField(filter.field)}`
     );
   }
-  if (!allowedOperators.includes(
-    canonicalFilter.op
-  )) {
+  if (!allowedOperators.includes(filter.op)) {
     throw new CliUsageError(
-      `Operator "${canonicalFilter.op}" is not supported for public document filter field "${canonicalFilter.field}". Supported operators: ${allowedOperators.join(
+      `Operator "${filter.op}" is not supported for public document filter field "${filter.field}". Supported operators: ${allowedOperators.join(
         ", "
       )}.`
     );
   }
-  switch (canonicalFilter.field) {
+  const documentFilter = { ...filter, field };
+  switch (field) {
     case "id":
       return normalizeStringDocumentFilter(
-        canonicalFilter,
+        documentFilter,
         normalizeDocumentIdValue
       );
     case "doi":
-      return normalizeStringDocumentFilter(canonicalFilter, normalizeDoiOrNull);
+      return normalizeStringDocumentFilter(documentFilter, normalizeDoiOrNull);
     case "arxivId":
       return normalizeStringDocumentFilter(
-        canonicalFilter,
+        documentFilter,
         normalizeArxivOrNull
       );
     case "pmid":
-      return normalizeStringDocumentFilter(
-        canonicalFilter,
-        normalizePmidOrNull
-      );
+      return normalizeStringDocumentFilter(documentFilter, normalizePmidOrNull);
     case "publishedDate":
-      return normalizePublishedDateFilter(canonicalFilter);
+      return normalizePublishedDateFilter(documentFilter);
     case "publishedYear":
-      return normalizePublishedYearFilter(canonicalFilter);
+      return normalizePublishedYearFilter(documentFilter);
     case "sourceDomain":
-      return normalizeSourceDomainFilter(canonicalFilter);
+      return normalizeSourceDomainFilter(documentFilter);
     case "annotated":
     case "engaged":
-      return normalizeBooleanDocumentFilter(canonicalFilter);
+      return normalizeBooleanDocumentFilter(documentFilter);
     case "lastEngagedAt":
-      return normalizeLastEngagedAtFilter(canonicalFilter);
+      return normalizeLastEngagedAtFilter(documentFilter);
     default:
       return normalizeStringDocumentFilter(
-        canonicalFilter,
+        documentFilter,
         normalizeNonEmptyString
       );
   }
@@ -3001,12 +3202,6 @@ function normalizeBooleanDocumentFilter(filter) {
   }
   throw invalidFilterValue(filter);
 }
-function canonicalDocumentFilterField(field) {
-  return Object.prototype.hasOwnProperty.call(
-    DOCUMENT_FILTER_FIELD_ALIASES,
-    field
-  ) ? DOCUMENT_FILTER_FIELD_ALIASES[field] : field;
-}
 function normalizePublishedDateFilter(filter) {
   const normalized = normalizePapiersPublicDateFilter(
     filter.op,
@@ -3293,21 +3488,22 @@ function parseScalar(rawValue) {
 
 // src/args.ts
 var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
+  "all",
   "force",
   "help",
   "doc-ids",
+  "evidence-ids",
+  "highlight-ids",
   "ids",
   "ids0",
   "input0",
   "json",
+  "passage-ids",
   "pretty",
-  "stdin",
-  "token-stdin",
   "fail-fast",
   "version"
 ]);
 var VALUE_FLAGS = /* @__PURE__ */ new Set([
-  "api-base-url",
   "api-url",
   "cursor",
   "document-id",
@@ -3326,8 +3522,13 @@ var VALUE_FLAGS = /* @__PURE__ */ new Set([
   "since"
 ]);
 var SECRET_ARG_FLAGS = /* @__PURE__ */ new Set(["pat", "token", "api-token"]);
-var GLOBAL_VALUE_FLAGS = /* @__PURE__ */ new Set(["api-base-url", "api-url"]);
+var GLOBAL_VALUE_FLAGS = /* @__PURE__ */ new Set(["api-url"]);
 var NO_COMMAND_VALUE_FLAGS = /* @__PURE__ */ new Set([...GLOBAL_VALUE_FLAGS]);
+var REMOVED_FLAG_HINTS = {
+  "api-base-url": "Use --api-url instead.",
+  "token-stdin": "papiers auth login reads the token from stdin \u2014 no flag needed.",
+  stdin: "papiers auth login reads the token from stdin \u2014 no flag needed."
+};
 var NO_COMMAND_BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["help", "json"]);
 var IDS_PIPELINE_BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "help",
@@ -3338,6 +3539,12 @@ var IDS_PIPELINE_BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "json",
   "pretty"
 ]);
+var SEARCH_IDS_PIPELINE_BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
+  ...IDS_PIPELINE_BOOLEAN_FLAGS,
+  "evidence-ids",
+  "highlight-ids",
+  "passage-ids"
+]);
 var LIST_VALUE_FLAGS = /* @__PURE__ */ new Set([
   ...GLOBAL_VALUE_FLAGS,
   "cursor",
@@ -3378,122 +3585,309 @@ var READ_BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
 ]);
 var AUTH_LOGIN_BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   ...NO_COMMAND_BOOLEAN_FLAGS,
-  "force",
-  "stdin",
-  "token-stdin"
+  "force"
 ]);
-var PUBLIC_KIND_ALIAS_HELP = "Kind aliases: doc/docs/documents -> document, annotation(s) -> highlight, chat(s) -> conversation; plural kind names are accepted.";
-var PUBLIC_KIND_ALIASES = /* @__PURE__ */ new Map([
-  ["document", "document"],
-  ["documents", "document"],
+var FORMER_KIND_ALIASES = /* @__PURE__ */ new Map([
   ["doc", "document"],
   ["docs", "document"],
-  ["passage", "passage"],
+  ["documents", "document"],
   ["passages", "passage"],
-  ["highlight", "highlight"],
-  ["highlights", "highlight"],
   ["annotation", "highlight"],
   ["annotations", "highlight"],
-  ["conversation", "conversation"],
-  ["conversations", "conversation"],
+  ["highlights", "highlight"],
   ["chat", "conversation"],
   ["chats", "conversation"],
-  ["equation", "equation"],
+  ["conversations", "conversation"],
   ["equations", "equation"]
 ]);
 var MULTI_SEARCH_KINDS = [
   "passage",
   "highlight",
-  "conversation"
+  "conversation",
+  "equation"
 ];
-var HELP_TEXT = `Papiers CLI
+var GLOBAL_HELP = `Papiers CLI: search and read your library from the terminal.
+Your saved papers, highlights, and conversations (your chats) \u2014 for you or an AI agent.
 
-Search, list, and read your saved papers, highlights, notes, and conversations from the terminal.
-Data commands return stable JSON by default. Use --pretty for human-readable output.
+GETTING STARTED
+  papiers auth login                     Sign in with a token from Papiers (Settings -> API tokens)
+  papiers list --limit 5 --pretty        Your most recent documents
+  papiers search "your topic" --pretty   Search across your library
 
-Usage:
-  papiers auth login --token-stdin [--force] [--json]
-  papiers auth status [--json]
-  papiers auth inspect [--json]
-  papiers auth logout [--json]
-  papiers doctor [--json]
-  papiers capabilities [--json]
+COMMANDS
+  search        Search across your library
+  list          List your documents, highlights, and conversations
+  read          Print a document, highlight, or conversation
+  browse        Page through an earlier search's results
+  auth          Sign in, check status, or sign out
+  tokens        List or revoke your API tokens
+  doctor        Check your setup, connection, and what's available
+  version       Print the CLI version
+
+  papiers <command> --help     full options and examples for a command
+  papiers help --all           everything, in one page
+
+OUTPUT
+  Commands print JSON by default \u2014 built for scripts and agents.
+  --pretty            human-readable output
+  --ids / --doc-ids   pipe result IDs into the next command
+
+SIGNING IN
+  Signing in saves your token on this machine.
+  For scripts or an AI agent, set PAPIERS_TOKEN instead.
+
+Exit codes: 0 ok \xB7 1 command or API failure \xB7 2 bad usage`;
+var OUTPUT_OPTS = `  --json               machine-readable JSON (the default)
+  --pretty             human-readable text
+  --ids                result/item IDs, one per line, with their native prefix
+  --ids0               the same IDs, NUL-separated, for \`xargs -0\`
+  --doc-ids            parent document IDs only (doc_\u2026), deduped; conversation hits are skipped`;
+var SEARCH_OUTPUT_OPTS = `${OUTPUT_OPTS}
+  --passage-ids        matching passage evidence IDs, flattened in result order
+  --highlight-ids      matching highlight evidence IDs, flattened in result order
+  --evidence-ids       all matching evidence IDs, flattened in result order`;
+var HELP_TOPICS = {
+  search: `papiers search \u2014 search across your library.
+
+USAGE
+  papiers search QUERY [--kind KIND ...] [--filter FIELD.OP=VALUE ...] [--limit N] [--pretty|--json|--ids|--ids0|--doc-ids|--passage-ids|--highlight-ids|--evidence-ids]
+
+OPTIONS
+  --kind KIND          what to search. Defaults to all \u2014 your passages, highlights,
+                       equations, conversations, and matching titles. Or focus on one:
+                       passage \xB7 highlight \xB7 conversation \xB7 equation.
+  --filter FIELD.OP=VALUE   narrow parent documents \u2014 repeatable, up to 25.
+                       e.g. --filter publishedYear.gte=2020 --filter author.contains=hinton. Fields/ops: help --all.
+  --document-id ID     scope to documents: doc_\u2026 (comma-separated or repeated), or @-/@file.
+  --limit N            max results, 1\u201350.
+${SEARCH_OUTPUT_OPTS}
+
+EXAMPLES
+  papiers search "mixture of experts" --pretty
+  papiers search "capacity factors" --kind passage --document-id doc_<id> --json
+  papiers search "dropout" --filter author.contains=hinton --json
+  papiers search "diffusion" --filter venue.contains=neurips --json
+  papiers search retrieval --kind passage --limit 5 --passage-ids | papiers read @- --format plain --json
+
+When capabilities.searchResultsBrowse.enabled is true, a search may return ranking.searchId \u2014 pass it to \`papiers browse\` for more pages.`,
+  list: `papiers list \u2014 list your documents, highlights, and conversations.
+
+USAGE
+  papiers list [--kind KIND] [--limit N] [--cursor CURSOR] [--pretty|--json|--ids|--ids0|--doc-ids]
+  papiers list --kind document [--filter FIELD.OP=VALUE ...] [--order-by KEY] [--document-id doc_\u2026|@-|@file]
+  papiers list --kind highlight|conversation [--since WHEN]
+
+OPTIONS
+  --kind KIND          document (default) \xB7 passage \xB7 highlight \xB7 conversation \xB7 equation.
+  --filter FIELD.OP=VALUE   narrow document results \u2014 repeatable, up to 25. document kind only.
+                       e.g. --filter lastEngagedAt.gte=30d --filter annotated=true. Fields/ops: help --all.
+  --order-by KEY       addedAt:desc (default) or lastEngagedAt:desc. document kind only.
+  --document-id ID     scope to documents: doc_\u2026 (comma-separated or repeated), or @-/@file.
+                       document and highlight only.
+  --since WHEN         only items at or after an ISO 8601 time, or an Nd shorthand (e.g. 30d).
+                       highlight and conversation only.
+  --limit N            max results, 1\u201350.
+  --cursor CURSOR      fetch the next page \u2014 use page.nextCursor from the previous response.
+${OUTPUT_OPTS}
+
+EXAMPLES
+  papiers list --limit 5 --pretty
+  papiers list --kind highlight --since 30d --pretty
+  papiers list --kind document --filter lastEngagedAt.gte=30d --json
+  papiers list --kind document --filter annotated=true --json`,
+  read: `papiers read \u2014 print documents, highlights, conversations, passages, or equations.
+
+USAGE
+  papiers read ID [ID ...] [--format FORMAT] [--max-chars-per-item N] [--fail-fast] [--json|--pretty]
+  papiers read @- | @file [--input0] [--format FORMAT] [--max-chars-per-item N] [--json|--pretty]
+  Each ID is doc_\u2026 / pas_\u2026 / hl_\u2026 / cnv_\u2026 / eq_\u2026 \u2014 the kind is read from the prefix; don't mix kinds.
+
+OPTIONS
+  --format FORMAT      how to render each item. Default auto (equation defaults to metadata).
+                       document: auto|metadata|markdown|plain.   passage: markdown|plain.
+                       highlight, conversation: metadata|plain.   equation: metadata.
+  --include SECTION    extra sections, comma-separated: metadata, source, locations.
+                       document only (highlight/conversation/equation: metadata only; passage: none).
+  --pages RANGE        restrict a document read to pages, e.g. 1,3-5. document only.
+  --max-chars-per-item N   truncate each item's content to N chars, 1\u2013200000.
+  --cursor CURSOR      continue one long document \u2014 use items[].nextCursor from the previous
+                       response. One literal doc_\u2026 only, with --format auto, markdown, or plain.
+  --fail-fast          exit non-zero if any item fails (default: succeed if at least one does).
+  --json               machine-readable JSON (the default)
+  --pretty             human-readable text
+
+EXAMPLES
+  papiers read doc_<id> --format markdown --max-chars-per-item 2000 --json
+  papiers read hl_<id> --json
+  papiers search retrieval --doc-ids | papiers read @- --format metadata --json`,
+  browse: `papiers browse \u2014 page deeper into an earlier search's results.
+
+USAGE
+  papiers browse srch_\u2026 [--offset N] [--limit N] [--pretty|--json|--ids|--ids0|--doc-ids|--passage-ids|--highlight-ids|--evidence-ids]
+
+OPTIONS
+  --offset N           start at rank N (0-based) in the frozen ranking.
+  --limit N            max results, 1\u201350.
+  ${SEARCH_OUTPUT_OPTS}
+
+When capabilities.searchResultsBrowse.enabled is true, a search response includes
+ranking.searchId (an srch_\u2026 handle); pass it here to page deeper without
+re-running the search. The ranking is frozen and expires after a while.
+
+EXAMPLE
+  papiers browse srch_<id> --offset 10 --json`,
+  auth: `papiers auth \u2014 sign in, check status, or sign out.
+
+USAGE
+  papiers auth login [--force] [--json]     Sign in (paste your token, or pipe it in)
+  papiers auth status [--json]              Show whether you're signed in
+  papiers auth inspect [--json]             Show details about the saved token
+  papiers auth logout [--json]              Forget the saved token
+
+OPTIONS
+  --force              when signing in, replace an already-saved token.
+
+Signing in saves your token on this machine. For scripts or an AI agent, set PAPIERS_TOKEN instead.`,
+  tokens: `papiers tokens \u2014 list or revoke your API tokens.
+
+USAGE
   papiers tokens list [--json]
   papiers tokens revoke TOKEN_ID [--json]
-  papiers version | papiers --version | papiers -V
-  papiers list [--kind document] [--limit 20] [--cursor CURSOR] [--filter FIELD.OP=VALUE] [--document-id doc_...|@-|@file] [--input0] [--order-by addedAt:desc|lastEngagedAt:desc] [--json|--ids|--ids0|--doc-ids|--pretty]
-  papiers list --kind passage|highlight|conversation|equation [--document-id doc_... (highlight)] [--since ISO|Nd (highlight/conversation)] [--limit 20] [--cursor CURSOR] [--json|--ids|--ids0|--doc-ids|--pretty]
-  papiers search QUERY [--limit 20] [--json|--ids|--ids0|--doc-ids|--pretty]
-  papiers search QUERY --kind document [--query-in title|metadata] [--limit 20] [--filter FIELD.OP=VALUE] [--document-id doc_...|@-|@file] [--input0] [--json|--ids|--ids0|--doc-ids|--pretty]
-  papiers search QUERY --kind passage|highlight|conversation [--query-in content] [--document-id doc_... (passage/highlight)] [--since ISO|Nd (highlight/conversation)] [--limit 20] [--json|--ids|--ids0|--doc-ids|--pretty]
-  papiers search QUERY --kind all [--limit 20] [--json|--ids|--ids0|--doc-ids|--pretty]
-  papiers search QUERY --kind equation [--query-in latex] [--limit 20] [--json|--ids|--ids0|--doc-ids|--pretty]
-  papiers browse srch_... [--offset N] [--limit 20] [--json|--ids|--ids0|--doc-ids|--pretty]
-  papiers read doc_... [doc_...] [--id doc_...|@file] [--kind document] [--format auto|metadata|markdown|plain] [--include metadata,source,locations] [--pages 1,3-5] [--max-chars-per-item N] [--input0] [--fail-fast] [--json|--pretty]
-  papiers read doc_... --format auto|markdown|plain --cursor CURSOR [--pages 1,3-5] [--max-chars-per-item N] [--json]
-  papiers read pas_... [pas_...] [--format markdown|plain] [--max-chars-per-item N] [--input0] [--fail-fast] [--json|--pretty]
-  papiers read hl_... [hl_...] [--format metadata|plain|auto] [--max-chars-per-item N] [--input0] [--fail-fast] [--json|--pretty]
-  papiers read cnv_... [cnv_...] [--format metadata|plain|auto] [--max-chars-per-item N] [--input0] [--fail-fast] [--json|--pretty]
-  papiers read eq_... [eq_...] [--format metadata|auto] [--include metadata] [--input0] [--fail-fast] [--json|--pretty]
-  papiers read @- [--input0] [--format auto|metadata|markdown|plain] [--include metadata,source,locations] [--pages 1,3-5] [--max-chars-per-item N] [--fail-fast] [--json]
 
-Examples:
-  papiers capabilities --json                          # check available features
-  papiers list --kind document --limit 5 --json
-  papiers list --kind annotations --limit 5 --pretty   # your highlights with notes
-  papiers list --kind annotations --since 30d --json   # recent highlights
-  papiers list --kind annotations --document-id doc_<id> --json  # highlights on one document
-  papiers list --kind document --filter engaged=false --limit 10 --json  # unread documents
-  papiers list --kind document --filter annotated=true --json   # documents with your notes
-  papiers list --kind document --filter lastEngagedAt.gte=30d --json  # recently active documents
-  papiers list --kind document --order-by lastEngagedAt:desc --limit 10 --json  # most recently engaged first (engaged docs only)
-  papiers search "router load balancing tradeoffs" --limit 10 --json
-  papiers browse srch_<id> --offset 10 --json
-  papiers search "mixture of experts" --kind passage --limit 5 --json
-  papiers search "capacity factors" --kind passage --document-id doc_<id> --json  # search within one document
-  papiers search "evaluation harness" --kind chats --json
-  papiers search "\\\\alpha" --kind equation --query-in latex --json
-  papiers read doc_<id> --format markdown --max-chars-per-item 2000 --json
-  papiers read hl_<id> --json                          # highlight quote + annotation
-  papiers search retrieval --kind passage --limit 5 --ids | papiers read @- --format plain --json
-  papiers search retrieval --doc-ids | papiers read @- --format metadata --json  # resolve hits to their parent documents
+Create and name tokens in Papiers (Settings -> API tokens). Revoking is permanent.`,
+  doctor: `papiers doctor \u2014 check your setup, connection, and what's available.
 
-Output:
-  Data commands return JSON by default for scripts.
-  Use --pretty for human-readable terminal output.
-  Use --ids or --ids0 to pipe result IDs into another command.
-  Use --doc-ids to pipe parent document IDs where available.
-  Paginated responses include page.nextCursor; pass it back with --cursor.
-  Search responses may include ranking.searchId; pass it to papiers browse.
-  API errors use papiers.error.v1 with error.message and requestId.
+USAGE
+  papiers doctor [--json]
 
-Exit codes:
-  0 success; 1 command or API failure (read exits 1 when no item succeeded,
-  or with --fail-fast when any item failed); 2 usage or configuration error.
+Verifies your token, the server connection, and which features are available.
+Run it first when something isn't working.`,
+  version: `papiers version \u2014 print the CLI version.
 
-Configuration:
-  Create an API token in Papiers, then run papiers auth login --token-stdin.
-  For CI or scripts, set PAPIERS_TOKEN and pass --json for stable output.
+USAGE
+  papiers version | papiers --version | papiers -V`
+};
+var REFERENCE = `REFERENCE \u2014 IDs, piping, pagination, and limits.
 
-Tokens must come from PAPIERS_TOKEN or an ignored local .env file, not command-line flags.
-Read cursors apply only to one literal doc_* ID with --format auto, markdown, or plain.
-${PUBLIC_KIND_ALIAS_HELP}
-Filter aliases accepted by the CLI include ${DOCUMENT_FILTER_FIELD_ALIAS_NAMES.join(", ")}.
-`;
+ID PREFIXES
+  doc_   document        pas_   passage         hl_    highlight
+  cnv_   conversation    eq_    equation        srch_  a saved search ranking (for browse)
+  On read, the kind \u2014 and which --format/--include apply \u2014 is read from the prefix.
+
+PIPING IDS BETWEEN COMMANDS
+  --ids        result IDs, one per line, with their native prefix
+  --ids0       the same IDs, NUL-separated (for \`xargs -0\`)
+  --doc-ids    parent document IDs only (doc_\u2026), deduped; conversation hits are skipped
+  @-           read IDs from stdin          @file   read IDs from a file
+  --input0     read piped IDs NUL-separated instead of whitespace/newlines
+  @- and @file accept plain IDs or a Papiers JSON envelope, and may be mixed with literal IDs.
+
+PAGINATION \u2014 three separate mechanisms
+  list     response has page.nextCursor          \u2192 papiers list \u2026 --cursor CURSOR
+  search   response has ranking.searchId           \u2192 papiers browse srch_\u2026 --offset N
+  read     a truncated item has items[].nextCursor \u2192 papiers read doc_\u2026 --cursor CURSOR
+
+LIMITS
+  --limit 1\u201350  \xB7  --max-chars-per-item 1\u2013200000  \xB7  up to 25 filters  \xB7  up to 100 IDs per request
+
+FILTER FIELDS \u2014 document kind, as FIELD.OP=VALUE (or FIELD=VALUE for equality)
+  id  title  author  venue  doi  arxivId  pmid
+  publishedDate  publishedYear  sourceFamily  sourceDomain
+  annotated  engaged  lastEngagedAt
+  Operators: eq \xB7 in \xB7 contains \xB7 prefix \xB7 gte \xB7 gt \xB7 lte \xB7 lt \xB7 between (which apply depends on the field).`;
+var HELP_PAGES = {
+  ...HELP_TOPICS,
+  reference: REFERENCE
+};
+var HELP_TOPIC_NAMES = Object.keys(HELP_PAGES);
+var HELP_COMMAND_NAMES = Object.keys(HELP_TOPICS);
+var HELP_TEXT = [GLOBAL_HELP, ...Object.values(HELP_PAGES)].join(
+  "\n\n\n"
+);
+function colorizeHelp(text) {
+  return text.replace(/^([A-Z][A-Z ]{2,})$/gm, "\x1B[1;36m$1\x1B[0m").replace(
+    /(^|[\s([|/])(--[a-z0-9-]+|-[A-Za-z])\b/g,
+    "$1\x1B[33m$2\x1B[0m"
+  );
+}
+function renderHelp(command, style) {
+  const help = command.type === "help" ? command : void 0;
+  let body = GLOBAL_HELP;
+  if (help?.all) {
+    body = HELP_TEXT;
+  } else if (help?.topic) {
+    body = HELP_PAGES[help.topic] ?? GLOBAL_HELP;
+  }
+  return style ? colorizeHelp(body) : body;
+}
+var SUGGESTIBLE_COMMANDS = [
+  "auth",
+  "doctor",
+  "capabilities",
+  "tokens",
+  "list",
+  "search",
+  "browse",
+  "read",
+  "version",
+  "help"
+];
+function levenshtein(a, b) {
+  const rows = a.length + 1;
+  const cols = b.length + 1;
+  const dist = Array.from(
+    { length: rows },
+    () => new Array(cols).fill(0)
+  );
+  for (let i = 0; i < rows; i += 1) dist[i][0] = i;
+  for (let j = 0; j < cols; j += 1) dist[0][j] = j;
+  for (let i = 1; i < rows; i += 1) {
+    for (let j = 1; j < cols; j += 1) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      dist[i][j] = Math.min(
+        dist[i - 1][j] + 1,
+        dist[i][j - 1] + 1,
+        dist[i - 1][j - 1] + cost
+      );
+    }
+  }
+  return dist[rows - 1][cols - 1];
+}
+function suggestCommand(input) {
+  let best = null;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  for (const candidate of SUGGESTIBLE_COMMANDS) {
+    const distance = levenshtein(input, candidate);
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      best = candidate;
+    }
+  }
+  return best !== null && bestDistance <= 2 ? best : null;
+}
+function unknownCommandMessage(command) {
+  const suggestion = suggestCommand(command);
+  const guess = suggestion ? ` Did you mean "${suggestion}"?` : "";
+  return `Unknown papiers command.${guess} Run papiers --help to see commands.`;
+}
 function parseCliArgs(argv) {
   const parsed = parseRawArgv(argv);
   const global = parseGlobalOptions(parsed);
   if (parsed.booleanFlags.has("version") && !parsed.help) {
     return { type: "version", ...global };
   }
-  if (parsed.help || parsed.positionals.length === 0) {
+  const [command, ...rest] = parsed.positionals;
+  if (parsed.help || command === "help" || parsed.positionals.length === 0) {
+    if (parsed.booleanFlags.has("all")) {
+      return { type: "help", all: true, ...global };
+    }
+    const topic = command === "help" ? rest[0] : command;
+    if (topic && HELP_TOPIC_NAMES.includes(topic)) {
+      return { type: "help", topic, ...global };
+    }
     return { type: "help", ...global };
   }
-  const [command, ...rest] = parsed.positionals;
   switch (command) {
-    case "help":
-    case "--help":
-      return { type: "help", ...global };
     case "version":
       assertNoExtraPositionals(command, rest);
       return { type: "version", ...global };
@@ -3527,7 +3921,7 @@ function parseCliArgs(argv) {
         type: "list",
         ...global,
         idsOnly: listOutput.idsOnly,
-        ...parsePrettyOutput(parsed, listOutput.idsOnly) ? { pretty: true } : {},
+        ...parsePrettyOutput(parsed, listOutput.anyIdsOutput) ? { pretty: true } : {},
         ...listOutput.idsNulDelimited ? { idsNulDelimited: true } : {},
         ...listOutput.docIdsOnly ? { docIdsOnly: true } : {},
         ...parsed.booleanFlags.has("input0") ? { inputNulDelimited: true } : {},
@@ -3537,16 +3931,23 @@ function parseCliArgs(argv) {
     }
     case "search": {
       assertAllowedFlags(parsed, SEARCH_VALUE_FLAGS, "search");
-      assertAllowedBooleanFlags(parsed, IDS_PIPELINE_BOOLEAN_FLAGS, "search");
+      assertAllowedBooleanFlags(
+        parsed,
+        SEARCH_IDS_PIPELINE_BOOLEAN_FLAGS,
+        "search"
+      );
       const searchDocumentIds = parseDocumentIdFlagValues(parsed, "search");
       const searchOutput = parseIdsOutput(parsed, "search");
       return {
         type: "search",
         ...global,
         idsOnly: searchOutput.idsOnly,
-        ...parsePrettyOutput(parsed, searchOutput.idsOnly) ? { pretty: true } : {},
+        ...parsePrettyOutput(parsed, searchOutput.anyIdsOutput) ? { pretty: true } : {},
         ...searchOutput.idsNulDelimited ? { idsNulDelimited: true } : {},
         ...searchOutput.docIdsOnly ? { docIdsOnly: true } : {},
+        ...searchOutput.passageIdsOnly ? { passageIdsOnly: true } : {},
+        ...searchOutput.highlightIdsOnly ? { highlightIdsOnly: true } : {},
+        ...searchOutput.evidenceIdsOnly ? { evidenceIdsOnly: true } : {},
         ...parsed.booleanFlags.has("input0") ? { inputNulDelimited: true } : {},
         ...searchDocumentIds ? { documentIds: searchDocumentIds } : {},
         request: buildSearchRequest(rest, parsed, searchDocumentIds)
@@ -3554,7 +3955,11 @@ function parseCliArgs(argv) {
     }
     case "browse": {
       assertAllowedFlags(parsed, BROWSE_VALUE_FLAGS, "browse");
-      assertAllowedBooleanFlags(parsed, IDS_PIPELINE_BOOLEAN_FLAGS, "browse");
+      assertAllowedBooleanFlags(
+        parsed,
+        SEARCH_IDS_PIPELINE_BOOLEAN_FLAGS,
+        "browse"
+      );
       if (parsed.booleanFlags.has("input0")) {
         throw new CliUsageError("--input0 is not supported for browse.");
       }
@@ -3563,9 +3968,12 @@ function parseCliArgs(argv) {
         type: "browse",
         ...global,
         idsOnly: browseOutput.idsOnly,
-        ...parsePrettyOutput(parsed, browseOutput.idsOnly) ? { pretty: true } : {},
+        ...parsePrettyOutput(parsed, browseOutput.anyIdsOutput) ? { pretty: true } : {},
         ...browseOutput.idsNulDelimited ? { idsNulDelimited: true } : {},
         ...browseOutput.docIdsOnly ? { docIdsOnly: true } : {},
+        ...browseOutput.passageIdsOnly ? { passageIdsOnly: true } : {},
+        ...browseOutput.highlightIdsOnly ? { highlightIdsOnly: true } : {},
+        ...browseOutput.evidenceIdsOnly ? { evidenceIdsOnly: true } : {},
         request: buildBrowseRequest(rest, parsed)
       };
     }
@@ -3584,7 +3992,7 @@ function parseCliArgs(argv) {
       };
     }
     default:
-      throw new CliUsageError("Unknown papiers command.");
+      throw new CliUsageError(unknownCommandMessage(command));
   }
 }
 function argvWantsJson(argv) {
@@ -3594,9 +4002,9 @@ function parsePrettyOutput(parsed, idsOnly) {
   if (!parsed.booleanFlags.has("pretty")) {
     return false;
   }
-  if (idsOnly || parsed.json || parsed.booleanFlags.has("doc-ids")) {
+  if (idsOnly || parsed.json) {
     throw new CliUsageError(
-      "--pretty cannot be combined with --json, --ids, --ids0, or --doc-ids."
+      "--pretty cannot be combined with --json or ID projection flags."
     );
   }
   return true;
@@ -3636,12 +4044,6 @@ function parseAuthCommand(rest, parsed, global) {
     case "login": {
       assertAllowedBooleanFlags(parsed, AUTH_LOGIN_BOOLEAN_FLAGS, "auth login");
       assertNoExtraPositionals("auth login", extra);
-      const patStdinFlagCount = Number(parsed.booleanFlags.has("token-stdin")) + Number(parsed.booleanFlags.has("stdin"));
-      if (patStdinFlagCount !== 1) {
-        throw new CliUsageError(
-          "papiers auth login requires exactly one of --token-stdin or --stdin."
-        );
-      }
       return {
         type: "auth-login",
         ...global,
@@ -3792,104 +4194,65 @@ function buildSearchRequest(positionals, parsed, documentIds) {
       "Ranked public search cursors are not available yet."
     );
   }
-  if (isMultiSearchKindFlag(parsed)) {
-    return buildMultiKindSearchRequest(parsed, query, documentIds);
-  }
-  if (!parsed.flags.has("kind")) {
-    const defaulted = buildDefaultKindSearchRequest(parsed, query, documentIds);
-    if (defaulted) {
-      return defaulted;
-    }
-  }
-  const kind = parseListSearchKind(parsed, "search");
-  const since = parseSinceFlag(parsed, kind, "search");
-  if (kind !== "document") {
-    if (documentIds?.length && kind !== "highlight" && kind !== "passage") {
-      throw new CliUsageError(
-        "papiers search --document-id is supported only with --kind document, passage, or highlight."
-      );
-    }
-    assertNoNonDocumentListSearchFlag(parsed, "filter", "search", kind);
-    return pruneUndefined({
-      schemaVersion: PAPIERS_SCHEMA_VERSIONS.searchRequest,
-      query,
-      kinds: [kind],
-      queryIn: parseSearchQueryIn(parsed, kind),
-      documentIds: documentIds?.length ? documentIds : void 0,
-      since,
-      limit: parseLimit(parsed)
-    });
-  }
-  const filters = parsed.flags.get("filter")?.map((filter) => parseDocumentFilterExpression(filter));
-  assertFilterCount(filters, "search", documentIds ? 1 : 0);
-  return pruneUndefined({
-    schemaVersion: PAPIERS_SCHEMA_VERSIONS.searchRequest,
-    query,
-    kinds: ["document"],
-    queryIn: parseSearchQueryIn(parsed, kind),
-    filters,
-    limit: parseLimit(parsed)
-  });
-}
-function isMultiSearchKindFlag(parsed) {
-  return singleFlagValue(parsed, "kind")?.trim().toLowerCase() === "all";
-}
-function buildDefaultKindSearchRequest(parsed, query, documentIds) {
-  const queryIn = singleFlagValue(parsed, "query-in");
-  if (parsed.flags.has("filter") || documentIds?.length || queryIn === "title" || queryIn === "metadata") {
-    return null;
-  }
-  if (parsed.flags.has("since")) {
+  if (parsed.flags.has("query-in")) {
     throw new CliUsageError(
-      "papiers search --since is supported only with --kind highlight or conversation."
+      "papiers search no longer supports --query-in; use free-text query plus --filter FIELD.OP=VALUE for structured attributes."
     );
   }
-  if (queryIn === "latex") {
-    throw new CliUsageError(
-      "papiers search --query-in latex requires --kind equation."
-    );
-  }
-  if (queryIn !== void 0 && queryIn !== "content") {
+  if (parsed.flags.has("since")) {
     throw new CliUsageError(
-      "papiers search supports --query-in title, metadata, content, or latex."
+      "papiers search no longer supports --since; use --filter lastEngagedAt.gte=<when> for document recency."
     );
   }
+  const kinds = parseSearchKindScopes(parsed);
+  const filters = parsed.flags.get("filter")?.map((filter) => parseDocumentFilterExpression(filter));
+  assertFilterCount(filters, "search");
   return pruneUndefined({
     schemaVersion: PAPIERS_SCHEMA_VERSIONS.searchRequest,
     query,
-    queryIn,
+    kinds,
+    filters,
     limit: parseLimit(parsed)
   });
 }
-function buildMultiKindSearchRequest(parsed, query, documentIds) {
-  if (documentIds?.length) {
-    throw new CliUsageError(
-      "papiers search --document-id is not supported with --kind all; use --kind passage or --kind highlight."
-    );
+function parseSearchKindScopes(parsed) {
+  const rawKinds = parsed.flags.get("kind")?.flatMap(splitCommaSeparatedValues);
+  if (rawKinds === void 0) {
+    return void 0;
   }
-  if (parsed.flags.has("since")) {
-    throw new CliUsageError(
-      "papiers search --since is not supported with --kind all; use --kind highlight or conversation."
-    );
+  if (rawKinds.length === 0) {
+    throw new CliUsageError("papiers search --kind requires a value.");
   }
-  if (parsed.flags.has("filter")) {
-    throw new CliUsageError(
-      "papiers search --filter is not supported with --kind all."
-    );
+  const sawAll = rawKinds.some((kind) => kind.trim().toLowerCase() === "all");
+  if (sawAll) {
+    if (rawKinds.length > 1) {
+      throw new CliUsageError(
+        "papiers search --kind all cannot be combined with other --kind values."
+      );
+    }
+    return void 0;
   }
-  const queryIn = singleFlagValue(parsed, "query-in");
-  if (queryIn !== void 0 && queryIn !== "content") {
-    throw new CliUsageError(
-      "papiers search --kind all supports --query-in content only."
-    );
+  const kinds = [];
+  for (const rawKind of rawKinds) {
+    const kind = normalizeCliPublicKind(rawKind);
+    if (!kind) {
+      throw new CliUsageError(
+        `papiers search supports --kind passage, highlight, conversation, or equation; received "${rawKind}".${didYouMeanKind(rawKind)}`
+      );
+    }
+    if (kind === "document") {
+      throw new CliUsageError(
+        "papiers search no longer supports --kind document; omit --kind to search matching titles and content."
+      );
+    }
+    if (!MULTI_SEARCH_KINDS.includes(kind)) {
+      throw new CliUsageError(
+        `papiers search supports --kind passage, highlight, conversation, or equation; received "${rawKind}".`
+      );
+    }
+    kinds.push(kind);
   }
-  return pruneUndefined({
-    schemaVersion: PAPIERS_SCHEMA_VERSIONS.searchRequest,
-    query,
-    kinds: [...MULTI_SEARCH_KINDS],
-    queryIn: "content",
-    limit: parseLimit(parsed)
-  });
+  return [...new Set(kinds)];
 }
 function parseSinceFlag(parsed, kind, command) {
   const value = singleFlagValue(parsed, "since");
@@ -3964,7 +4327,7 @@ function parseReadKind(parsed) {
     return normalized;
   }
   throw new CliUsageError(
-    `Public CLI read currently supports --kind document, passage, highlight, conversation, or equation only; received "${kind}". ${PUBLIC_KIND_ALIAS_HELP}`
+    `Public CLI read currently supports --kind document, passage, highlight, conversation, or equation only; received "${kind}".${didYouMeanKind(kind)}`
   );
 }
 function readKindsForLiteralIds(ids) {
@@ -4023,13 +4386,25 @@ function parseIdsOutput(parsed, command) {
   const idsOnly = parsed.booleanFlags.has("ids");
   const idsNulDelimited = parsed.booleanFlags.has("ids0");
   const docIdsOnly = parsed.booleanFlags.has("doc-ids");
-  const selectedCount = Number(idsOnly) + Number(idsNulDelimited) + Number(docIdsOnly) + Number(parsed.json);
+  const passageIdsOnly = parsed.booleanFlags.has("passage-ids");
+  const highlightIdsOnly = parsed.booleanFlags.has("highlight-ids");
+  const evidenceIdsOnly = parsed.booleanFlags.has("evidence-ids");
+  const selectedCount = Number(idsOnly) + Number(idsNulDelimited) + Number(docIdsOnly) + Number(passageIdsOnly) + Number(highlightIdsOnly) + Number(evidenceIdsOnly) + Number(parsed.json);
   if (selectedCount > 1) {
     throw new CliUsageError(
-      `Use only one of --ids, --ids0, --doc-ids, or --json for papiers ${command}.`
+      `Use only one of --ids, --ids0, --doc-ids, --passage-ids, --highlight-ids, --evidence-ids, or --json for papiers ${command}.`
     );
   }
-  return { idsOnly: idsOnly || idsNulDelimited, idsNulDelimited, docIdsOnly };
+  const normalizedIdsOnly = idsOnly || idsNulDelimited;
+  return {
+    idsOnly: normalizedIdsOnly,
+    idsNulDelimited,
+    docIdsOnly,
+    passageIdsOnly,
+    highlightIdsOnly,
+    evidenceIdsOnly,
+    anyIdsOutput: normalizedIdsOnly || docIdsOnly || passageIdsOnly || highlightIdsOnly || evidenceIdsOnly
+  };
 }
 function parseReadInclude(parsed) {
   const rawIncludes = parsed.flags.get("include")?.flatMap(splitCommaSeparatedValues);
@@ -4190,7 +4565,8 @@ function parseRawArgv(argv) {
       continue;
     }
     if (!VALUE_FLAGS.has(name)) {
-      throw new CliUsageError(`Unknown option --${name}.`);
+      const hint = REMOVED_FLAG_HINTS[name] ?? "Run papiers --help to see options.";
+      throw new CliUsageError(`Unknown option --${name}. ${hint}`);
     }
     const flagValue = value ?? argv[index + 1];
     if (flagValue === void 0 || flagValue.startsWith("--")) {
@@ -4221,14 +4597,9 @@ function splitLongFlag(arg) {
   };
 }
 function parseGlobalOptions(parsed) {
-  const apiBaseUrl = singleFlagValue(parsed, "api-base-url");
-  const apiUrlAlias = singleFlagValue(parsed, "api-url");
-  if (apiBaseUrl && apiUrlAlias) {
-    throw new CliUsageError("Use only one of --api-base-url or --api-url.");
-  }
   return {
     json: parsed.json,
-    apiBaseUrl: apiBaseUrl ?? apiUrlAlias
+    apiBaseUrl: singleFlagValue(parsed, "api-url")
   };
 }
 function parseListSearchKind(parsed, command) {
@@ -4243,11 +4614,16 @@ function parseListSearchKind(parsed, command) {
     );
   }
   throw new CliUsageError(
-    `papiers ${command} supports --kind document, passage, highlight, conversation, or equation; received "${kind}". ${PUBLIC_KIND_ALIAS_HELP}`
+    `papiers ${command} supports --kind document, passage, highlight, conversation, or equation; received "${kind}".${didYouMeanKind(kind)}`
   );
 }
 function normalizeCliPublicKind(value) {
-  return PUBLIC_KIND_ALIASES.get(value.trim().toLowerCase()) ?? null;
+  const normalized = value.trim().toLowerCase();
+  return PUBLIC_KINDS.includes(normalized) ? normalized : null;
+}
+function didYouMeanKind(value) {
+  const suggestion = FORMER_KIND_ALIASES.get(value.trim().toLowerCase());
+  return suggestion ? ` Did you mean "${suggestion}"?` : "";
 }
 function assertNoNonDocumentListSearchFlag(parsed, flag, command, kind) {
   if (parsed.flags.has(flag)) {
@@ -4300,34 +4676,6 @@ function parseLimit(parsed) {
   }
   return limit;
 }
-function parseSearchQueryIn(parsed, kind) {
-  const queryIn = singleFlagValue(parsed, "query-in");
-  if (kind === "document") {
-    if (queryIn === void 0) {
-      return void 0;
-    }
-    if (EXPECTED_DOCUMENT_QUERY_IN.some((supported2) => supported2 === queryIn)) {
-      return queryIn;
-    }
-    throw new CliUsageError(
-      "Public document search supports --query-in title or --query-in metadata."
-    );
-  }
-  const defaultsByKind = {
-    passage: EXPECTED_CONTENT_QUERY_IN[0],
-    highlight: EXPECTED_CONTENT_QUERY_IN[0],
-    conversation: EXPECTED_CONTENT_QUERY_IN[0],
-    equation: EXPECTED_EQUATION_QUERY_IN[0]
-  };
-  const resolved = queryIn ?? defaultsByKind[kind];
-  const supported = kind === "equation" ? EXPECTED_EQUATION_QUERY_IN : EXPECTED_CONTENT_QUERY_IN;
-  if (supported.some((value) => value === resolved)) {
-    return resolved;
-  }
-  throw new CliUsageError(
-    kind === "equation" ? "Public equation search supports --query-in latex only." : `Public ${kind} search supports --query-in content only.`
-  );
-}
 function assertFilterCount(filters, command, reservedFilterCount = 0) {
   const totalFilterCount = (filters?.length ?? 0) + reservedFilterCount;
   if (totalFilterCount > DOCUMENT_MAX_FILTERS) {
@@ -4511,26 +4859,7 @@ function assertSupportedDocumentCapabilities(value) {
   assertSupportedSearchResultsBrowse(capabilities.searchResultsBrowse);
   const queryIn = assertRecord2("capabilities queryIn", capabilities.queryIn);
   assertRecordKeysSubset("capabilities queryIn", queryIn, PUBLIC_KINDS);
-  const expectedQueryInByKind = {
-    document: EXPECTED_DOCUMENT_QUERY_IN
-  };
-  if (searchKinds.includes("passage")) {
-    expectedQueryInByKind.passage = EXPECTED_CONTENT_QUERY_IN;
-  }
-  if (searchKinds.includes("highlight")) {
-    expectedQueryInByKind.highlight = EXPECTED_CONTENT_QUERY_IN;
-  }
-  if (searchKinds.includes("conversation")) {
-    expectedQueryInByKind.conversation = EXPECTED_CONTENT_QUERY_IN;
-  }
-  if (searchKinds.includes("equation")) {
-    expectedQueryInByKind.equation = EXPECTED_EQUATION_QUERY_IN;
-  }
-  assertPublicKindStringArrayRecord(
-    "capabilities queryIn",
-    queryIn,
-    expectedQueryInByKind
-  );
+  assertPublicKindStringArrayRecord("capabilities queryIn", queryIn, {});
   const readFormats = assertStringArray(
     "capabilities readFormats",
     capabilities.readFormats
@@ -4619,7 +4948,11 @@ function assertSupportedDocumentCapabilities(value) {
       `capabilities filters.${kind}`,
       filters[kind]
     );
-    assertSameStringSet(`capabilities filters.${kind}`, actualFilters, []);
+    assertSameStringSet(
+      `capabilities filters.${kind}`,
+      actualFilters,
+      kind === "conversation" ? EXPECTED_CONVERSATION_FILTERS : []
+    );
   }
   const operatorsByField = assertRecord2(
     "capabilities operatorsByField",
@@ -4723,12 +5056,9 @@ function assertPublicKindStringArrayRecord(label, record, expectedByKind) {
   }
 }
 function assertSupportedSearchKinds(searchKinds) {
-  if (!searchKinds.includes("document")) {
-    throw new Error("capabilities searchKinds did not include document.");
-  }
   const seen = /* @__PURE__ */ new Set();
   for (const kind of searchKinds) {
-    if (seen.has(kind) || !PUBLIC_KINDS.includes(kind)) {
+    if (seen.has(kind) || kind === "document" || !PUBLIC_KINDS.includes(kind)) {
       throw new Error(
         `capabilities searchKinds advertised unsupported kind: ${kind}.`
       );
@@ -4950,9 +5280,16 @@ function isPublicNotReadyReason(reason, reasons) {
 }
 
 // src/pretty.ts
+function warningLines(warnings) {
+  if (!warnings?.length) {
+    return [];
+  }
+  return warnings.map((warning) => warning.message?.trim()).filter((message) => Boolean(message)).map((message) => `! ${message}`);
+}
 function renderPrettyPageOutput(response) {
   const lines = [];
-  for (const item of response.items) {
+  const entries = response.results ?? response.items ?? [];
+  for (const item of entries) {
     const rank = item.rank !== void 0 ? `${item.rank}. ` : "";
     const title = item.title?.trim() ? `  ${item.title.trim()}` : "";
     lines.push(`${rank}${item.id}  [${item.kind}]${title}`);
@@ -4960,21 +5297,36 @@ function renderPrettyPageOutput(response) {
     if (excerpt?.trim()) {
       lines.push(`    ${excerpt.trim()}`);
     }
+    if (item.evidence?.length) {
+      for (const evidence of item.evidence) {
+        const evidenceRank = evidence.rank !== void 0 ? `${evidence.rank}. ` : "";
+        lines.push(`    - ${evidenceRank}${evidence.id}  [${evidence.kind}]`);
+        if (evidence.snippet?.trim()) {
+          lines.push(`      ${evidence.snippet.trim()}`);
+        }
+      }
+      if (typeof item.evidenceTotal === "number" && item.evidenceTotal > item.evidence.length) {
+        lines.push(
+          `      + ${item.evidenceTotal - item.evidence.length} more evidence item${item.evidenceTotal - item.evidence.length === 1 ? "" : "s"}`
+        );
+      }
+    }
   }
   if (lines.length === 0) {
     lines.push("(no items)");
   }
-  const itemCount = response.items.length;
+  const itemCount = entries.length;
   lines.push(
     `(${itemCount} item${itemCount === 1 ? "" : "s"}; ${pagingSummary(response)})`
   );
+  lines.push(...warningLines(response.warnings));
   return `${lines.join("\n")}
 `;
 }
 function pagingSummary(response) {
   const ranking = response.ranking;
   if (ranking) {
-    const nextOffset = ranking.nextOffset !== void 0 ? ranking.nextOffset : ranking.totalCount > response.items.length ? response.items.length : null;
+    const nextOffset = ranking.nextOffset !== void 0 ? ranking.nextOffset : ranking.totalCount > (response.results ?? response.items ?? []).length ? (response.results ?? response.items ?? []).length : null;
     return nextOffset === null ? `ranking exhausted at ${ranking.totalCount}` : `${ranking.totalCount} ranked in total \u2014 papiers browse ${ranking.searchId} --offset ${nextOffset}`;
   }
   return response.page.nextCursor ? "more available \u2014 rerun with --json and pass page.nextCursor via --cursor" : "no more pages";
@@ -5054,7 +5406,9 @@ async function runCli(argv, dependencies = {}) {
     const command = parseCliArgs(argv);
     jsonOutput = command.json;
     if (command.type === "help") {
-      stdout.write(HELP_TEXT);
+      const styled = dependencies.stdout === void 0 && process.stdout.isTTY === true && process.env.NO_COLOR === void 0;
+      stdout.write(`${renderHelp(command, styled)}
+`);
       return 0;
     }
     if (command.type === "version") {
@@ -5126,12 +5480,27 @@ async function runCli(argv, dependencies = {}) {
           json: command.json,
           stdout
         });
-      case "capabilities":
-        writeJson(
-          stdout,
-          await getCapabilities(config, resolveFetch(dependencies.fetch))
+      case "capabilities": {
+        const capabilities = await getCapabilities(
+          config,
+          resolveFetch(dependencies.fetch)
+        );
+        if (command.json) {
+          writeJson(stdout, capabilities);
+          return 0;
+        }
+        const caps = capabilities;
+        stdout.write(
+          `${redactSensitiveText(
+            [
+              `Validation: ok requestId=${String(caps.requestId ?? "")}`,
+              ...formatCapabilityLines(caps)
+            ].join("\n")
+          )}
+`
         );
         return 0;
+      }
       case "tokens-list":
         writeTokenListOutput(
           stdout,
@@ -5198,11 +5567,17 @@ async function runCli(argv, dependencies = {}) {
             request
           );
           if (command.idsOnly) {
-            writeIds(stdout, response.items, {
+            writeIds(stdout, response.results, {
               nulDelimited: command.idsNulDelimited === true
             });
           } else if (command.docIdsOnly) {
-            writeParentDocumentIds(stdout, response.items);
+            writeParentDocumentIds(stdout, response.results);
+          } else if (command.passageIdsOnly) {
+            writeEvidenceIds(stdout, response.results, "passage");
+          } else if (command.highlightIdsOnly) {
+            writeEvidenceIds(stdout, response.results, "highlight");
+          } else if (command.evidenceIdsOnly) {
+            writeEvidenceIds(stdout, response.results);
           } else if (command.pretty) {
             stdout.write(redactSensitiveText(renderPrettyPageOutput(response)));
           } else {
@@ -5218,11 +5593,17 @@ async function runCli(argv, dependencies = {}) {
             command.request
           );
           if (command.idsOnly) {
-            writeIds(stdout, response.items, {
+            writeIds(stdout, response.results, {
               nulDelimited: command.idsNulDelimited === true
             });
           } else if (command.docIdsOnly) {
-            writeParentDocumentIds(stdout, response.items);
+            writeParentDocumentIds(stdout, response.results);
+          } else if (command.passageIdsOnly) {
+            writeEvidenceIds(stdout, response.results, "passage");
+          } else if (command.highlightIdsOnly) {
+            writeEvidenceIds(stdout, response.results, "highlight");
+          } else if (command.evidenceIdsOnly) {
+            writeEvidenceIds(stdout, response.results);
           } else if (command.pretty) {
             stdout.write(redactSensitiveText(renderPrettyPageOutput(response)));
           } else {
@@ -5351,6 +5732,7 @@ function writeAuthLoginOutput(stdout, output, json) {
     return;
   }
   stdout.write("Signed in to Papiers.\n");
+  stdout.write("Next, try: papiers list --limit 5 --pretty\n");
 }
 function writeAuthLogoutOutput(stdout, output, json) {
   if (json) {
@@ -5369,6 +5751,14 @@ function writeAuthLogoutOutput(stdout, output, json) {
   stdout.write(`${redactSensitiveText(lines.join("\n"))}
 `);
 }
+function formatCapabilityLines(capabilities) {
+  return [
+    `Scopes: ${formatUnknownList(capabilities.scopes)}`,
+    `Search kinds: ${formatUnknownList(capabilities.searchKinds)}`,
+    `Read formats: ${formatUnknownList(capabilities.readFormats)}`,
+    `Not ready: ${formatNotReady(capabilities.notReady)}`
+  ];
+}
 function writeAuthInspectOutput(stdout, output, json) {
   if (json) {
     writeJson(stdout, output);
@@ -5384,10 +5774,7 @@ function writeAuthInspectOutput(stdout, output, json) {
         `Account: userId=${String(
           capabilities.account?.userId ?? "unknown"
         )} profile=${String(capabilities.account?.profile ?? "unknown")}`,
-        `Scopes: ${formatUnknownList(capabilities.scopes)}`,
-        `Search kinds: ${formatUnknownList(capabilities.searchKinds)}`,
-        `Read formats: ${formatUnknownList(capabilities.readFormats)}`,
-        `Not ready: ${formatNotReady(capabilities.notReady)}`
+        ...formatCapabilityLines(capabilities)
       ].join("\n")
     )}
 `
@@ -5543,13 +5930,13 @@ function normalizeStdinToken(rawInput) {
   const parts = rawInput.trim().split(/\s+/u).filter(Boolean);
   if (parts.length !== 1) {
     throw new CliUsageError(
-      "Token stdin must contain exactly one Papiers API token."
+      "Token stdin must contain exactly one Papiers API token (starting with pap_live_), with no surrounding whitespace."
     );
   }
   const token = parts[0];
   if (!isPapiersPat(token)) {
     throw new CliUsageError(
-      "Token stdin did not contain a valid Papiers API token."
+      "Token stdin did not contain a valid Papiers API token; expected one starting with pap_live_."
     );
   }
   return token;
@@ -5715,6 +6102,27 @@ function writeParentDocumentIds(stdout, items) {
   stdout.write(ids.length === 0 ? "" : `${ids.join("\n")}
 `);
 }
+function writeEvidenceIds(stdout, results, kind) {
+  const ids = [];
+  for (const result of results) {
+    if (result.kind !== "document") {
+      continue;
+    }
+    for (const evidence of result.evidence) {
+      if (kind !== void 0 && evidence.kind !== kind) {
+        continue;
+      }
+      if (publicReadKindForId(evidence.id) !== evidence.kind) {
+        throw new Error(
+          "Papiers API returned an evidence id that did not match its kind in evidence ID output."
+        );
+      }
+      ids.push(evidence.id);
+    }
+  }
+  stdout.write(ids.length === 0 ? "" : `${ids.join("\n")}
+`);
+}
 async function expandListDocumentIdRequest(request, documentIds, input) {
   const ids = await expandDocumentIdPlaceholders(documentIds, "list", input);
   if (!ids?.length) {
@@ -6036,7 +6444,7 @@ function parseJsonEnvelopeIds(input, context, sourceLabel) {
   }
   if (input.startsWith("[")) {
     throw new CliUsageError(
-      `${context} JSON ${sourceLabel} must be a Papiers envelope with schemaVersion and items[].id.`
+      `${context} JSON ${sourceLabel} must be a Papiers envelope with schemaVersion and items[].id or results[].id.`
     );
   }
   let parsed;
@@ -6049,7 +6457,7 @@ function parseJsonEnvelopeIds(input, context, sourceLabel) {
   }
   if (!parsed || typeof parsed !== "object") {
     throw new CliUsageError(
-      `${context} JSON ${sourceLabel} must be a Papiers envelope with schemaVersion and items[].id.`
+      `${context} JSON ${sourceLabel} must be a Papiers envelope with schemaVersion and items[].id or results[].id.`
     );
   }
   const envelope = parsed;
@@ -6062,7 +6470,7 @@ function parseJsonEnvelopeIds(input, context, sourceLabel) {
     if (envelope.schemaVersion === PAPIERS_SCHEMA_VERSIONS.list) {
       assertPapiersListResponse(`${context} list envelope`, parsed);
     } else if (envelope.schemaVersion === PAPIERS_SCHEMA_VERSIONS.search) {
-      assertPapiersSearchResponse(`${context} search envelope`, parsed);
+      validateSearchPipelineEnvelope(`${context} search envelope`, parsed);
     } else {
       assertPapiersReadPipelineEnvelope(`${context} read envelope`, parsed);
     }
@@ -6074,10 +6482,10 @@ function parseJsonEnvelopeIds(input, context, sourceLabel) {
     }
     throw error;
   }
-  const items = envelope.items;
+  const items = envelope.schemaVersion === PAPIERS_SCHEMA_VERSIONS.search ? envelope.results : envelope.items;
   if (!Array.isArray(items)) {
     throw new CliUsageError(
-      `${context} JSON ${sourceLabel} must be a Papiers envelope with items[].id.`
+      `${context} JSON ${sourceLabel} must be a Papiers envelope with items[].id or results[].id.`
     );
   }
   return items.map((item, index) => {
@@ -6102,6 +6510,19 @@ function parseJsonEnvelopeIds(input, context, sourceLabel) {
     return id;
   });
 }
+function validateSearchPipelineEnvelope(label, parsed) {
+  const envelope = parsed;
+  const ranking = envelope.ranking && typeof envelope.ranking === "object" && !Array.isArray(envelope.ranking) ? envelope.ranking : null;
+  if (ranking && ("offset" in ranking || "nextOffset" in ranking)) {
+    assertPapiersSearchResultsResponse(label, parsed, {
+      schemaVersion: PAPIERS_SCHEMA_VERSIONS.searchResultsRequest,
+      searchId: typeof ranking.searchId === "string" ? ranking.searchId : "",
+      offset: typeof ranking.offset === "number" ? ranking.offset : void 0
+    });
+    return;
+  }
+  assertPapiersSearchResponse(label, parsed);
+}
 function parseTextIds(input) {
   return input.split(/[\s,]+/u).filter(Boolean);
 }
@@ -6120,9 +6541,20 @@ function writeCliError(error, params) {
       `${redactSensitiveText(serialized.body.error.message)}
 `
     );
+    const hint = humanErrorHint(error);
+    if (hint) {
+      params.stderr.write(`${hint}
+`);
+    }
   }
   return serialized.exitCode;
 }
+function humanErrorHint(error) {
+  if (error instanceof PapiersCliApiError && error.status === 401) {
+    return "Your token may be expired or revoked. Run papiers auth login --force to replace it.";
+  }
+  return null;
+}
 function serializeCliError(error) {
   if (error instanceof PapiersCliApiError) {
     return {