papiers 0.1.5 → 0.1.8

package/dist/index.js

@@ -9,6 +9,7 @@ import { realpathSync } from "fs";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/commands.ts
+import { randomUUID as randomUUID2 } from "crypto";
 import { readFile, stat } from "fs/promises";
 import { isAbsolute, resolve as resolve2 } from "path";
 
@@ -412,6 +413,177 @@ function isNodeError(error) {
   return Boolean(error && typeof error === "object" && "code" in error);
 }
 
+// src/contracts.ts
+var PAPIERS_SCHEMA_VERSIONS = {
+  searchRequest: "papiers.search.request.v1",
+  search: "papiers.search.v1",
+  searchResultsRequest: "papiers.search.results.request.v1",
+  listRequest: "papiers.list.request.v1",
+  list: "papiers.list.v1",
+  readRequest: "papiers.read.request.v1",
+  read: "papiers.read.v1",
+  capabilities: "papiers.capabilities.v1",
+  importRequest: "papiers.import.request.v1",
+  import: "papiers.import.v1",
+  highlightRequest: "papiers.highlight.request.v1",
+  highlight: "papiers.highlight.v1",
+  feedLinkRequest: "papiers.discover.feed.link.request.v1",
+  feedLink: "papiers.discover.feed.link.v1",
+  error: "papiers.error.v1"
+};
+var PAPIERS_PUBLIC_DATA_PLANE_SCOPES = [
+  "library:metadata:read",
+  "library:search",
+  "content:search",
+  "content:snippet:read",
+  "content:read",
+  "content:structure:read"
+];
+var PAPIERS_PUBLIC_FEATURE_IDS = [
+  "document_content_read",
+  "non_document_kinds",
+  "content_search",
+  "list_cursors",
+  "read_cursors",
+  "read_section_scopes",
+  "read_context",
+  "read_locations",
+  "ranked_search_cursors",
+  "search_results_browse",
+  "public_id_projection_not_ready",
+  "queryIn:content",
+  "queryIn:all",
+  "queryIn:latex"
+];
+var PAPIERS_SEARCH_QUALITY_SIGNALS = [
+  "high",
+  "medium",
+  "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"],
+  content_search: ["content_search_not_ready"],
+  list_cursors: ["cursor_signing_not_configured"],
+  read_cursors: [
+    "cursor_signing_not_configured",
+    "document_content_read_required"
+  ],
+  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_sessions_not_ready"
+  ]
+};
+var PAPIERS_PUBLIC_ERROR_CODES = [
+  "api_disabled",
+  "auth_missing",
+  "auth_invalid_format",
+  "auth_invalid",
+  "auth_wrong_surface",
+  "auth_scope_missing",
+  "feature_not_available",
+  "filter_not_supported",
+  "invalid_filter_field",
+  "invalid_filter_operator",
+  "invalid_filter_value",
+  "invalid_filter_combination",
+  "order_not_supported",
+  "unsupported_format",
+  "invalid_cursor",
+  "invalid_cursor_context",
+  "forbidden",
+  "invalid_request",
+  "not_found",
+  "source_superseded",
+  "stale_reference",
+  "content_limit_exceeded",
+  "request_limit_exceeded",
+  "rate_limited",
+  "internal_error"
+];
+
+// ../../src/shared/papiers-public-ids.ts
+var PAPIERS_PUBLIC_ID_PREFIX_BY_KIND = {
+  document: "doc",
+  highlight: "hl",
+  conversation: "cnv",
+  section: "sec",
+  figure: "fig",
+  table: "tbl",
+  note: "nte"
+};
+var PAPIERS_PUBLIC_ID_KIND_BY_PREFIX = Object.fromEntries(
+  Object.entries(PAPIERS_PUBLIC_ID_PREFIX_BY_KIND).map(([kind, prefix]) => [
+    prefix,
+    kind
+  ])
+);
+var PAPIERS_PUBLIC_ID_PATTERN = /^(doc|hl|cnv|sec|fig|tbl|nte)_([a-f0-9]{32})$/;
+var PAPIERS_PUBLIC_REF_PATTERN = /^(doc_[a-f0-9]{32})#(?:p(0|[1-9][0-9]{0,9})|e([a-z0-9_]{1,64}))\.([a-f0-9]{8})$/;
+var MAX_CHUNK_INDEX = 2147483647;
+function parsePapiersPublicId(value) {
+  const id = value.trim();
+  const ref = id.match(PAPIERS_PUBLIC_REF_PATTERN);
+  if (ref) {
+    const [, documentId, chunkIndex, astNodeId, fingerprint] = ref;
+    if (chunkIndex !== void 0) {
+      const index = Number(chunkIndex);
+      if (index > MAX_CHUNK_INDEX) return null;
+      return {
+        id,
+        kind: "passage",
+        documentId,
+        chunkIndex: index,
+        fingerprint
+      };
+    }
+    return { id, kind: "equation", documentId, astNodeId, fingerprint };
+  }
+  const match = id.match(PAPIERS_PUBLIC_ID_PATTERN);
+  if (!match) {
+    return null;
+  }
+  const prefix = match[1];
+  const kind = PAPIERS_PUBLIC_ID_KIND_BY_PREFIX[prefix];
+  if (!kind) {
+    return null;
+  }
+  return {
+    id,
+    kind,
+    prefix,
+    opaqueId: match[2]
+  };
+}
+function staleReferenceMessage(kind) {
+  return kind === "passage" ? "Passage text has changed. Search or read the document again." : "Equation text has changed. Search or read the document again.";
+}
+
 // ../../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}`;
@@ -533,54 +705,20 @@ var DOCUMENT_MAX_FILTER_VALUES = DOCUMENT_MAX_IDS;
 var DOCUMENT_DEFAULT_READ_CHARS_PER_ITEM = 5e4;
 var DOCUMENT_MAX_READ_CHARS_PER_ITEM = 2e5;
 var DOCUMENT_MAX_READ_CHARS_PER_REQUEST = 5e5;
-var DOCUMENT_PUBLIC_ID_PATTERN = /^doc_[a-f0-9]{32}$/u;
-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);
 }
