papiers 0.1.5 → 0.1.7

package/README.md

@@ -2,8 +2,10 @@
 
 Search and read your Papiers library from the terminal.
 
-The CLI is read-only: it can inspect your saved documents, highlights, notes,
-and conversations, but it cannot change your library.
+The CLI can inspect your saved documents, highlights, notes, and
+conversations. It changes your library only to import a public PDF or webpage
+(`papiers import --help`) or highlight a passage in a saved PDF or webpage
+(`papiers highlight --help`), and only with a token that allows it.
 
 ## Install
 

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,63 @@ function isNodeError(error) {
   return Boolean(error && typeof error === "object" && "code" in 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 +591,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);
@@ -607,8 +631,10 @@ var PAPIERS_SCHEMA_VERSIONS = {
   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",
+  importRequest: "papiers.import.request.v1",
+  import: "papiers.import.v1",
+  highlightRequest: "papiers.highlight.request.v1",
+  highlight: "papiers.highlight.v1",
   error: "papiers.error.v1"
 };
 var PAPIERS_PUBLIC_DATA_PLANE_SCOPES = [
@@ -665,10 +691,7 @@ var PAPIERS_SEARCH_MATCH_REASONS = [
 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"
-  ],
+  content_search: ["content_search_not_ready"],
   list_cursors: ["cursor_signing_not_configured"],
   read_cursors: [
     "cursor_signing_not_configured",
@@ -703,6 +726,7 @@ var PAPIERS_PUBLIC_ERROR_CODES = [
   "invalid_request",
   "not_found",
   "source_superseded",
+  "stale_reference",
   "content_limit_exceeded",
   "request_limit_exceeded",
   "rate_limited",
@@ -799,9 +823,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 +871,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 +950,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 +1058,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 +1302,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 +1477,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 +1824,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 +1838,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 +1968,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 +2413,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 +2424,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 +2951,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 +3038,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 +3049,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 +3060,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 +3070,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 +3080,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 +3093,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 +3138,38 @@ 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;
+}
 async function requestPapiersApi(config, fetchImpl, path, init) {
   if (!config.token) {
     throw new CliUsageError(
@@ -3164,10 +3199,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 +3217,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 +3280,26 @@ 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_PUBLIC_SCOPES = [
+  ...PAPIERS_PUBLIC_DATA_PLANE_SCOPES2,
+  "library:import",
+  "library:highlight"
+];
+var PAPIERS_HIGHLIGHT_MAX_SCOPE_PAGES = 20;
+var PAPIERS_HIGHLIGHT_MAX_PAGE = 1e4;
+
 // src/filters.ts
 var FILTER_OPERATORS = [
   "eq",
@@ -3709,7 +3768,16 @@ 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,
   "api-url",
   "cursor",
   "document-id",
@@ -3827,8 +3895,9 @@ 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
   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,7 +3955,7 @@ 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.
@@ -3916,7 +3985,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 +4028,40 @@ 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 tokens list [--json]
-  papiers tokens revoke TOKEN_ID [--json]
+  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.`,
+  highlight: `papiers highlight \u2014 highlight a passage in a saved PDF or webpage.
 
-Create and name tokens in Papiers (Settings -> API tokens). Revoking is permanent.`,
+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 +4077,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 +4145,12 @@ var SUGGESTIBLE_COMMANDS = [
   "auth",
   "doctor",
   "capabilities",
-  "tokens",
   "list",
   "search",
   "browse",
   "read",
+  "import",
+  "highlight",
   "version",
   "help"
 ];
@@ -4098,7 +4203,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,9 +4231,61 @@ 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 "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");
@@ -4226,35 +4384,6 @@ function parsePrettyOutput(parsed, idsOnly) {
   }
   return true;
 }
-function parseTokensCommand(rest, parsed, global) {
-  const [subcommand, tokenId, ...extra] = rest;
-  switch (subcommand) {
-    case "list":
-      assertAllowedBooleanFlags(
-        parsed,
-        NO_COMMAND_BOOLEAN_FLAGS,
-        "tokens list"
-      );
-      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 };
-    default:
-      throw new CliUsageError("Supported tokens commands: list, revoke.");
-  }
-}
 function parseAuthCommand(rest, parsed, global) {
   const [subcommand, ...extra] = rest;
   switch (subcommand) {
@@ -4357,7 +4486,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") {
@@ -4649,7 +4778,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 +4969,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 +5165,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 +5180,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 +5229,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 +5895,36 @@ async function runCli(argv, dependencies = {}) {
         );
         return 0;
       }
-      case "tokens-list":
-        writeTokenListOutput(
+      case "import":
+        writeJson(
+          stdout,
+          await importDocument(config, resolveFetch(dependencies.fetch), {
+            schemaVersion: PAPIERS_SCHEMA_VERSIONS.importRequest,
+            url: command.url,
+            submissionId: randomUUID2()
+          })
+        );
+        return 0;
+      case "highlight": {
+        const { type: _, json: __, apiBaseUrl: ___, ...highlight } = command;
+        writeJson(
           stdout,
-          await listPapiersTokens(config, resolveFetch(dependencies.fetch)),
-          command.json
+          await highlightDocument(config, resolveFetch(dependencies.fetch), {
+            schemaVersion: PAPIERS_SCHEMA_VERSIONS.highlightRequest,
+            ...highlight,
+            referenceId: randomUUID2()
+          })
         );
         return 0;
-      case "tokens-revoke":
-        writeTokenRevokeOutput(
+      }
+      case "import-status":
+        writeJson(
           stdout,
-          await revokePapiersToken(
+          await getImportStatus(
             config,
             resolveFetch(dependencies.fetch),
-            command.tokenId
-          ),
-          command.json
+            command.operationId
+          )
         );
         return 0;
       case "list":
@@ -6016,50 +6185,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 +6738,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "papiers",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Read-only CLI for your Papiers library.",
   "license": "UNLICENSED",
   "homepage": "https://papiers.ai",

package/skills/papiers-research/SKILL.md

@@ -85,6 +85,9 @@ once for the full contract. `PAPIERS_TOKEN` must be configured.
 
    Most highlights carry no annotation (quote-only); `annotationText` is
    only present on reads, so read the highlights you intend to lean on.
+   It contains sanitized Markdown source, including emphasis markers, escapes,
+   and backticks; interpret those as part of the user's note. The read's
+   `format` describes the quoted content, not the annotation's syntax.
 
 5. **Write the judgement brief.** Before generating anything, summarize what
    you found: verbatim annotations with dates and IDs, stances, open
@@ -111,8 +114,24 @@ once for the full contract. `PAPIERS_TOKEN` must be configured.
   ISO timestamps or `30d`-style shorthand.
 - **Honor the quality signal.** `quality.signal: "empty"` or `"low"` means
   the library has nothing — report that rather than citing weak matches.
-- **Cite IDs.** `hl_/cnv_/doc_/pas_/eq_/nte_` IDs are stable; include them so the
-  user can jump to sources.
+- **Cite IDs.** Include `doc_/hl_/cnv_/nte_` IDs so the user can jump to
+  sources. A passage or equation is a place in a document plus a fingerprint
+  of its text (`'doc_<id>#p12.3f9c01aa'`); if its text has changed since you got
+  it, Papiers reports `stale_reference` — search or read the document again.
+  Quote these references in the shell: some shells treat `#` specially.
+- **Import only what the user approved.** `papiers import URL` needs a token
+  with "Allow document imports". Show the user the exact URLs first. An import
+  is queued until `papiers import-status OPERATION_ID` says `ready`, which
+  means `papiers read` works on its `documentId`; don't call it added before
+  then. On `failed`, report `error.message`; retry only if `error.retryable`.
+- **Highlight only what the user asked for or approved.** `papiers highlight
+  DOC_ID --start "..." [--end "..."]` needs a token with "Allow highlights".
+  In a PDF, name what you read: `--passage` with the search result's passage
+  reference, or `--pages` with the pages you read; a webpage needs neither. Give the
+  passage's first words as `--start` and, for a longer passage or one crossing
+  a formula, its last words as `--end`; both as you read them, on plain words:
+  keep math, even a single symbol like V, out of both (formatting doesn't
+  matter). If it repeats, add words until unique.
 - **Budgets are policy, not protocol.** Default to ~10–20 queries and 3–8
   document reads per task. The user may override any policy in this skill
   (read more, weight recency differently, skip curation); the loop's shape