papiers 0.1.2 → 0.1.4

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
@@ -412,23 +412,41 @@ function isNodeError(error) {
   return Boolean(error && typeof error === "object" && "code" in error);
 }
 
+// ../../src/shared/papiers-resource-locators.ts
+var UUID_PATTERN = "[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}";
+var PAPIERS_RESOURCE_LOCATOR_PATTERN_SOURCE = `papiers://(?:note|highlight|item|conversation|artifact)/${UUID_PATTERN}`;
+var RESOURCE_LOCATOR_PATTERN = new RegExp(
+  `^papiers://(note|highlight|item|conversation|artifact)/(${UUID_PATTERN})$`,
+  "u"
+);
+var UUID_REGEX = new RegExp(`^${UUID_PATTERN}$`, "iu");
+var READ_KIND_BY_LOCATOR_KIND = {
+  note: "note",
+  highlight: "highlight",
+  item: "document",
+  conversation: "conversation",
+  artifact: "artifact"
+};
+function parsePapiersResourceLocator(value) {
+  const match = RESOURCE_LOCATOR_PATTERN.exec(value);
+  if (!match) return null;
+  const kind = match[1];
+  return {
+    value,
+    kind,
+    readKind: READ_KIND_BY_LOCATOR_KIND[kind],
+    internalId: match[2].toLowerCase()
+  };
+}
+
 // src/document-contract.ts
 var PUBLIC_KINDS = [
   "document",
   "passage",
   "highlight",
   "conversation",
-  "equation"
-];
-var EXPECTED_DOCUMENT_QUERY_IN = [
-  "title",
-  "metadata"
-];
-var EXPECTED_CONTENT_QUERY_IN = [
-  "content"
-];
-var EXPECTED_EQUATION_QUERY_IN = [
-  "latex"
+  "equation",
+  "note"
 ];
 var EXPECTED_DOCUMENT_READ_FORMATS = [
   "metadata",
@@ -450,6 +468,10 @@ var EXPECTED_CONVERSATION_READ_FORMATS = [
 var EXPECTED_EQUATION_READ_FORMATS = [
   "metadata"
 ];
+var EXPECTED_NOTE_READ_FORMATS = [
+  "markdown",
+  "plain"
+];
 var DOCUMENT_READ_REQUEST_FORMATS = [
   ...EXPECTED_DOCUMENT_READ_FORMATS,
   "auto"
@@ -478,10 +500,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"],
@@ -513,6 +538,7 @@ var PASSAGE_PUBLIC_ID_PATTERN = /^pas_[a-f0-9]{32}$/u;
 var HIGHLIGHT_PUBLIC_ID_PATTERN = /^hl_[a-f0-9]{32}$/u;
 var CONVERSATION_PUBLIC_ID_PATTERN = /^cnv_[a-f0-9]{32}$/u;
 var EQUATION_PUBLIC_ID_PATTERN = /^eq_[a-f0-9]{32}$/u;
+var NOTE_PUBLIC_ID_PATTERN = /^nte_[a-f0-9]{32}$/u;
 var SEARCH_RANKING_ID_PATTERN = /^srch_[a-f0-9]{32}$/u;
 function isSearchRankingId(value) {
   return SEARCH_RANKING_ID_PATTERN.test(value);
@@ -532,6 +558,9 @@ function isConversationPublicId(value) {
 function isEquationPublicId(value) {
   return EQUATION_PUBLIC_ID_PATTERN.test(value);
 }
+function isNotePublicId(value) {
+  return NOTE_PUBLIC_ID_PATTERN.test(value);
+}
 function publicReadKindForId(value) {
   if (isDocumentPublicId(value)) {
     return "document";
@@ -548,8 +577,22 @@ function publicReadKindForId(value) {
   if (isEquationPublicId(value)) {
     return "equation";
   }
+  if (isNotePublicId(value)) {
+    return "note";
+  }
   return null;
 }
+function readKindForIdentifier(value) {
+  const publicKind = publicReadKindForId(value);
+  if (publicKind) {
+    return publicKind;
+  }
+  const locatorKind = parsePapiersResourceLocator(value)?.readKind;
+  return locatorKind === "artifact" ? null : locatorKind ?? null;
+}
+function isDocumentReadIdentifier(value) {
+  return isDocumentPublicId(value) || parsePapiersResourceLocator(value)?.kind === "item";
+}
 function isPublicIdForKind(value, kind) {
   return publicReadKindForId(value) === kind;
 }
@@ -598,6 +641,27 @@ var PAPIERS_SEARCH_QUALITY_SIGNALS = [
   "low",
   "empty"
 ];
+var PAPIERS_SEARCH_RESULT_KINDS = [
+  "document",
+  "conversation",
+  "note"
+];
+var PAPIERS_SEARCH_EVIDENCE_KINDS = [
+  "passage",
+  "highlight",
+  "equation"
+];
+var PAPIERS_SEARCH_MATCH_REASONS = [
+  "title",
+  "doi",
+  "arxivId",
+  "pmid",
+  "passage",
+  "highlight",
+  "equation",
+  "conversation",
+  "note"
+];
 var PAPIERS_PUBLIC_NOT_READY_REASONS_BY_FEATURE = {
   document_content_read: ["explicit_enablement_required"],
   non_document_kinds: ["public_id_projection_not_ready"],
@@ -613,7 +677,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",
@@ -636,6 +703,8 @@ var PAPIERS_PUBLIC_ERROR_CODES = [
   "invalid_request",
   "not_found",
   "source_superseded",
+  "content_limit_exceeded",
+  "request_limit_exceeded",
   "rate_limited",
   "internal_error"
 ];
@@ -746,7 +815,7 @@ var SEARCH_RESPONSE_KEYS = /* @__PURE__ */ new Set([
   "requestId",
   "query",
   "quality",
-  "items",
+  "results",
   "page",
   "ranking",
   "warnings"
@@ -760,6 +829,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.";
@@ -771,6 +843,7 @@ var RANKED_SEARCH_CURSOR_WARNING_MESSAGES = /* @__PURE__ */ new Set([
 var DOCUMENT_READ_TRUNCATED_WARNING_CODE = "read_truncated";
 var DOCUMENT_READ_TRUNCATED_WARNING_MESSAGE = "Document content was truncated by public read limits.";
 var PASSAGE_READ_TRUNCATED_WARNING_MESSAGE = "Passage content was truncated by public read limits.";
+var NOTE_READ_TRUNCATED_WARNING_MESSAGE = "Note content was truncated by public read limits.";
 var READ_RESPONSE_KEYS = /* @__PURE__ */ new Set([
   "schemaVersion",
   "requestId",
@@ -821,6 +894,37 @@ 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_NOTE_RESULT_KEYS = /* @__PURE__ */ new Set([
+  ...SEARCH_RESULT_BASE_KEYS,
+  "snippet",
+  "metadata"
+]);
+var SEARCH_EVIDENCE_KEYS = /* @__PURE__ */ new Set([
+  "kind",
+  "id",
+  "rank",
+  "snippet",
+  "score"
+]);
 var READ_SUCCESS_DOCUMENT_ITEM_KEYS = /* @__PURE__ */ new Set([
   "id",
   "kind",
@@ -866,6 +970,19 @@ var READ_SUCCESS_EQUATION_ITEM_KEYS = /* @__PURE__ */ new Set([
   "format",
   "metadata"
 ]);
+var READ_SUCCESS_NOTE_ITEM_KEYS = /* @__PURE__ */ new Set([
+  "id",
+  "kind",
+  "ok",
+  "format",
+  "content",
+  "truncated",
+  "charCount",
+  "tokenEstimate",
+  "metadata",
+  "nextCursor",
+  "warnings"
+]);
 var READ_ERROR_DOCUMENT_ITEM_KEYS = /* @__PURE__ */ new Set(["id", "kind", "ok", "error"]);
 var READ_ITEM_ERROR_KEYS = /* @__PURE__ */ new Set(["code", "message", "retryable"]);
 var HIGHLIGHT_READ_METADATA_KEYS = /* @__PURE__ */ new Set([
@@ -875,6 +992,8 @@ var HIGHLIGHT_READ_METADATA_KEYS = /* @__PURE__ */ new Set([
   "anchorType",
   "annotationText",
   "quoteContext",
+  "quotePrefix",
+  "quoteSuffix",
   "createdAt",
   "updatedAt"
 ]);
@@ -896,6 +1015,14 @@ var EQUATION_READ_METADATA_KEYS = /* @__PURE__ */ new Set([
   "nodeType",
   "updatedAt"
 ]);
+var NOTE_READ_METADATA_KEYS = /* @__PURE__ */ new Set([
+  "documentId",
+  "attachedTitle",
+  "editedAt",
+  "createdAt",
+  "updatedAt",
+  "title"
+]);
 var READ_LOCATIONS_KEYS = /* @__PURE__ */ new Set(["pages", "scope", "truncated"]);
 var READ_LOCATION_PAGE_KEYS = /* @__PURE__ */ new Set(["page", "sections"]);
 var READ_LOCATION_SCOPE_KEYS = /* @__PURE__ */ new Set(["pages"]);
@@ -927,9 +1054,16 @@ var PASSAGE_READ_NOT_FOUND_MESSAGE = "Passage is not available.";
 var HIGHLIGHT_READ_NOT_FOUND_MESSAGE = "Highlight is not available.";
 var CONVERSATION_READ_NOT_FOUND_MESSAGE = "Conversation is not available.";
 var EQUATION_READ_NOT_FOUND_MESSAGE = "Equation is not available.";
+var NOTE_READ_NOT_FOUND_MESSAGE = "Note is not available.";
 var DOCUMENT_READ_SOURCE_SUPERSEDED_CODE = "source_superseded";
+var CONVERSATION_READ_CONTENT_LIMIT_CODE = "content_limit_exceeded";
+var CONVERSATION_READ_REQUEST_LIMIT_CODE = "request_limit_exceeded";
 var DOCUMENT_READ_SOURCE_SUPERSEDED_MESSAGE = "Document content is not available for the current source.";
+var NOTE_READ_SOURCE_SUPERSEDED_MESSAGE = "Note content changed since this cursor was issued.";
 var PASSAGE_READ_CONTENT_UNAVAILABLE_MESSAGE = "Passage content is not available.";
+var CONVERSATION_READ_SOURCE_SUPERSEDED_MESSAGE = "Conversation source is no longer available. Search again for a current result.";
+var CONVERSATION_READ_CONTENT_LIMIT_MESSAGE = "Conversation content exceeds the public read limit.";
+var CONVERSATION_READ_REQUEST_LIMIT_MESSAGE = "Conversation read batch is too large. Retry this item in a smaller batch.";
 var PUBLIC_CURSOR_BASE64URL_PATTERN = /^[A-Za-z0-9_-]{1,4096}$/u;
 var PUBLIC_CURSOR_SIGNATURE_PATTERN = /^[A-Za-z0-9_-]{43}$/u;
 var PUBLIC_CURSOR_HASH_PATTERN = /^[A-Za-z0-9_-]{43}$/u;
@@ -989,6 +1123,8 @@ var INTERNAL_RESPONSE_KEYS = /* @__PURE__ */ new Set([
   "latexTokens",
   "library_item_id",
   "libraryItemId",
+  "note_id",
+  "noteId",
   "actor_id",
   "actorId",
   "owner_user_id",
@@ -1012,7 +1148,7 @@ var INTERNAL_RESPONSE_KEYS = /* @__PURE__ */ new Set([
   "last_used_ip_hash",
   "lastUsedIpHash"
 ]);
-var UNSAFE_PUBLIC_EXCERPT_MARKER_PATTERN = /\b(?:artifact_id|artifactId|astNodeId|atom_id|atomId|branchKey|contentHash|conversation_id|conversationId|current_artifact_id|currentArtifactId|current_internal_target_json|currentInternalTargetJson|internal_locator|internalLocator|latexTokens|library_item_id|libraryItemId|actor_id|actorId|owner_user_id|ownerUserId|secret_hash|secretHash|source_id|sourceId|source_url|sourceUrl|source_locator|sourceLocator|source_locator_hash|sourceLocatorHash|source_locator_json|sourceLocatorJson|projectionHash|search_row_id|searchRowId|last_used_ip_hash|lastUsedIpHash)\b/u;
+var UNSAFE_PUBLIC_EXCERPT_MARKER_PATTERN = /\b(?:artifact_id|artifactId|astNodeId|atom_id|atomId|branchKey|contentHash|conversation_id|conversationId|current_artifact_id|currentArtifactId|current_internal_target_json|currentInternalTargetJson|internal_locator|internalLocator|latexTokens|library_item_id|libraryItemId|note_id|noteId|actor_id|actorId|owner_user_id|ownerUserId|secret_hash|secretHash|source_id|sourceId|source_url|sourceUrl|source_locator|sourceLocator|source_locator_hash|sourceLocatorHash|source_locator_json|sourceLocatorJson|projectionHash|search_row_id|searchRowId|last_used_ip_hash|lastUsedIpHash)\b/u;
 var UNSAFE_PUBLIC_EXCERPT_URL_PATTERN = /\bhttps?:\/\/\S+[?&](?:access_token|key|secret|sig|signature|token)=/iu;
 var UNSAFE_PUBLIC_EXCERPT_SIGNED_URL_PATTERN = /\bsigned[_-]?url\b/iu;
 var CLI_DOCUMENT_READ_FORMAT_SET = new Set(
@@ -1050,17 +1186,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 +1211,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 +1246,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;
@@ -1243,10 +1371,10 @@ function validatePapiersReadResponse(label, body, options = {}) {
   const expectedInclude = options.expectedInclude ? new Set(options.expectedInclude) : void 0;
   for (const [index, rawItem] of items.entries()) {
     const item = assertRecord(`${label} item ${index}`, rawItem);
-    const id = assertReadPublicId(`${label} item ${index} id`, item.id);
+    const id = assertReadIdentifier(`${label} item ${index} id`, item.id);
     if (options.expectedIds !== void 0 && id !== options.expectedIds[index]) {
       throw new PapiersCliResponseValidationError(
-        `${label} did not echo the requested public ids in order.`
+        `${label} did not echo the requested identifiers in order.`
       );
     }
     const kind = validateReadItemKind(
@@ -1332,6 +1460,190 @@ 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.`
+      );
+    }
+    switch (kind) {
+      case "document":
+        validateSearchDocumentResult(`${label} result ${index}`, result);
+        break;
+      case "conversation":
+        validateSearchConversationResult(`${label} result ${index}`, result);
+        break;
+      case "note":
+        validateSearchNoteResult(`${label} result ${index}`, result);
+        break;
+    }
+  }
+  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";
+  }
+  if (value === "note" && isPublicIdForKind(id, "note")) {
+    return "note";
+  }
+  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 validateSearchNoteResult(label, result) {
+  rejectUnexpectedKeys(label, result, SEARCH_NOTE_RESULT_KEYS);
+  const id = assertNonEmptyString(`${label} id`, result.id);
+  if (!isPublicIdForKind(id, "note")) {
+    throw new PapiersCliResponseValidationError(
+      `${label} id was not an nte_* public id.`
+    );
+  }
+  assertPositiveInteger(`${label} rank`, result.rank);
+  validateSearchScore(`${label} score`, result.score);
+  validateSearchMatchedBy(`${label} matchedBy`, result.matchedBy, {
+    allow: /* @__PURE__ */ new Set(["note"])
+  });
+  validateOptionalNullableString(`${label} title`, result.title);
+  validateOptionalPublicExcerpt(`${label} snippet`, result.snippet);
+  validateNoteMetadata(`${label} metadata`, result.metadata, assertDocId);
+}
+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 }
@@ -1472,9 +1784,9 @@ function validateOptionalDocumentIdForKind(label, value, kind) {
     }
     return void 0;
   }
-  if (kind === "conversation") {
+  if (kind === "conversation" || kind === "note") {
     throw new PapiersCliResponseValidationError(
-      `${label} was not supported for conversation items.`
+      `${label} was not supported for ${kind} items.`
     );
   }
   return assertDocId(label, value);
@@ -1498,12 +1810,15 @@ function validateOptionalListSearchMetadata(label, value, kind) {
     return validatePassageListSearchMetadata(label, value);
   }
   if (kind === "highlight") {
-    return validateHighlightReadMetadata(label, value);
+    return validateHighlightMetadata(label, value, assertDocId);
   }
   if (kind === "conversation") {
     validateConversationReadMetadata(label, value);
     return void 0;
   }
+  if (kind === "note") {
+    return validateNoteMetadata(label, value, assertDocId);
+  }
   return validateEquationReadMetadata(label, value);
 }
 function validatePassageListSearchMetadata(label, value) {
@@ -1534,11 +1849,54 @@ function validateReadSuccessItem(label, item, kind, options) {
       return validateConversationReadSuccessItem(label, item, options);
     case "equation":
       return validateEquationReadSuccessItem(label, item, options);
+    case "note":
+      return validateNoteReadSuccessItem(label, item, options);
   }
 }
+function validateNoteReadSuccessItem(label, item, options) {
+  rejectUnexpectedKeys(label, item, READ_SUCCESS_NOTE_ITEM_KEYS);
+  const itemFormat = validateCliReadFormat(`${label} format`, item.format);
+  if (!EXPECTED_NOTE_READ_FORMATS.some((format) => format === itemFormat)) {
+    throw new PapiersCliResponseValidationError(
+      `${label} format was not supported for note reads.`
+    );
+  }
+  if (options.expectedFormat !== void 0 && !isResolvedReadFormatAllowed(itemFormat, options.expectedFormat)) {
+    throw new PapiersCliResponseValidationError(
+      `${label} did not echo the requested read format.`
+    );
+  }
+  const contentResult = validateReadContent(label, item, itemFormat, {
+    expectedMaxCharsPerItem: options.expectedMaxCharsPerItem
+  });
+  validateReadItemCursor(
+    label,
+    item.nextCursor,
+    itemFormat,
+    contentResult.truncated,
+    options.singleItemRead
+  );
+  validateNoteMetadata(
+    `${label} metadata`,
+    item.metadata,
+    assertDocumentReadIdentifier
+  );
+  const hasReadTruncatedWarning = validateOptionalReadWarnings(
+    `${label} warnings`,
+    item.warnings,
+    itemFormat,
+    "note"
+  );
+  if (hasReadTruncatedWarning && !contentResult.truncated) {
+    throw new PapiersCliResponseValidationError(
+      `${label} returned read_truncated without truncated=true.`
+    );
+  }
+  return { ...contentResult, contentRead: true };
+}
 function validateDocumentReadSuccessItem(label, item, options) {
   rejectUnexpectedKeys(label, item, READ_SUCCESS_DOCUMENT_ITEM_KEYS);
-  assertDocId(`${label} id`, item.id);
+  assertDocumentReadIdentifier(`${label} id`, item.id);
   const itemFormat = validateCliReadFormat(`${label} format`, item.format);
   if (options.expectedFormat !== void 0 && !isResolvedReadFormatAllowed(itemFormat, options.expectedFormat)) {
     throw new PapiersCliResponseValidationError(
@@ -1660,11 +2018,19 @@ function validateHighlightReadSuccessItem(label, item, options) {
   }
   if (itemFormat === "plain") {
     const contentResult = validatePlainReadContentFields(label, item);
-    validateHighlightReadMetadata(`${label} metadata`, item.metadata);
+    validateHighlightMetadata(
+      `${label} metadata`,
+      item.metadata,
+      assertDocumentReadIdentifier
+    );
     return { ...contentResult, contentRead: true };
   }
   rejectMetadataOnlyContentFields(label, item);
-  validateHighlightReadMetadata(`${label} metadata`, item.metadata);
+  validateHighlightMetadata(
+    `${label} metadata`,
+    item.metadata,
+    assertDocumentReadIdentifier
+  );
   return { returnedChars: 0, truncated: false, contentRead: false };
 }
 function validateConversationReadSuccessItem(label, item, options) {
@@ -1706,18 +2072,21 @@ function validateEquationReadSuccessItem(label, item, options) {
   return { returnedChars: 0, truncated: false, contentRead: false };
 }
 function validateReadItemKind(label, value, id) {
-  const expectedKind = publicReadKindForId(id);
-  if (expectedKind === null || value !== expectedKind || value !== "document" && value !== "passage" && value !== "highlight" && value !== "conversation" && value !== "equation") {
+  const expectedKind = readKindForIdentifier(id);
+  if (expectedKind === null || value !== expectedKind || value !== "document" && value !== "passage" && value !== "highlight" && value !== "conversation" && value !== "equation" && value !== "note") {
     throw new PapiersCliResponseValidationError(
-      `${label} did not match the public id kind.`
+      `${label} did not match the read identifier kind.`
     );
   }
   return value;
 }
-function validateHighlightReadMetadata(label, value) {
+function validateHighlightMetadata(label, value, validateDocumentId) {
   const metadata = assertRecord(label, value);
   rejectUnexpectedKeys(label, metadata, HIGHLIGHT_READ_METADATA_KEYS);
-  const documentId = assertDocId(`${label}.documentId`, metadata.documentId);
+  const documentId = validateDocumentId(
+    `${label}.documentId`,
+    metadata.documentId
+  );
   validateOptionalNullableString(
     `${label}.documentTitle`,
     metadata.documentTitle
@@ -1736,6 +2105,8 @@ function validateHighlightReadMetadata(label, value) {
     `${label}.quoteContext`,
     metadata.quoteContext
   );
+  validateOptionalNullableString(`${label}.quotePrefix`, metadata.quotePrefix);
+  validateOptionalNullableString(`${label}.quoteSuffix`, metadata.quoteSuffix);
   validateOptionalTimestamp(`${label}.createdAt`, metadata.createdAt);
   validateOptionalTimestamp(`${label}.updatedAt`, metadata.updatedAt);
   return documentId;
@@ -1767,6 +2138,21 @@ function validateEquationReadMetadata(label, value) {
   validateOptionalTimestamp(`${label}.updatedAt`, metadata.updatedAt);
   return documentId;
 }
+function validateNoteMetadata(label, value, validateDocumentId) {
+  const metadata = assertRecord(label, value);
+  rejectUnexpectedKeys(label, metadata, NOTE_READ_METADATA_KEYS);
+  const documentId = metadata.documentId === null ? void 0 : validateDocumentId(`${label}.documentId`, metadata.documentId);
+  if (metadata.attachedTitle !== null && typeof metadata.attachedTitle !== "string") {
+    throw new PapiersCliResponseValidationError(
+      `${label}.attachedTitle was not a string or null.`
+    );
+  }
+  assertTimestampString(`${label}.editedAt`, metadata.editedAt);
+  assertTimestampString(`${label}.createdAt`, metadata.createdAt);
+  assertTimestampString(`${label}.updatedAt`, metadata.updatedAt);
+  assertNonEmptyString(`${label}.title`, metadata.title);
+  return documentId;
+}
 function rejectUnexpectedContent(label, item) {
   if (item.content !== void 0 && item.content !== null) {
     throw new PapiersCliResponseValidationError(
@@ -1994,19 +2380,20 @@ function validateReadUsage(label, rawUsage, options) {
 function validateReadItemError(label, value, kind, expectedFormat) {
   const error = assertRecord(label, value);
   rejectUnexpectedKeys(label, error, READ_ITEM_ERROR_KEYS);
-  if (error.code !== DOCUMENT_READ_NOT_FOUND_CODE) {
-    if (kind !== "document" && kind !== "passage" || error.code !== DOCUMENT_READ_SOURCE_SUPERSEDED_CODE) {
-      throw new PapiersCliResponseValidationError(
-        `${label}.code was not a supported read error code.`
-      );
-    }
+  const sourceSupersededAllowed = error.code === DOCUMENT_READ_SOURCE_SUPERSEDED_CODE && (kind === "document" || kind === "passage" || kind === "note" || kind === "conversation");
+  const contentLimitAllowed = error.code === CONVERSATION_READ_CONTENT_LIMIT_CODE && kind === "conversation";
+  const requestLimitAllowed = error.code === CONVERSATION_READ_REQUEST_LIMIT_CODE && kind === "conversation";
+  if (error.code !== DOCUMENT_READ_NOT_FOUND_CODE && !sourceSupersededAllowed && !contentLimitAllowed && !requestLimitAllowed) {
+    throw new PapiersCliResponseValidationError(
+      `${label}.code was not a supported read error code.`
+    );
   }
-  if (expectedFormat === "metadata" && error.code === DOCUMENT_READ_SOURCE_SUPERSEDED_CODE) {
+  if (expectedFormat === "metadata" && (error.code === DOCUMENT_READ_SOURCE_SUPERSEDED_CODE || error.code === CONVERSATION_READ_CONTENT_LIMIT_CODE || error.code === CONVERSATION_READ_REQUEST_LIMIT_CODE)) {
     throw new PapiersCliResponseValidationError(
       `${label}.code was not supported for metadata reads.`
     );
   }
-  const expectedMessage = error.code === DOCUMENT_READ_NOT_FOUND_CODE ? readNotFoundMessageForKind(kind) : kind === "passage" ? PASSAGE_READ_CONTENT_UNAVAILABLE_MESSAGE : DOCUMENT_READ_SOURCE_SUPERSEDED_MESSAGE;
+  const expectedMessage = error.code === DOCUMENT_READ_NOT_FOUND_CODE ? readNotFoundMessageForKind(kind) : error.code === CONVERSATION_READ_CONTENT_LIMIT_CODE ? CONVERSATION_READ_CONTENT_LIMIT_MESSAGE : error.code === CONVERSATION_READ_REQUEST_LIMIT_CODE ? CONVERSATION_READ_REQUEST_LIMIT_MESSAGE : kind === "conversation" ? CONVERSATION_READ_SOURCE_SUPERSEDED_MESSAGE : kind === "passage" ? PASSAGE_READ_CONTENT_UNAVAILABLE_MESSAGE : kind === "note" ? NOTE_READ_SOURCE_SUPERSEDED_MESSAGE : DOCUMENT_READ_SOURCE_SUPERSEDED_MESSAGE;
   if (error.message !== expectedMessage) {
     throw new PapiersCliResponseValidationError(
       `${label}.message was not a supported read error message.`
@@ -2031,6 +2418,8 @@ function readNotFoundMessageForKind(kind) {
       return CONVERSATION_READ_NOT_FOUND_MESSAGE;
     case "equation":
       return EQUATION_READ_NOT_FOUND_MESSAGE;
+    case "note":
+      return NOTE_READ_NOT_FOUND_MESSAGE;
   }
 }
 function validateOptionalSearchQuality(label, value) {
@@ -2095,7 +2484,7 @@ function validateOptionalReadWarnings(label, value, format, kind) {
       );
     }
     hasReadTruncatedWarning = true;
-    const expectedMessage = kind === "document" ? DOCUMENT_READ_TRUNCATED_WARNING_MESSAGE : PASSAGE_READ_TRUNCATED_WARNING_MESSAGE;
+    const expectedMessage = kind === "document" ? DOCUMENT_READ_TRUNCATED_WARNING_MESSAGE : kind === "passage" ? PASSAGE_READ_TRUNCATED_WARNING_MESSAGE : NOTE_READ_TRUNCATED_WARNING_MESSAGE;
     if (warning.message !== expectedMessage) {
       throw new PapiersCliResponseValidationError(
         `${label} ${index}.message was not a supported warning message.`
@@ -2515,10 +2904,18 @@ function assertDocId(label, value) {
   }
   return value;
 }
-function assertReadPublicId(label, value) {
-  if (typeof value !== "string" || publicReadKindForId(value) === null) {
+function assertDocumentReadIdentifier(label, value) {
+  if (typeof value !== "string" || !isDocumentReadIdentifier(value)) {
     throw new PapiersCliResponseValidationError(
-      `${label} was not a supported public read id.`
+      `${label} was not a doc_* public id or papiers://item locator.`
+    );
+  }
+  return value;
+}
+function assertReadIdentifier(label, value) {
+  if (typeof value !== "string" || readKindForIdentifier(value) === null) {
+    throw new PapiersCliResponseValidationError(
+      `${label} was not a supported read identifier.`
     );
   }
   return value;
@@ -2662,7 +3059,7 @@ async function readDocuments(config, fetchImpl, request) {
     "/api/v1/papiers/read",
     { method: "POST", body: request, retryable: true }
   );
-  const readKind = publicReadKindForId(request.ids[0] ?? "");
+  const readKind = readKindForIdentifier(request.ids[0] ?? "");
   assertPapiersReadResponse("read", body, request.ids, {
     // Every kind resolves an omitted format server-side (auto semantics),
     // so there is nothing to echo-check unless the caller pinned one;
@@ -2709,22 +3106,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", "note"]) };
   }
-  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 +3126,19 @@ function expectedKindsForSearchRequest(request) {
       );
     }
   }
-  return {
-    expectedKinds: new Set(kinds)
-  };
+  const expectedKinds = /* @__PURE__ */ new Set();
+  for (const kind of rawKinds) {
+    expectedKinds.add(
+      kind === "conversation" || kind === "note" ? kind : "document"
+    );
+  }
+  const [onlyKind] = expectedKinds;
+  return expectedKinds.size === 1 ? { expectedKind: onlyKind } : { expectedKinds };
 }
 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 +3260,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 +3269,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 +3315,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 +3408,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 +3694,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 +3728,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 +3745,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 +3791,320 @@ 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"],
-  ["equations", "equation"]
+  ["conversations", "conversation"],
+  ["equations", "equation"],
+  ["notes", "note"]
 ]);
 var MULTI_SEARCH_KINDS = [
   "passage",
   "highlight",
-  "conversation"
+  "conversation",
+  "equation",
+  "note"
 ];
-var HELP_TEXT = `Papiers CLI
+var GLOBAL_HELP = `Papiers CLI: search and read your library from the terminal.
+Your saved papers, highlights, notes, 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, notes, and conversations
+  read          Print a document, highlight, note, 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, notes, conversations, and matching titles. Or focus on one:
+                       passage \xB7 highlight \xB7 conversation \xB7 equation \xB7 note.
+  --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, notes, 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 \xB7 note.
+  --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, notes, 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]
+  Read public IDs or papiers://note|highlight|item|conversation/<uuid> locators; don't mix resource 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.   note: markdown|plain.
+                       equation: metadata.
+  --include SECTION    extra sections, comma-separated: metadata, source, locations.
+                       document only (highlight/conversation/equation/note: 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 or note \u2014 use items[].nextCursor from the
+                       previous response. One literal document or note identifier 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 nte_<id> --format markdown --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        nte_   note
+  srch_  a saved search ranking (for browse)
+  On read, the kind \u2014 and which --format/--include apply \u2014 is read from the prefix.
+
+RESOURCE LOCATORS
+  papiers://note/<uuid>          papiers://highlight/<uuid>
+  papiers://item/<uuid>          papiers://conversation/<uuid>
+  Locators are accepted by read and resolved with the same ownership checks as public IDs.
+
+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 identifiers from stdin          @file   read identifiers from a file
+  --input0     read piped identifiers NUL-separated instead of whitespace/newlines
+  @- and @file accept IDs, resource locators, or a Papiers JSON envelope, and may be mixed with literals.
+
+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 NOTE_OR_DOCUMENT --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 +4138,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 +4148,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 +4172,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 +4185,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 +4209,7 @@ function parseCliArgs(argv) {
       };
     }
     default:
-      throw new CliUsageError("Unknown papiers command.");
+      throw new CliUsageError(unknownCommandMessage(command));
   }
 }
 function argvWantsJson(argv) {
@@ -3594,9 +4219,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 +4261,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,
@@ -3683,7 +4302,7 @@ function buildReadRequest(parsed) {
   const ids = orderedReadIdValues(parsed);
   if (ids.length === 0) {
     throw new CliUsageError(
-      "papiers read requires at least one doc_*, pas_*, hl_*, cnv_*, or eq_* ID."
+      "papiers read requires at least one public ID or papiers:// resource locator."
     );
   }
   if (ids.filter((id) => id === "@-").length > 1) {
@@ -3697,7 +4316,7 @@ function buildReadRequest(parsed) {
   const literalKinds = readKindsForLiteralIds(ids);
   if (literalKinds.length > 1) {
     throw new CliUsageError(
-      "papiers read IDs must all use the same public resource kind."
+      "papiers read identifiers must all use the same resource kind."
     );
   }
   const inferredKind = literalKinds[0] ?? requestedKind ?? "document";
@@ -3713,9 +4332,9 @@ function buildReadRequest(parsed) {
   }
   const format = parseReadFormat(parsed, inferredKind);
   const cursor = singleFlagValue(parsed, "cursor");
-  if (cursor !== void 0 && (inferredKind !== "document" || ids.length !== 1 || ids.some((id) => isDocumentIdSource(id)) || !isDocumentPublicId(ids[0]))) {
+  if (cursor !== void 0 && (inferredKind !== "document" && inferredKind !== "note" || ids.length !== 1 || ids.some((id) => isDocumentIdSource(id)) || readKindForIdentifier(ids[0]) !== inferredKind)) {
     throw new CliUsageError(
-      "papiers read --cursor requires exactly one literal doc_* ID."
+      "papiers read --cursor requires exactly one literal document or note identifier."
     );
   }
   if (cursor !== void 0 && format !== "auto" && !DOCUMENT_CONTENT_READ_FORMATS.some((supported) => supported === format)) {
@@ -3792,104 +4411,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")) {
-    throw new CliUsageError(
-      "papiers search --since is supported only with --kind highlight or conversation."
-    );
-  }
-  if (queryIn === "latex") {
+  if (parsed.flags.has("query-in")) {
     throw new CliUsageError(
-      "papiers search --query-in latex requires --kind equation."
+      "papiers search no longer supports --query-in; use free-text query plus --filter FIELD.OP=VALUE for structured attributes."
     );
   }
-  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, equation, or note; 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, equation, or note; 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 +4544,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, equation, or note only; received "${kind}".${didYouMeanKind(kind)}`
   );
 }
 function readKindsForLiteralIds(ids) {
@@ -3973,10 +4553,10 @@ function readKindsForLiteralIds(ids) {
     if (isDocumentIdSource(id)) {
       continue;
     }
-    const kind = publicReadKindForId(id);
+    const kind = readKindForIdentifier(id);
     if (!kind) {
       throw new CliUsageError(
-        "papiers read currently accepts only doc_*, pas_*, hl_*, cnv_*, or eq_* IDs."
+        "papiers read accepts public IDs or papiers://note, highlight, item, and conversation locators."
       );
     }
     kinds.add(kind);
@@ -4023,13 +4603,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);
@@ -4072,6 +4664,21 @@ function validateReadOptionsForKind(parsed, kind, format) {
     });
     return;
   }
+  if (kind === "note") {
+    if (format !== "auto" && !EXPECTED_NOTE_READ_FORMATS.some((supported) => supported === format)) {
+      throw new CliUsageError(
+        "Public note read supports --format markdown, plain, or auto."
+      );
+    }
+    const includes = parseReadInclude(parsed);
+    if (includes?.some((include) => include !== "metadata")) {
+      throw new CliUsageError(
+        "Public note read supports only --include metadata."
+      );
+    }
+    rejectReadFlagsForKind(parsed, kind, ["pages"]);
+    return;
+  }
   validateMetadataReadOptionsForKind(parsed, kind, format, {
     supportedFormats: EXPECTED_EQUATION_READ_FORMATS
   });
@@ -4190,7 +4797,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 +4829,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 +4846,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, equation, or note; 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 +4908,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 +5091,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
@@ -4592,6 +5153,13 @@ function assertSupportedDocumentCapabilities(value) {
           EXPECTED_EQUATION_READ_FORMATS
         );
         continue;
+      case "note":
+        assertOptionalReadFormats(
+          `capabilities readFormatsByKind.${kind}`,
+          actualFormats,
+          EXPECTED_NOTE_READ_FORMATS
+        );
+        continue;
       default:
         assertSameStringSet(
           `capabilities readFormatsByKind.${kind}`,
@@ -4619,7 +5187,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 +5295,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 +5519,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 +5536,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 +5645,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 +5719,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 +5806,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 +5832,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 {
@@ -5280,16 +5900,13 @@ async function runAuthLogin(params) {
   }
   assertSafeBearerApiBaseUrl(params.config.apiBaseUrl);
   const token = await loginWithPatStdin(params);
-  const validationConfig = cliConfigWithToken(
-    params.config,
-    token,
-    "stdin"
+  const validationConfig = cliConfigWithToken(params.config, token, "stdin");
+  const capabilities = await getCapabilities(
+    validationConfig,
+    params.fetchImpl
   );
-  let capabilities;
-  capabilities = await getCapabilities(validationConfig, params.fetchImpl);
   assertCliSupportedCapabilities(capabilities);
-  let update;
-  update = writeLocalAuthToken({
+  const update = writeLocalAuthToken({
     root: params.envRoot,
     token,
     apiBaseUrl: params.config.apiBaseUrl
@@ -5351,6 +5968,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 +5987,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 +6010,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 +6166,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;
@@ -5698,7 +6321,8 @@ function writeParentDocumentIds(stdout, items) {
   const seen = /* @__PURE__ */ new Set();
   const ids = [];
   for (const item of items) {
-    const docId = item.kind === "document" ? item.id : item.documentId;
+    const metadataDocumentId = item.kind === "note" && typeof item.metadata === "object" && item.metadata !== null && !Array.isArray(item.metadata) ? item.metadata.documentId : void 0;
+    const docId = item.kind === "document" ? item.id : item.documentId ?? metadataDocumentId;
     if (typeof docId !== "string" || !docId) {
       continue;
     }
@@ -5715,6 +6339,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) {
@@ -5940,23 +6585,23 @@ function validateReadIds(ids, context, sourceLabel) {
   }
   const kinds = /* @__PURE__ */ new Set();
   for (const [index, id] of ids.entries()) {
-    const kind = publicReadKindForId(id);
+    const kind = readKindForIdentifier(id);
     if (!kind) {
       throw new CliUsageError(
-        `${context} ${sourceLabel} item ${index + 1} was not a doc_*, pas_*, hl_*, cnv_*, or eq_* ID.`
+        `${context} ${sourceLabel} item ${index + 1} was not a public ID or papiers:// resource locator.`
       );
     }
     kinds.add(kind);
   }
   if (kinds.size > 1) {
     throw new CliUsageError(
-      `${context} ${sourceLabel} IDs must all use the same public resource kind.`
+      `${context} ${sourceLabel} identifiers must all use the same resource kind.`
     );
   }
   return ids;
 }
 function validateExpandedReadRequest(request, ids, requestedReadKind) {
-  const kind = publicReadKindForId(ids[0] ?? "");
+  const kind = readKindForIdentifier(ids[0] ?? "");
   if (requestedReadKind && kind && requestedReadKind !== kind) {
     throw new CliUsageError(
       `papiers read --kind ${requestedReadKind} does not match ${kind} IDs.`
@@ -5987,6 +6632,25 @@ function validateExpandedReadRequest(request, ids, requestedReadKind) {
   }
   if (kind === "equation") {
     validateMetadataOnlyReadRequest(request, kind);
+    return;
+  }
+  if (kind === "note") {
+    validateNoteReadRequest(request);
+  }
+}
+function validateNoteReadRequest(request) {
+  if (request.format !== void 0 && request.format !== "auto" && request.format !== "markdown" && request.format !== "plain") {
+    throw new CliUsageError(
+      "Public note read supports --format markdown, plain, or auto."
+    );
+  }
+  if (request.include?.some((include) => include !== "metadata")) {
+    throw new CliUsageError(
+      "Public note read supports only --include metadata."
+    );
+  }
+  if (request.scope?.pages || request.scope?.sectionId) {
+    throw new CliUsageError("Public note read does not support --pages.");
   }
 }
 function validateContentCapableReadRequest(request, kind) {
@@ -6036,7 +6700,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 +6713,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 +6726,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 +6738,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) => {
@@ -6093,15 +6757,28 @@ function parseJsonEnvelopeIds(input, context, sourceLabel) {
       );
     }
     const kind = item.kind;
-    const idKind = publicReadKindForId(id);
+    const idKind = envelope.schemaVersion === PAPIERS_SCHEMA_VERSIONS.read ? readKindForIdentifier(id) : publicReadKindForId(id);
     if (kind !== idKind) {
       throw new CliUsageError(
-        `${context} JSON item ${index} kind did not match its public id.`
+        `${context} JSON item ${index} kind did not match its identifier.`
       );
     }
     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 +6797,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 {