-function isDocumentPublicId(value) {
-  return DOCUMENT_PUBLIC_ID_PATTERN.test(value);
-}
-function isPassagePublicId(value) {
-  return PASSAGE_PUBLIC_ID_PATTERN.test(value);
-}
-function isHighlightPublicId(value) {
-  return HIGHLIGHT_PUBLIC_ID_PATTERN.test(value);
-}
-function isConversationPublicId(value) {
-  return CONVERSATION_PUBLIC_ID_PATTERN.test(value);
-}
-function isEquationPublicId(value) {
-  return EQUATION_PUBLIC_ID_PATTERN.test(value);
-}
-function isNotePublicId(value) {
-  return NOTE_PUBLIC_ID_PATTERN.test(value);
-}
+var CLI_READABLE_KINDS = new Set(PUBLIC_KINDS);
 function publicReadKindForId(value) {
-  if (isDocumentPublicId(value)) {
-    return "document";
-  }
-  if (isPassagePublicId(value)) {
-    return "passage";
-  }
-  if (isHighlightPublicId(value)) {
-    return "highlight";
-  }
-  if (isConversationPublicId(value)) {
-    return "conversation";
-  }
-  if (isEquationPublicId(value)) {
-    return "equation";
-  }
-  if (isNotePublicId(value)) {
-    return "note";
+  const parsed = parsePapiersPublicId(value);
+  if (!parsed || parsed.id !== value || !CLI_READABLE_KINDS.has(parsed.kind)) {
+    return null;
   }
-  return null;
+  return parsed.kind;
+}
+function isDocumentPublicId(value) {
+  return publicReadKindForId(value) === "document";
 }
 function readKindForIdentifier(value) {
   const publicKind = publicReadKindForId(value);
@@ -597,118 +735,6 @@ function isPublicIdForKind(value, kind) {
   return publicReadKindForId(value) === kind;
 }
 
-// src/contracts.ts
-var PAPIERS_SCHEMA_VERSIONS = {
-  searchRequest: "papiers.search.request.v1",
-  search: "papiers.search.v1",
-  searchResultsRequest: "papiers.search.results.request.v1",
-  listRequest: "papiers.list.request.v1",
-  list: "papiers.list.v1",
-  readRequest: "papiers.read.request.v1",
-  read: "papiers.read.v1",
-  capabilities: "papiers.capabilities.v1",
-  tokenList: "papiers.tokens.list.response.v1",
-  tokenRevoke: "papiers.tokens.revoke.response.v1",
-  error: "papiers.error.v1"
-};
-var PAPIERS_PUBLIC_DATA_PLANE_SCOPES = [
-  "library:metadata:read",
-  "library:search",
-  "content:search",
-  "content:snippet:read",
-  "content:read",
-  "content:structure:read"
-];
-var PAPIERS_PUBLIC_FEATURE_IDS = [
-  "document_content_read",
-  "non_document_kinds",
-  "content_search",
-  "list_cursors",
-  "read_cursors",
-  "read_section_scopes",
-  "read_context",
-  "read_locations",
-  "ranked_search_cursors",
-  "search_results_browse",
-  "public_id_projection_not_ready",
-  "queryIn:content",
-  "queryIn:all",
-  "queryIn:latex"
-];
-var PAPIERS_SEARCH_QUALITY_SIGNALS = [
-  "high",
-  "medium",
-  "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"],
-  content_search: [
-    "content_search_not_ready",
-    "public_passage_projection_not_ready"
-  ],
-  list_cursors: ["cursor_signing_not_configured"],
-  read_cursors: [
-    "cursor_signing_not_configured",
-    "document_content_read_required"
-  ],
-  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_sessions_not_ready"
-  ]
-};
-var PAPIERS_PUBLIC_ERROR_CODES = [
-  "api_disabled",
-  "auth_missing",
-  "auth_invalid_format",
-  "auth_invalid",
-  "auth_wrong_surface",
-  "auth_scope_missing",
-  "feature_not_available",
-  "filter_not_supported",
-  "invalid_filter_field",
-  "invalid_filter_operator",
-  "invalid_filter_value",
-  "invalid_filter_combination",
-  "order_not_supported",
-  "unsupported_format",
-  "invalid_cursor",
-  "invalid_cursor_context",
-  "forbidden",
-  "invalid_request",
-  "not_found",
-  "source_superseded",
-  "content_limit_exceeded",
-  "request_limit_exceeded",
-  "rate_limited",
-  "internal_error"
-];
-
 // ../../src/shared/papiers-public-source-domain.ts
 var papiers_public_source_domain_exports = {};
 __export(papiers_public_source_domain_exports, {
@@ -799,9 +825,6 @@ function isTokenUuid(value) {
 }
 
 // src/response-validation.ts
-var PUBLIC_DATA_PLANE_SCOPE_SET = new Set(
-  PAPIERS_PUBLIC_DATA_PLANE_SCOPES
-);
 var PUBLIC_ERROR_CODE_SET = new Set(PAPIERS_PUBLIC_ERROR_CODES);
 var SAFE_REQUEST_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/u;
 var LIST_RESPONSE_KEYS = /* @__PURE__ */ new Set([
@@ -850,26 +873,6 @@ var READ_RESPONSE_KEYS = /* @__PURE__ */ new Set([
   "items",
   "usage"
 ]);
-var TOKEN_LIST_RESPONSE_KEYS = /* @__PURE__ */ new Set([
-  "schemaVersion",
-  "requestId",
-  "tokens"
-]);
-var TOKEN_REVOKE_RESPONSE_KEYS = /* @__PURE__ */ new Set([
-  "schemaVersion",
-  "requestId",
-  "tokenId",
-  "revoked"
-]);
-var TOKEN_SUMMARY_KEYS = /* @__PURE__ */ new Set([
-  "tokenId",
-  "name",
-  "scopes",
-  "createdAt",
-  "expiresAt",
-  "revokedAt",
-  "lastUsedAt"
-]);
 var PAGE_KEYS = /* @__PURE__ */ new Set(["nextCursor", "returnedCount"]);
 var READ_USAGE_KEYS = /* @__PURE__ */ new Set(["returnedChars", "truncatedItemCount"]);
 var LIST_DOCUMENT_ITEM_KEYS = /* @__PURE__ */ new Set([
@@ -949,6 +952,7 @@ var READ_SUCCESS_PASSAGE_ITEM_KEYS = /* @__PURE__ */ new Set([
   "truncated",
   "charCount",
   "tokenEstimate",
+  "metadata",
   "warnings"
 ]);
 var READ_SUCCESS_HIGHLIGHT_ITEM_KEYS = /* @__PURE__ */ new Set([
@@ -1056,6 +1060,7 @@ 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 READ_STALE_REFERENCE_CODE = "stale_reference";
 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.";
@@ -1299,28 +1304,64 @@ function assertPapiersReadResponse(label, body, expectedIds, expected = "metadat
 function assertPapiersReadPipelineEnvelope(label, body) {
   validatePapiersReadResponse(label, body);
 }
-function assertPapiersTokenListResponse(label, body) {
-  assertNoInternalResponseKeys(label, body);
-  const value = assertSchema(label, body, PAPIERS_SCHEMA_VERSIONS.tokenList);
-  rejectUnexpectedKeys(label, value, TOKEN_LIST_RESPONSE_KEYS);
+var IMPORT_RESPONSE_KEYS = /* @__PURE__ */ new Set([
+  "schemaVersion",
+  "requestId",
+  "operationId",
+  "status",
+  "documentId",
+  "error"
+]);
+var IMPORT_ERROR_KEYS = new Set(
+  Object.keys({
+    code: true,
+    message: true,
+    retryable: true,
+    details: true
+  })
+);
+var IMPORT_ERROR_DETAIL_KEYS = /* @__PURE__ */ new Set(["importCode"]);
+function assertPapiersImportResponse(label, body) {
+  const value = assertSchema(label, body, PAPIERS_SCHEMA_VERSIONS.import);
+  rejectUnexpectedKeys(label, value, IMPORT_RESPONSE_KEYS);
   assertPublicRequestId(`${label} requestId`, value.requestId);
-  const tokens = assertArray(`${label} tokens`, value.tokens);
-  for (const [index, rawToken] of tokens.entries()) {
-    validateTokenSummary(`${label} token ${index}`, rawToken);
+  assertNonEmptyString(`${label} operationId`, value.operationId);
+  assertNonEmptyString(`${label} status`, value.status);
+  if (value.documentId !== null) {
+    assertDocumentReadIdentifier(`${label} documentId`, value.documentId);
+  }
+  if (value.error !== null) {
+    const error = assertRecord(`${label} error`, value.error);
+    rejectUnexpectedKeys(`${label} error`, error, IMPORT_ERROR_KEYS);
+    assertPublicErrorCode(`${label} error.code`, error.code);
+    assertNonEmptyString(`${label} error.message`, error.message);
+    assertBoolean(`${label} error.retryable`, error.retryable);
+    const details = assertRecord(`${label} error.details`, error.details);
+    rejectUnexpectedKeys(
+      `${label} error.details`,
+      details,
+      IMPORT_ERROR_DETAIL_KEYS
+    );
+    assertNonEmptyString(
+      `${label} error.details.importCode`,
+      details.importCode
+    );
   }
 }
-function assertPapiersTokenRevokeResponse(label, body, expectedTokenId) {
-  assertNoInternalResponseKeys(label, body);
-  const value = assertSchema(label, body, PAPIERS_SCHEMA_VERSIONS.tokenRevoke);
-  rejectUnexpectedKeys(label, value, TOKEN_REVOKE_RESPONSE_KEYS);
+var HIGHLIGHT_RESPONSE_KEYS = /* @__PURE__ */ new Set([
+  "schemaVersion",
+  "requestId",
+  "highlightId"
+]);
+function assertPapiersHighlightResponse(label, body) {
+  const value = assertSchema(label, body, PAPIERS_SCHEMA_VERSIONS.highlight);
+  rejectUnexpectedKeys(label, value, HIGHLIGHT_RESPONSE_KEYS);
   assertPublicRequestId(`${label} requestId`, value.requestId);
-  const tokenId = assertTokenId(`${label} tokenId`, value.tokenId);
-  if (tokenId !== expectedTokenId) {
+  if (typeof value.highlightId !== "string" || !value.highlightId.startsWith("papiers://highlight/")) {
     throw new PapiersCliResponseValidationError(
-      `${label} did not echo the requested token id.`
+      `${label} returned an invalid highlight identifier.`
     );
   }
-  assertBoolean(`${label} revoked`, value.revoked);
 }
 function assertPapiersErrorResponse(label, body, expectedHttpStatus) {
   assertNoInternalResponseKeys(label, body);
@@ -1438,28 +1479,6 @@ function validatePapiersReadResponse(label, body, options = {}) {
     );
   }
 }
-function validateTokenSummary(label, rawToken) {
-  const token = assertRecord(label, rawToken);
-  rejectUnexpectedKeys(label, token, TOKEN_SUMMARY_KEYS);
-  assertTokenId(`${label} tokenId`, token.tokenId);
-  assertNonEmptyString(`${label} name`, token.name);
-  const scopes = assertArray(`${label} scopes`, token.scopes);
-  if (scopes.length === 0) {
-    throw new PapiersCliResponseValidationError(`${label} scopes was empty.`);
-  }
-  for (const [index, rawScope] of scopes.entries()) {
-    const scope = assertNonEmptyString(`${label} scope ${index}`, rawScope);
-    if (!PUBLIC_DATA_PLANE_SCOPE_SET.has(scope)) {
-      throw new PapiersCliResponseValidationError(
-        `${label} scope ${index} was not a public data-plane scope.`
-      );
-    }
-  }
-  assertTimestampString(`${label} createdAt`, token.createdAt);
-  validateOptionalTimestamp(`${label} expiresAt`, token.expiresAt);
-  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()) {
@@ -1807,7 +1826,7 @@ function validateOptionalListSearchMetadata(label, value, kind) {
     );
   }
   if (kind === "passage") {
-    return validatePassageListSearchMetadata(label, value);
+    return validatePassageMetadata(label, value);
   }
   if (kind === "highlight") {
     return validateHighlightMetadata(label, value, assertDocId);
@@ -1821,7 +1840,7 @@ function validateOptionalListSearchMetadata(label, value, kind) {
   }
   return validateEquationReadMetadata(label, value);
 }
-function validatePassageListSearchMetadata(label, value) {
+function validatePassageMetadata(label, value) {
   const metadata = assertRecord(label, value);
   rejectUnexpectedKeys(label, metadata, PASSAGE_METADATA_KEYS);
   const documentId = assertDocId(`${label}.documentId`, metadata.documentId);
@@ -1951,6 +1970,19 @@ function validatePassageReadSuccessItem(label, item, options) {
   const contentResult = validateReadContent(label, item, itemFormat, {
     expectedMaxCharsPerItem: options.expectedMaxCharsPerItem
   });
+  const metadataRequested = options.expectedInclude?.has("metadata") ?? false;
+  if (Object.prototype.hasOwnProperty.call(item, "metadata")) {
+    if (!metadataRequested) {
+      throw new PapiersCliResponseValidationError(
+        `${label} returned metadata that was not requested.`
+      );
+    }
+    validatePassageMetadata(`${label} metadata`, item.metadata);
+  } else if (metadataRequested) {
+    throw new PapiersCliResponseValidationError(
+      `${label} did not return requested metadata.`
+    );
+  }
   const hasReadTruncatedWarning = validateOptionalReadWarnings(
     `${label} warnings`,
     item.warnings,
@@ -2383,7 +2415,8 @@ function validateReadItemError(label, value, kind, expectedFormat) {
   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) {
+  const staleReferenceKind = error.code === READ_STALE_REFERENCE_CODE && (kind === "passage" || kind === "equation") ? kind : null;
+  if (error.code !== DOCUMENT_READ_NOT_FOUND_CODE && !sourceSupersededAllowed && !contentLimitAllowed && !requestLimitAllowed && !staleReferenceKind) {
     throw new PapiersCliResponseValidationError(
       `${label}.code was not a supported read error code.`
     );
@@ -2393,7 +2426,7 @@ function validateReadItemError(label, value, kind, expectedFormat) {
       `${label}.code was not supported for metadata reads.`
     );
   }
-  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;
+  const expectedMessage = staleReferenceKind ? staleReferenceMessage(staleReferenceKind) : 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.`
@@ -2920,14 +2953,6 @@ function assertReadIdentifier(label, value) {
   }
   return value;
 }
-function assertTokenId(label, value) {
-  if (typeof value !== "string" || !isTokenUuid(value)) {
-    throw new PapiersCliResponseValidationError(
-      `${label} was not a token UUID.`
-    );
-  }
-  return value;
-}
 function assertPublicRequestId(label, value) {
   if (typeof value !== "string" || !SAFE_REQUEST_ID_PATTERN.test(value)) {
     throw new PapiersCliResponseValidationError(
@@ -3015,7 +3040,7 @@ async function getCapabilities(config, fetchImpl) {
     config,
     fetchImpl,
     "/api/v1/papiers/capabilities",
-    { method: "GET", retryable: true }
+    { method: "GET" }
   );
   assertPapiersCapabilitiesResponse("capabilities", body);
   return body;
@@ -3026,7 +3051,7 @@ async function listDocuments(config, fetchImpl, request) {
     config,
     fetchImpl,
     "/api/v1/papiers/list",
-    { method: "POST", body: request, retryable: true }
+    { method: "POST", body: request }
   );
   assertPapiersListResponse("list", body, { expectedKind });
   return body;
@@ -3037,7 +3062,7 @@ async function searchDocuments(config, fetchImpl, request) {
     config,
     fetchImpl,
     "/api/v1/papiers/search",
-    { method: "POST", body: request, retryable: true }
+    { method: "POST", body: request }
   );
   assertPapiersSearchResponse("search", body, request.query, expected);
   return body;
@@ -3047,7 +3072,7 @@ async function browseSearchResults(config, fetchImpl, request) {
     config,
     fetchImpl,
     "/api/v1/papiers/search/results",
-    { method: "POST", body: request, retryable: true }
+    { method: "POST", body: request }
   );
   assertPapiersSearchResultsResponse("search results", body, request);
   return body;
@@ -3057,7 +3082,7 @@ async function readDocuments(config, fetchImpl, request) {
     config,
     fetchImpl,
     "/api/v1/papiers/read",
-    { method: "POST", body: request, retryable: true }
+    { method: "POST", body: request }
   );
   const readKind = readKindForIdentifier(request.ids[0] ?? "");
   assertPapiersReadResponse("read", body, request.ids, {
@@ -3070,26 +3095,6 @@ async function readDocuments(config, fetchImpl, request) {
   });
   return body;
 }
-async function listPapiersTokens(config, fetchImpl) {
-  const body = await requestPapiersApi(
-    config,
-    fetchImpl,
-    "/api/v1/papiers/tokens",
-    { method: "GET", retryable: true }
-  );
-  assertPapiersTokenListResponse("tokens list", body);
-  return body;
-}
-async function revokePapiersToken(config, fetchImpl, tokenId) {
-  const body = await requestPapiersApi(
-    config,
-    fetchImpl,
-    `/api/v1/papiers/tokens/${encodeURIComponent(tokenId)}/revoke`,
-    { method: "POST" }
-  );
-  assertPapiersTokenRevokeResponse("tokens revoke", body, tokenId);
-  return body;
-}
 function expectedKindForListSearchRequest(request) {
   const kinds = request.kinds;
   if (kinds === void 0) {
@@ -3135,6 +3140,48 @@ function expectedKindsForSearchRequest(request) {
   const [onlyKind] = expectedKinds;
   return expectedKinds.size === 1 ? { expectedKind: onlyKind } : { expectedKinds };
 }
+async function importDocument(config, fetchImpl, request) {
+  const body = await requestPapiersApi(
+    config,
+    fetchImpl,
+    "/api/v1/papiers/imports",
+    { method: "POST", body: request }
+  );
+  assertPapiersImportResponse("import", body);
+  return body;
+}
+async function getImportStatus(config, fetchImpl, operationId) {
+  const body = await requestPapiersApi(
+    config,
+    fetchImpl,
+    `/api/v1/papiers/imports/${encodeURIComponent(operationId)}`,
+    { method: "GET" }
+  );
+  assertPapiersImportResponse("import-status", body);
+  return body;
+}
+async function highlightDocument(config, fetchImpl, request) {
+  const body = await requestPapiersApi(
+    config,
+    fetchImpl,
+    "/api/v1/papiers/highlights",
+    // Outlasts the server's 10 s queue wait plus 20 s search, so its answer
+    // arrives.
+    { method: "POST", body: request, timeoutMs: 4e4 }
+  );
+  assertPapiersHighlightResponse("highlight", body);
+  return body;
+}
+var FEED_PATH = "/api/v1/papiers/discover/feed";
+function addFeedLink(config, fetchImpl, link) {
+  return requestPapiersApi(config, fetchImpl, FEED_PATH, {
+    method: "POST",
+    body: {
+      schemaVersion: PAPIERS_SCHEMA_VERSIONS.feedLinkRequest,
+      ...link
+    }
+  });
+}
 async function requestPapiersApi(config, fetchImpl, path, init) {
   if (!config.token) {
     throw new CliUsageError(
@@ -3164,10 +3211,13 @@ async function requestPapiersApiWithBearer(config, fetchImpl, bearerToken, path,
     headers["content-type"] = "application/json";
     requestInit.body = JSON.stringify(init.body);
   }
-  const response = await fetchWithRetry(fetchImpl, requestUrl, requestInit, {
-    retryable: init.retryable === true
-  });
-  const body = await parseResponseBody(response);
+  const { response, text } = await fetchWithRetry(
+    fetchImpl,
+    requestUrl,
+    requestInit,
+    init.timeoutMs ?? REQUEST_TIMEOUT_MS
+  );
+  const body = parseResponseBody(text);
   if (!response.ok) {
     const errorEnvelope = extractErrorEnvelope(body, response.status);
     throw new PapiersCliApiError({
@@ -3179,44 +3229,45 @@ async function requestPapiersApiWithBearer(config, fetchImpl, bearerToken, path,
   }
   return body;
 }
-async function fetchWithRetry(fetchImpl, requestUrl, requestInit, options) {
-  const maxAttempts = options.retryable ? MAX_REQUEST_ATTEMPTS : 1;
+async function fetchWithRetry(fetchImpl, requestUrl, requestInit, timeoutMs) {
   let attempt = 1;
   while (true) {
     let response;
+    let text;
     try {
       response = await fetchImpl(requestUrl, {
         ...requestInit,
-        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+        signal: AbortSignal.timeout(timeoutMs)
       });
+      text = await response.text();
     } catch (error) {
-      if (attempt >= maxAttempts) {
+      if (attempt >= MAX_REQUEST_ATTEMPTS) {
         throw error;
       }
       await sleep(RETRY_BACKOFF_MS[attempt - 1] ?? 1e3);
       attempt += 1;
       continue;
     }
-    if (attempt < maxAttempts && RETRYABLE_STATUS_CODES.has(response.status)) {
-      await sleep(retryDelayMs(response, attempt));
+    const delayMs = retryDelayMs(response, attempt);
+    if (attempt < MAX_REQUEST_ATTEMPTS && RETRYABLE_STATUS_CODES.has(response.status) && delayMs <= MAX_RETRY_AFTER_MS) {
+      await sleep(delayMs);
       attempt += 1;
       continue;
     }
-    return response;
+    return { response, text };
   }
 }
 function retryDelayMs(response, attempt) {
   const retryAfterSeconds = Number(response.headers.get("retry-after") ?? "");
   if (Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0) {
-    return Math.min(retryAfterSeconds * 1e3, MAX_RETRY_AFTER_MS);
+    return retryAfterSeconds * 1e3;
   }
   return RETRY_BACKOFF_MS[attempt - 1] ?? 1e3;
 }
 function sleep(ms) {
   return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
 }
-async function parseResponseBody(response) {
-  const text = await response.text();
+function parseResponseBody(text) {
   if (!text) {
     return null;
   }
@@ -3241,6 +3292,30 @@ function formatApiErrorMessage(params) {
   return `Papiers API error ${params.status}.`;
 }
 
+// ../../src/shared/highlight-colors.ts
+var HIGHLIGHT_HEX_COLOR_REGEX = /^#[0-9a-f]{6}$/;
+
+// ../../src/shared/papiers-public-api.ts
+var PAPIERS_PUBLIC_DATA_PLANE_SCOPES2 = [
+  "library:metadata:read",
+  "library:search",
+  "content:search",
+  "content:snippet:read",
+  "content:read",
+  "content:structure:read"
+];
+var PAPIERS_WRITE_SCOPES = [
+  "library:import",
+  "library:highlight",
+  "discover:feed"
+];
+var PAPIERS_PUBLIC_SCOPES = [
+  ...PAPIERS_PUBLIC_DATA_PLANE_SCOPES2,
+  ...PAPIERS_WRITE_SCOPES
+];
+var PAPIERS_HIGHLIGHT_MAX_SCOPE_PAGES = 20;
+var PAPIERS_HIGHLIGHT_MAX_PAGE = 1e4;
+
 // src/filters.ts
 var FILTER_OPERATORS = [
   "eq",
@@ -3709,7 +3784,17 @@ var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "fail-fast",
   "version"
 ]);
+var HIGHLIGHT_VALUE_FLAGS = [
+  "start",
+  "end",
+  "passage",
+  "pages",
+  "note",
+  "color"
+];
 var VALUE_FLAGS = /* @__PURE__ */ new Set([
+  ...HIGHLIGHT_VALUE_FLAGS,
+  "reason",
   "api-url",
   "cursor",
   "document-id",
@@ -3827,8 +3912,10 @@ COMMANDS
   list          List your documents, highlights, notes, and conversations
   read          Print a document, highlight, note, or conversation
   browse        Page through an earlier search's results
+  import        Add a public PDF or webpage to your library
+  highlight     Highlight a passage in a saved document
+  feed          Add links to your Discover feed
   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
 
@@ -3886,12 +3973,12 @@ USAGE
   papiers list --kind highlight|conversation [--since WHEN]
 
 OPTIONS
-  --kind KIND          document (default) \xB7 passage \xB7 highlight \xB7 conversation \xB7 equation \xB7 note.
+  --kind KIND          document (default) \xB7 highlight \xB7 conversation \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.
+                       document and highlight only; highlight also takes papiers://item/\u2026 locators.
   --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.
@@ -3916,7 +4003,7 @@ OPTIONS
                        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).
+                       document only (passage/highlight/conversation/equation/note: metadata only).
   --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
@@ -3959,13 +4046,54 @@ 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.
+  import: `papiers import \u2014 add a public PDF or webpage to your library.
+
+USAGE
+  papiers import URL [--json]
+  papiers import-status OPERATION_ID [--json]
+
+Needs a token created with "Allow document imports" (Settings -> API tokens).
+Import only sources the user approved. An import is queued, not finished:
+check import-status until it is ready or failed; any other status means it
+is still in progress. Ready means papiers read works on its documentId now.
+A status is as of that check: reprocessing or trashing the document can
+change it later.`,
+  feed: `papiers feed \u2014 add links to your own Discover feed.
 
 USAGE
-  papiers tokens list [--json]
-  papiers tokens revoke TOKEN_ID [--json]
+  papiers feed add URL [--reason TEXT] [--json]
 
-Create and name tokens in Papiers (Settings -> API tokens). Revoking is permanent.`,
+Needs a token created with "Allow adding to your Discover feed" (Settings ->
+API tokens). A link shows in the user's Discover feed, labeled with the
+token's name and your reason, once Papiers has prepared it (usually within
+minutes); it never adds to their library. Give a short reason in your own
+words: why this user would want it. Sending a link again updates its reason.
+Links must be public pages: not paywalled, with no sign-in or private token.
+The user's plan sets how many new links it takes; past that, the answer says
+when to try again. The answer says whether the link is preparing, ready or
+failed; send it again to see how it is now.`,
+  highlight: `papiers highlight \u2014 highlight a passage in a saved PDF or webpage.
+
+USAGE
+  papiers highlight DOCUMENT_ID --start TEXT [--end TEXT]
+    [--passage PASSAGE_REF | --pages N[-M]]
+    [--note TEXT] [--color #rrggbb] [--json]
+
+Needs a token created with "Allow highlights" (Settings -> API tokens).
+DOCUMENT_ID is a doc_ ID or papiers://item/... locator. In a PDF, name what you
+read: --passage is the reference of a search result in this document
+(doc_\u2026#p\u2026.\u2026), --pages the page or pages (3, 3-4 or 3,5) you read it on. The
+passage is only looked for there; a webpage is searched whole and takes neither.
+--start is the passage's first words (or all of a short passage); --end its
+last words, for a longer passage or one crossing a formula. The highlight runs
+from --start through --end, so formulas and footnote marks between need not be
+quoted; if either repeats within reach (that page and the next, a few
+paragraphs), add words to it. Quote both as you read them; punctuation, hyphens,
+spacing and formatting don't matter. Keep math out of --start and --end, even
+a single symbol like V or \u03B2t: what you read spells it differently from the
+page, so start and end on plain words. If the passage appears more than once,
+add words until it is unique. Highlight only passages the user asked for or
+approved.`,
   doctor: `papiers doctor \u2014 check your setup, connection, and what's available.
 
 USAGE
@@ -3981,10 +4109,18 @@ USAGE
 var REFERENCE = `REFERENCE \u2014 IDs, piping, pagination, and limits.
 
 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.
+  doc_   document        hl_    highlight       cnv_   conversation
+  nte_   note            srch_  a saved search ranking (for browse)
+  On read, the kind \u2014 and which --format/--include apply \u2014 is read from the ID.
+
+PASSAGES AND EQUATIONS
+  A passage or equation is a place in a document plus a fingerprint of its text:
+    doc_<id>#p12.3f9c01aa        passage 12 of that document
+    doc_<id>#enode_812.77d0e2b1  an equation in that document
+  It keeps working while that text is unchanged. If the document is processed
+  again and the text changed, you get stale_reference: search or read the
+  document again. Quote references in the shell ('doc_\u2026#p12.3f9c01aa'): some
+  shells treat # specially.
 
 RESOURCE LOCATORS
   papiers://note/<uuid>          papiers://highlight/<uuid>
@@ -4041,11 +4177,12 @@ var SUGGESTIBLE_COMMANDS = [
   "auth",
   "doctor",
   "capabilities",
-  "tokens",
   "list",
   "search",
   "browse",
   "read",
+  "import",
+  "highlight",
   "version",
   "help"
 ];
@@ -4098,7 +4235,8 @@ function parseCliArgs(argv) {
     if (parsed.booleanFlags.has("all")) {
       return { type: "help", all: true, ...global };
     }
-    const topic = command === "help" ? rest[0] : command;
+    const named = command === "help" ? rest[0] : command;
+    const topic = named === "import-status" ? "import" : named;
     if (topic && HELP_TOPIC_NAMES.includes(topic)) {
       return { type: "help", topic, ...global };
     }
@@ -4125,14 +4263,72 @@ function parseCliArgs(argv) {
       );
       assertNoExtraPositionals(command, rest);
       return { type: "capabilities", ...global };
-    case "tokens":
-      assertAllowedFlags(parsed, NO_COMMAND_VALUE_FLAGS, "tokens");
-      return parseTokensCommand(rest, parsed, global);
+    case "import":
+    case "import-status": {
+      assertAllowedFlags(parsed, NO_COMMAND_VALUE_FLAGS, command);
+      assertAllowedBooleanFlags(parsed, NO_COMMAND_BOOLEAN_FLAGS, command);
+      const [target, ...extra] = rest;
+      assertNoExtraPositionals(command, extra);
+      if (!target) {
+        throw new CliUsageError(
+          command === "import" ? "papiers import requires a URL." : "papiers import-status requires an operation ID."
+        );
+      }
+      return command === "import" ? { type: "import", ...global, url: target } : { type: "import-status", ...global, operationId: target };
+    }
+    case "feed":
+      return parseFeedCommand(rest, parsed, global);
+    case "highlight": {
+      assertAllowedFlags(
+        parsed,
+        /* @__PURE__ */ new Set([...GLOBAL_VALUE_FLAGS, ...HIGHLIGHT_VALUE_FLAGS]),
+        command
+      );
+      assertAllowedBooleanFlags(parsed, NO_COMMAND_BOOLEAN_FLAGS, command);
+      const [documentId, ...extra] = rest;
+      assertNoExtraPositionals(command, extra);
+      const start = singleFlagValue(parsed, "start");
+      if (!documentId || !start) {
+        throw new CliUsageError(
+          "papiers highlight requires a document ID and --start."
+        );
+      }
+      const passageId = singleFlagValue(parsed, "passage");
+      const pagesFlag = singleFlagValue(parsed, "pages");
+      if (passageId !== void 0 && pagesFlag !== void 0) {
+        throw new CliUsageError("Give --passage or --pages, not both.");
+      }
+      const color = singleFlagValue(parsed, "color");
+      if (color !== void 0 && !HIGHLIGHT_HEX_COLOR_REGEX.test(color)) {
+        throw new CliUsageError(
+          "--color must be a lowercase #rrggbb hex color, like #fde68a."
+        );
+      }
+      const optional = (name) => {
+        const value = singleFlagValue(parsed, name);
+        return value === void 0 ? {} : { [name]: value };
+      };
+      return {
+        type: "highlight",
+        ...global,
+        documentId,
+        start,
+        ...optional("end"),
+        ...passageId === void 0 ? {} : { passageId },
+        ...pagesFlag === void 0 ? {} : { pages: parsePages(pagesFlag) },
+        ...optional("note"),
+        ...optional("color")
+      };
+    }
     case "list": {
       assertAllowedFlags(parsed, LIST_VALUE_FLAGS, "list");
       assertAllowedBooleanFlags(parsed, IDS_PIPELINE_BOOLEAN_FLAGS, "list");
       assertNoExtraPositionals(command, rest);
-      const listDocumentIds = parseDocumentIdFlagValues(parsed, "list");
+      const listDocumentIds = parseDocumentIdFlagValues(
+        parsed,
+        "list",
+        parseListKind(parsed) === "highlight"
+      );
       const listOutput = parseIdsOutput(parsed, "list");
       return {
         type: "list",
@@ -4226,33 +4422,31 @@ function parsePrettyOutput(parsed, idsOnly) {
   }
   return true;
 }
-function parseTokensCommand(rest, parsed, global) {
-  const [subcommand, tokenId, ...extra] = rest;
+function parseFeedCommand(rest, parsed, global) {
+  const [subcommand, target, ...extra] = rest;
+  const name = `feed ${subcommand ?? ""}`.trim();
+  assertAllowedBooleanFlags(parsed, NO_COMMAND_BOOLEAN_FLAGS, name);
   switch (subcommand) {
-    case "list":
-      assertAllowedBooleanFlags(
+    case "add": {
+      assertAllowedFlags(
         parsed,
-        NO_COMMAND_BOOLEAN_FLAGS,
-        "tokens list"
+        /* @__PURE__ */ new Set([...GLOBAL_VALUE_FLAGS, "reason"]),
+        name
       );
-      assertNoExtraPositionals("tokens list", rest.slice(1));
-      return { type: "tokens-list", ...global };
-    case "revoke":
-      assertAllowedBooleanFlags(
-        parsed,
-        NO_COMMAND_BOOLEAN_FLAGS,
-        "tokens revoke"
-      );
-      if (!tokenId) {
-        throw new CliUsageError("papiers tokens revoke requires a token UUID.");
-      }
-      assertNoExtraPositionals("tokens revoke", extra);
-      if (!isUuid(tokenId)) {
-        throw new CliUsageError("papiers tokens revoke requires a token UUID.");
-      }
-      return { type: "tokens-revoke", ...global, tokenId };
+      assertNoExtraPositionals(name, extra);
+      if (!target) throw new CliUsageError("papiers feed add requires a URL.");
+      const reason = singleFlagValue(parsed, "reason");
+      return {
+        type: "feed-add",
+        ...global,
+        url: target,
+        ...reason !== void 0 ? { reason } : {}
+      };
+    }
     default:
-      throw new CliUsageError("Supported tokens commands: list, revoke.");
+      throw new CliUsageError(
+        "papiers feed takes add. Run papiers feed --help."
+      );
   }
 }
 function parseAuthCommand(rest, parsed, global) {
@@ -4357,7 +4551,7 @@ function buildReadRequest(parsed) {
   };
 }
 function buildListRequest(parsed, documentIds) {
-  const kind = parseListSearchKind(parsed, "list");
+  const kind = parseListKind(parsed);
   const since = parseSinceFlag(parsed, kind, "list");
   if (kind !== "document") {
     if (documentIds?.length && kind !== "highlight") {
@@ -4495,7 +4689,7 @@ function parseSinceFlag(parsed, kind, command) {
   }
   return new Date(parsedMs).toISOString();
 }
-function parseDocumentIdFlagValues(parsed, command) {
+function parseDocumentIdFlagValues(parsed, command, acceptsItemLocators = false) {
   const rawDocumentIds = parsed.flags.get("document-id");
   if (!rawDocumentIds?.length) {
     return void 0;
@@ -4513,9 +4707,10 @@ function parseDocumentIdFlagValues(parsed, command) {
       `papiers ${command} --document-id file references must include a file path after @.`
     );
   }
-  if (documentIds.some((id) => !isDocumentIdSource(id) && !isDocumentPublicId(id))) {
+  const isDocumentId = acceptsItemLocators ? isDocumentReadIdentifier : isDocumentPublicId;
+  if (documentIds.some((id) => !isDocumentIdSource(id) && !isDocumentId(id))) {
     throw new CliUsageError(
-      `papiers ${command} --document-id currently accepts only doc_* IDs.`
+      acceptsItemLocators ? `papiers ${command} --document-id accepts only doc_* IDs or papiers://item locators.` : `papiers ${command} --document-id currently accepts only doc_* IDs.`
     );
   }
   const explicitDocumentIdCount = documentIds.filter(
@@ -4649,7 +4844,13 @@ function validateReadOptionsForKind(parsed, kind, format) {
         "Public passage read supports --format markdown or --format plain."
       );
     }
-    rejectReadFlagsForKind(parsed, "passage", ["include", "pages", "cursor"]);
+    const includes = parseReadInclude(parsed);
+    if (includes?.some((include) => include !== "metadata")) {
+      throw new CliUsageError(
+        "Public passage read supports only --include metadata."
+      );
+    }
+    rejectReadFlagsForKind(parsed, "passage", ["pages", "cursor"]);
     return;
   }
   if (kind === "highlight") {
@@ -4834,19 +5035,24 @@ function parseGlobalOptions(parsed) {
     apiBaseUrl: singleFlagValue(parsed, "api-url")
   };
 }
-function parseListSearchKind(parsed, command) {
+function parseListKind(parsed) {
   const kind = singleFlagValue(parsed, "kind") ?? "document";
   const normalized = normalizeCliPublicKind(kind);
+  if (normalized === "passage" || normalized === "equation") {
+    throw new CliUsageError(
+      `papiers list does not list ${normalized}s. Read a document (papiers read doc_\u2026) to page through its ${normalized}s in order, or search for them.`
+    );
+  }
   if (normalized) {
     return normalized;
   }
   if (kind.trim().toLowerCase() === "all") {
     throw new CliUsageError(
-      `papiers ${command} does not support --kind all here; multi-kind requests are available via papiers search --kind all.`
+      "papiers list does not support --kind all here; multi-kind requests are available via papiers search --kind all."
     );
   }
   throw new CliUsageError(
-    `papiers ${command} supports --kind document, passage, highlight, conversation, equation, or note; received "${kind}".${didYouMeanKind(kind)}`
+    `papiers list supports --kind document, highlight, conversation, or note; received "${kind}".${didYouMeanKind(kind)}`
   );
 }
 function normalizeCliPublicKind(value) {
@@ -5025,11 +5231,6 @@ function singleFlagValue(parsed, name) {
   }
   return values[0];
 }
-function isUuid(value) {
-  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu.test(
-    value
-  );
-}
 function splitCommaSeparatedValues(rawValue) {
   return rawValue.split(",").map((value) => value.trim()).filter(Boolean);
 }
@@ -5045,6 +5246,26 @@ function pruneUndefined(value) {
     Object.entries(value).filter(([, entry]) => entry !== void 0)
   );
 }
+function parsePages(value) {
+  const pages = [];
+  for (const part of value.split(",")) {
+    const match = /^\s*(\d+)\s*(?:-\s*(\d+)\s*)?$/.exec(part);
+    const first = match ? Number(match[1]) : Number.NaN;
+    const last = match?.[2] ? Number(match[2]) : first;
+    if (!(first >= 1 && first <= last && last <= PAPIERS_HIGHLIGHT_MAX_PAGE)) {
+      throw new CliUsageError(
+        `--pages must be a page, a range like 3-4, or a list like 3,5, of pages up to ${PAPIERS_HIGHLIGHT_MAX_PAGE}.`
+      );
+    }
+    if (pages.length + (last - first + 1) > PAPIERS_HIGHLIGHT_MAX_SCOPE_PAGES) {
+      throw new CliUsageError(
+        `--pages can name at most ${PAPIERS_HIGHLIGHT_MAX_SCOPE_PAGES} pages.`
+      );
+    }
+    for (let page = first; page <= last; page++) pages.push(page);
+  }
+  return pages;
+}
 
 // src/capabilities.ts
 var CAPABILITIES_ACCOUNT_KEYS = [
@@ -5074,11 +5295,11 @@ function assertSupportedDocumentCapabilities(value) {
   assertNonEmptyString2("capabilities account.userId", account.userId);
   assertExactString("capabilities account.profile", account.profile, "pat-v1");
   const scopes = assertStringArray("capabilities scopes", capabilities.scopes);
-  assertSameStringSet(
-    "capabilities scopes",
-    scopes,
-    PAPIERS_PUBLIC_DATA_PLANE_SCOPES
-  );
+  if (!PAPIERS_PUBLIC_DATA_PLANE_SCOPES.every((s) => scopes.includes(s))) {
+    throw new Error(
+      `capabilities scopes was ${scopes.join(", ") || "empty"}; expected every public read scope.`
+    );
+  }
   const searchKinds = assertStringArray(
     "capabilities searchKinds",
     capabilities.searchKinds
@@ -5740,22 +5961,45 @@ async function runCli(argv, dependencies = {}) {
         );
         return 0;
       }
-      case "tokens-list":
-        writeTokenListOutput(
+      case "feed-add":
+        writeJson(
+          stdout,
+          await addFeedLink(config, resolveFetch(dependencies.fetch), {
+            url: command.url,
+            ...command.reason !== void 0 ? { reason: command.reason } : {}
+          })
+        );
+        return 0;
+      case "import":
+        writeJson(
           stdout,
-          await listPapiersTokens(config, resolveFetch(dependencies.fetch)),
-          command.json
+          await importDocument(config, resolveFetch(dependencies.fetch), {
+            schemaVersion: PAPIERS_SCHEMA_VERSIONS.importRequest,
+            url: command.url,
+            submissionId: randomUUID2()
+          })
         );
         return 0;
-      case "tokens-revoke":
-        writeTokenRevokeOutput(
+      case "highlight": {
+        const { type: _, json: __, apiBaseUrl: ___, ...highlight } = command;
+        writeJson(
           stdout,
-          await revokePapiersToken(
+          await highlightDocument(config, resolveFetch(dependencies.fetch), {
+            schemaVersion: PAPIERS_SCHEMA_VERSIONS.highlightRequest,
+            ...highlight,
+            referenceId: randomUUID2()
+          })
+        );
+        return 0;
+      }
+      case "import-status":
+        writeJson(
+          stdout,
+          await getImportStatus(
             config,
             resolveFetch(dependencies.fetch),
-            command.tokenId
-          ),
-          command.json
+            command.operationId
+          )
         );
         return 0;
       case "list":
@@ -6016,50 +6260,6 @@ function writeAuthInspectOutput(stdout, output, json) {
 `
   );
 }
-function writeTokenListOutput(stdout, output, json) {
-  if (json) {
-    writeJson(stdout, output);
-    return;
-  }
-  if (output.tokens.length === 0) {
-    stdout.write(
-      `No active Papiers tokens found. requestId=${output.requestId}
-`
-    );
-    return;
-  }
-  const lines = [
-    `Papiers tokens requestId=${output.requestId}`,
-    ...output.tokens.map(
-      (token) => [
-        token.tokenId,
-        token.name,
-        `scopes=${token.scopes.join(",")}`,
-        `created=${token.createdAt}`,
-        `expires=${token.expiresAt ?? "never"}`,
-        `lastUsed=${token.lastUsedAt ?? "never"}`
-      ].join(" | ")
-    )
-  ];
-  stdout.write(`${redactSensitiveText(lines.join("\n"))}
-`);
-}
-function writeTokenRevokeOutput(stdout, output, json) {
-  if (json) {
-    writeJson(stdout, output);
-    return;
-  }
-  const state = output.revoked ? "revoked" : "already revoked";
-  stdout.write(
-    `${redactSensitiveText(
-      [
-        `Token ${output.tokenId} ${state}. requestId=${output.requestId}`,
-        "Local auth files were not changed; run papiers auth logout if this was your configured token."
-      ].join("\n")
-    )}
-`
-  );
-}
 async function runAuthInspect(params) {
   const capabilities = await getCapabilities(params.config, params.fetchImpl);
   assertCliSupportedCapabilities(capabilities);
@@ -6613,9 +6813,9 @@ function validateExpandedReadRequest(request, ids, requestedReadKind) {
         "Public passage read supports --format markdown or --format plain."
       );
     }
-    if (request.include?.length) {
+    if (request.include?.some((include) => include !== "metadata")) {
       throw new CliUsageError(
-        "Public passage read does not support --include."
+        "Public passage read supports only --include metadata."
       );
     }
     if (request.scope?.pages || request.scope?.sectionId) {