papiers 0.1.3 → 0.1.5

package/README.md

@@ -2,6 +2,9 @@
 
 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.
+
 ## Install
 
 ```bash
@@ -10,17 +13,60 @@ npm install -g papiers
 
 Requires Node.js 22 or newer.
 
-## Sign in
+## First run
 
-In Papiers, open Settings -> API tokens, create a token, then sign in:
+1. In Papiers, open Settings -> API tokens and create a token.
+2. Sign in and check the connection:
 
 ```bash
 papiers auth login
+papiers auth status
+papiers doctor
 ```
 
 Paste the token when prompted. The CLI saves it locally so you do not need to
 paste it again.
 
+3. Explore your library with human-readable output:
+
+```bash
+# See what you saved recently.
+papiers list --kind document --limit 5 --pretty
+
+# Search across documents, passages, highlights, notes, and conversations.
+papiers search "retrieval augmented generation" --limit 5 --pretty
+
+# List notes, then read one using the nte_... ID from the result.
+papiers list --kind note --limit 5 --pretty
+papiers read nte_... --format markdown --pretty
+```
+
+Run `papiers <command> --help` for command-specific options or
+`papiers help --all` for the complete CLI reference.
+
+## Common workflows
+
+```bash
+# Recent highlights.
+papiers list --kind highlight --since 30d --limit 10 --pretty
+
+# Read the matching passages from a search through stdin.
+papiers search "retrieval" --kind passage --limit 5 --passage-ids \
+  | papiers read @- --format plain --pretty
+
+# Read document metadata without fetching its full content.
+papiers read doc_... --format metadata --pretty
+```
+
+Data commands emit stable JSON by default. Use `--pretty` for terminal reading;
+use `--json`, `--ids`, `--ids0`, and `--doc-ids` for scripts and pipelines.
+
+To forget the locally saved token:
+
+```bash
+papiers auth logout
+```
+
 ## Use with an AI agent
 
 This is what `papiers` is really for. Point a coding or research agent (Claude
@@ -31,10 +77,28 @@ you wrote, the conversations you had — instead of generic web knowledge.
 The package ships a ready-to-use agent skill at
 [`skills/papiers-research/SKILL.md`](skills/papiers-research/SKILL.md). It
 encodes the loop — survey what you've been reading, search across passages +
-highlights + conversations in one ranking, then read and cite your own sources.
-Hand that file to your agent (or drop it in its skills directory) and ask it to
-propose an idea, design an experiment, or review a draft. It will think with
-your library, not around it.
+highlights + notes + conversations in one ranking, then read and cite your own
+sources.
+
+After a global install, locate the packaged skill under the npm root:
+
+```bash
+PAPIERS_ROOT="$(npm root -g)/papiers"
+
+# Claude Code, project-local skill
+mkdir -p .claude/skills/papiers-research
+cp "$PAPIERS_ROOT/skills/papiers-research/SKILL.md" \
+  .claude/skills/papiers-research/SKILL.md
+
+# Codex, project-local skill
+mkdir -p .codex/skills/papiers-research
+cp "$PAPIERS_ROOT/skills/papiers-research/SKILL.md" \
+  .codex/skills/papiers-research/SKILL.md
+```
+
+For another agent, add the same file through its normal skill or project
+instructions mechanism. Then ask the agent to propose an idea, design an
+experiment, or review a draft. It will think with your library, not around it.
 
 ```bash
 # the agent only needs your token in its environment:
@@ -44,18 +108,28 @@ export PAPIERS_TOKEN=pap_live_...
 Every data command emits a stable JSON envelope (`--json` makes errors JSON
 too), so an agent can learn the whole tool from `papiers --help --all` alone.
 
-## Common Commands
+## Automation
 
 ```bash
-papiers list --kind document --limit 5
-papiers search "retrieval augmented generation" --limit 10
-papiers read doc_... --format markdown
-papiers doctor   # check your setup and connection
+# Keep the token in the process environment rather than passing it as an
+# argument. Do not commit it to source control.
+export PAPIERS_TOKEN=pap_live_...
+papiers search "mixture of experts" --limit 10 --json
 ```
 
-Use `--json` for stable machine-readable output. Use `--ids`, `--ids0`, and
-`--doc-ids` to pipe results between commands.
-
-## Automation
-
-For scripts and automation, set `PAPIERS_TOKEN` and pass `--json` for stable machine-readable output.
+`PAPIERS_TOKEN` takes precedence over a token saved by `papiers auth login`.
+Run `papiers doctor` to see which token source and API endpoint are active.
+
+## Troubleshooting
+
+- **`papiers: command not found`:** run `npm prefix -g` and make sure that
+  installation's binary directory is on `PATH`.
+- **Unsupported Node.js version:** run `node --version` and install Node.js 22
+  or newer.
+- **Authentication failed:** run `papiers auth status`. If necessary, run
+  `papiers auth logout`, create a fresh token in Papiers, and sign in again.
+- **Wrong token or endpoint:** run `papiers doctor`. Unset `PAPIERS_TOKEN` or
+  `PAPIERS_API_BASE_URL` if an automation environment is overriding your saved
+  login or the production endpoint.
+- **Connection or API error:** run `papiers doctor`, then retry the failing
+  command with `--json` to get a machine-readable error and request ID.

package/dist/index.js

@@ -412,13 +412,41 @@ function isNodeError(error) {
   return Boolean(error && typeof error === "object" && "code" in error);
 }
 
+// ../../src/shared/papiers-resource-locators.ts
+var UUID_PATTERN = "[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}";
+var PAPIERS_RESOURCE_LOCATOR_PATTERN_SOURCE = `papiers://(?:note|highlight|item|conversation|artifact)/${UUID_PATTERN}`;
+var RESOURCE_LOCATOR_PATTERN = new RegExp(
+  `^papiers://(note|highlight|item|conversation|artifact)/(${UUID_PATTERN})$`,
+  "u"
+);
+var UUID_REGEX = new RegExp(`^${UUID_PATTERN}$`, "iu");
+var READ_KIND_BY_LOCATOR_KIND = {
+  note: "note",
+  highlight: "highlight",
+  item: "document",
+  conversation: "conversation",
+  artifact: "artifact"
+};
+function parsePapiersResourceLocator(value) {
+  const match = RESOURCE_LOCATOR_PATTERN.exec(value);
+  if (!match) return null;
+  const kind = match[1];
+  return {
+    value,
+    kind,
+    readKind: READ_KIND_BY_LOCATOR_KIND[kind],
+    internalId: match[2].toLowerCase()
+  };
+}
+
 // src/document-contract.ts
 var PUBLIC_KINDS = [
   "document",
   "passage",
   "highlight",
   "conversation",
-  "equation"
+  "equation",
+  "note"
 ];
 var EXPECTED_DOCUMENT_READ_FORMATS = [
   "metadata",
@@ -440,6 +468,10 @@ var EXPECTED_CONVERSATION_READ_FORMATS = [
 var EXPECTED_EQUATION_READ_FORMATS = [
   "metadata"
 ];
+var EXPECTED_NOTE_READ_FORMATS = [
+  "markdown",
+  "plain"
+];
 var DOCUMENT_READ_REQUEST_FORMATS = [
   ...EXPECTED_DOCUMENT_READ_FORMATS,
   "auto"
@@ -506,6 +538,7 @@ var PASSAGE_PUBLIC_ID_PATTERN = /^pas_[a-f0-9]{32}$/u;
 var HIGHLIGHT_PUBLIC_ID_PATTERN = /^hl_[a-f0-9]{32}$/u;
 var CONVERSATION_PUBLIC_ID_PATTERN = /^cnv_[a-f0-9]{32}$/u;
 var EQUATION_PUBLIC_ID_PATTERN = /^eq_[a-f0-9]{32}$/u;
+var NOTE_PUBLIC_ID_PATTERN = /^nte_[a-f0-9]{32}$/u;
 var SEARCH_RANKING_ID_PATTERN = /^srch_[a-f0-9]{32}$/u;
 function isSearchRankingId(value) {
   return SEARCH_RANKING_ID_PATTERN.test(value);
@@ -525,6 +558,9 @@ function isConversationPublicId(value) {
 function isEquationPublicId(value) {
   return EQUATION_PUBLIC_ID_PATTERN.test(value);
 }
+function isNotePublicId(value) {
+  return NOTE_PUBLIC_ID_PATTERN.test(value);
+}
 function publicReadKindForId(value) {
   if (isDocumentPublicId(value)) {
     return "document";
@@ -541,8 +577,22 @@ function publicReadKindForId(value) {
   if (isEquationPublicId(value)) {
     return "equation";
   }
+  if (isNotePublicId(value)) {
+    return "note";
+  }
   return null;
 }
+function readKindForIdentifier(value) {
+  const publicKind = publicReadKindForId(value);
+  if (publicKind) {
+    return publicKind;
+  }
+  const locatorKind = parsePapiersResourceLocator(value)?.readKind;
+  return locatorKind === "artifact" ? null : locatorKind ?? null;
+}
+function isDocumentReadIdentifier(value) {
+  return isDocumentPublicId(value) || parsePapiersResourceLocator(value)?.kind === "item";
+}
 function isPublicIdForKind(value, kind) {
   return publicReadKindForId(value) === kind;
 }
@@ -593,7 +643,8 @@ var PAPIERS_SEARCH_QUALITY_SIGNALS = [
 ];
 var PAPIERS_SEARCH_RESULT_KINDS = [
   "document",
-  "conversation"
+  "conversation",
+  "note"
 ];
 var PAPIERS_SEARCH_EVIDENCE_KINDS = [
   "passage",
@@ -608,7 +659,8 @@ var PAPIERS_SEARCH_MATCH_REASONS = [
   "passage",
   "highlight",
   "equation",
-  "conversation"
+  "conversation",
+  "note"
 ];
 var PAPIERS_PUBLIC_NOT_READY_REASONS_BY_FEATURE = {
   document_content_read: ["explicit_enablement_required"],
@@ -651,6 +703,8 @@ var PAPIERS_PUBLIC_ERROR_CODES = [
   "invalid_request",
   "not_found",
   "source_superseded",
+  "content_limit_exceeded",
+  "request_limit_exceeded",
   "rate_limited",
   "internal_error"
 ];
@@ -789,6 +843,7 @@ var RANKED_SEARCH_CURSOR_WARNING_MESSAGES = /* @__PURE__ */ new Set([
 var DOCUMENT_READ_TRUNCATED_WARNING_CODE = "read_truncated";
 var DOCUMENT_READ_TRUNCATED_WARNING_MESSAGE = "Document content was truncated by public read limits.";
 var PASSAGE_READ_TRUNCATED_WARNING_MESSAGE = "Passage content was truncated by public read limits.";
+var NOTE_READ_TRUNCATED_WARNING_MESSAGE = "Note content was truncated by public read limits.";
 var READ_RESPONSE_KEYS = /* @__PURE__ */ new Set([
   "schemaVersion",
   "requestId",
@@ -858,6 +913,11 @@ var SEARCH_CONVERSATION_RESULT_KEYS = /* @__PURE__ */ new Set([
   ...SEARCH_RESULT_BASE_KEYS,
   "snippet"
 ]);
+var SEARCH_NOTE_RESULT_KEYS = /* @__PURE__ */ new Set([
+  ...SEARCH_RESULT_BASE_KEYS,
+  "snippet",
+  "metadata"
+]);
 var SEARCH_EVIDENCE_KEYS = /* @__PURE__ */ new Set([
   "kind",
   "id",
@@ -910,6 +970,19 @@ var READ_SUCCESS_EQUATION_ITEM_KEYS = /* @__PURE__ */ new Set([
   "format",
   "metadata"
 ]);
+var READ_SUCCESS_NOTE_ITEM_KEYS = /* @__PURE__ */ new Set([
+  "id",
+  "kind",
+  "ok",
+  "format",
+  "content",
+  "truncated",
+  "charCount",
+  "tokenEstimate",
+  "metadata",
+  "nextCursor",
+  "warnings"
+]);
 var READ_ERROR_DOCUMENT_ITEM_KEYS = /* @__PURE__ */ new Set(["id", "kind", "ok", "error"]);
 var READ_ITEM_ERROR_KEYS = /* @__PURE__ */ new Set(["code", "message", "retryable"]);
 var HIGHLIGHT_READ_METADATA_KEYS = /* @__PURE__ */ new Set([
@@ -919,6 +992,8 @@ var HIGHLIGHT_READ_METADATA_KEYS = /* @__PURE__ */ new Set([
   "anchorType",
   "annotationText",
   "quoteContext",
+  "quotePrefix",
+  "quoteSuffix",
   "createdAt",
   "updatedAt"
 ]);
@@ -940,6 +1015,14 @@ var EQUATION_READ_METADATA_KEYS = /* @__PURE__ */ new Set([
   "nodeType",
   "updatedAt"
 ]);
+var NOTE_READ_METADATA_KEYS = /* @__PURE__ */ new Set([
+  "documentId",
+  "attachedTitle",
+  "editedAt",
+  "createdAt",
+  "updatedAt",
+  "title"
+]);
 var READ_LOCATIONS_KEYS = /* @__PURE__ */ new Set(["pages", "scope", "truncated"]);
 var READ_LOCATION_PAGE_KEYS = /* @__PURE__ */ new Set(["page", "sections"]);
 var READ_LOCATION_SCOPE_KEYS = /* @__PURE__ */ new Set(["pages"]);
@@ -971,9 +1054,16 @@ var PASSAGE_READ_NOT_FOUND_MESSAGE = "Passage is not available.";
 var HIGHLIGHT_READ_NOT_FOUND_MESSAGE = "Highlight is not available.";
 var CONVERSATION_READ_NOT_FOUND_MESSAGE = "Conversation is not available.";
 var EQUATION_READ_NOT_FOUND_MESSAGE = "Equation is not available.";
+var NOTE_READ_NOT_FOUND_MESSAGE = "Note is not available.";
 var DOCUMENT_READ_SOURCE_SUPERSEDED_CODE = "source_superseded";
+var CONVERSATION_READ_CONTENT_LIMIT_CODE = "content_limit_exceeded";
+var CONVERSATION_READ_REQUEST_LIMIT_CODE = "request_limit_exceeded";
 var DOCUMENT_READ_SOURCE_SUPERSEDED_MESSAGE = "Document content is not available for the current source.";
+var NOTE_READ_SOURCE_SUPERSEDED_MESSAGE = "Note content changed since this cursor was issued.";
 var PASSAGE_READ_CONTENT_UNAVAILABLE_MESSAGE = "Passage content is not available.";
+var CONVERSATION_READ_SOURCE_SUPERSEDED_MESSAGE = "Conversation source is no longer available. Search again for a current result.";
+var CONVERSATION_READ_CONTENT_LIMIT_MESSAGE = "Conversation content exceeds the public read limit.";
+var CONVERSATION_READ_REQUEST_LIMIT_MESSAGE = "Conversation read batch is too large. Retry this item in a smaller batch.";
 var PUBLIC_CURSOR_BASE64URL_PATTERN = /^[A-Za-z0-9_-]{1,4096}$/u;
 var PUBLIC_CURSOR_SIGNATURE_PATTERN = /^[A-Za-z0-9_-]{43}$/u;
 var PUBLIC_CURSOR_HASH_PATTERN = /^[A-Za-z0-9_-]{43}$/u;
@@ -1033,6 +1123,8 @@ var INTERNAL_RESPONSE_KEYS = /* @__PURE__ */ new Set([
   "latexTokens",
   "library_item_id",
   "libraryItemId",
+  "note_id",
+  "noteId",
   "actor_id",
   "actorId",
   "owner_user_id",
@@ -1056,7 +1148,7 @@ var INTERNAL_RESPONSE_KEYS = /* @__PURE__ */ new Set([
   "last_used_ip_hash",
   "lastUsedIpHash"
 ]);
-var UNSAFE_PUBLIC_EXCERPT_MARKER_PATTERN = /\b(?:artifact_id|artifactId|astNodeId|atom_id|atomId|branchKey|contentHash|conversation_id|conversationId|current_artifact_id|currentArtifactId|current_internal_target_json|currentInternalTargetJson|internal_locator|internalLocator|latexTokens|library_item_id|libraryItemId|actor_id|actorId|owner_user_id|ownerUserId|secret_hash|secretHash|source_id|sourceId|source_url|sourceUrl|source_locator|sourceLocator|source_locator_hash|sourceLocatorHash|source_locator_json|sourceLocatorJson|projectionHash|search_row_id|searchRowId|last_used_ip_hash|lastUsedIpHash)\b/u;
+var UNSAFE_PUBLIC_EXCERPT_MARKER_PATTERN = /\b(?:artifact_id|artifactId|astNodeId|atom_id|atomId|branchKey|contentHash|conversation_id|conversationId|current_artifact_id|currentArtifactId|current_internal_target_json|currentInternalTargetJson|internal_locator|internalLocator|latexTokens|library_item_id|libraryItemId|note_id|noteId|actor_id|actorId|owner_user_id|ownerUserId|secret_hash|secretHash|source_id|sourceId|source_url|sourceUrl|source_locator|sourceLocator|source_locator_hash|sourceLocatorHash|source_locator_json|sourceLocatorJson|projectionHash|search_row_id|searchRowId|last_used_ip_hash|lastUsedIpHash)\b/u;
 var UNSAFE_PUBLIC_EXCERPT_URL_PATTERN = /\bhttps?:\/\/\S+[?&](?:access_token|key|secret|sig|signature|token)=/iu;
 var UNSAFE_PUBLIC_EXCERPT_SIGNED_URL_PATTERN = /\bsigned[_-]?url\b/iu;
 var CLI_DOCUMENT_READ_FORMAT_SET = new Set(
@@ -1279,10 +1371,10 @@ function validatePapiersReadResponse(label, body, options = {}) {
   const expectedInclude = options.expectedInclude ? new Set(options.expectedInclude) : void 0;
   for (const [index, rawItem] of items.entries()) {
     const item = assertRecord(`${label} item ${index}`, rawItem);
-    const id = assertReadPublicId(`${label} item ${index} id`, item.id);
+    const id = assertReadIdentifier(`${label} item ${index} id`, item.id);
     if (options.expectedIds !== void 0 && id !== options.expectedIds[index]) {
       throw new PapiersCliResponseValidationError(
-        `${label} did not echo the requested public ids in order.`
+        `${label} did not echo the requested identifiers in order.`
       );
     }
     const kind = validateReadItemKind(
@@ -1388,10 +1480,16 @@ function validateSearchResults(label, results, options = {}) {
         `${label} result ${index} kind was not one of the requested kinds.`
       );
     }
-    if (kind === "document") {
-      validateSearchDocumentResult(`${label} result ${index}`, result);
-    } else {
-      validateSearchConversationResult(`${label} result ${index}`, result);
+    switch (kind) {
+      case "document":
+        validateSearchDocumentResult(`${label} result ${index}`, result);
+        break;
+      case "conversation":
+        validateSearchConversationResult(`${label} result ${index}`, result);
+        break;
+      case "note":
+        validateSearchNoteResult(`${label} result ${index}`, result);
+        break;
     }
   }
   return values.length;
@@ -1412,6 +1510,9 @@ function validateSearchResultKind(label, value, id) {
   if (value === "conversation" && isPublicIdForKind(id, "conversation")) {
     return "conversation";
   }
+  if (value === "note" && isPublicIdForKind(id, "note")) {
+    return "note";
+  }
   throw new PapiersCliResponseValidationError(
     `${label} did not match the public id kind.`
   );
@@ -1465,6 +1566,23 @@ function validateSearchConversationResult(label, result) {
   validateOptionalNullableString(`${label} title`, result.title);
   validateOptionalPublicExcerpt(`${label} snippet`, result.snippet);
 }
+function validateSearchNoteResult(label, result) {
+  rejectUnexpectedKeys(label, result, SEARCH_NOTE_RESULT_KEYS);
+  const id = assertNonEmptyString(`${label} id`, result.id);
+  if (!isPublicIdForKind(id, "note")) {
+    throw new PapiersCliResponseValidationError(
+      `${label} id was not an nte_* public id.`
+    );
+  }
+  assertPositiveInteger(`${label} rank`, result.rank);
+  validateSearchScore(`${label} score`, result.score);
+  validateSearchMatchedBy(`${label} matchedBy`, result.matchedBy, {
+    allow: /* @__PURE__ */ new Set(["note"])
+  });
+  validateOptionalNullableString(`${label} title`, result.title);
+  validateOptionalPublicExcerpt(`${label} snippet`, result.snippet);
+  validateNoteMetadata(`${label} metadata`, result.metadata, assertDocId);
+}
 function validateSearchEvidenceList(label, value) {
   const evidence = assertArray(label, value);
   for (const [index, rawEvidence] of evidence.entries()) {
@@ -1666,9 +1784,9 @@ function validateOptionalDocumentIdForKind(label, value, kind) {
     }
     return void 0;
   }
-  if (kind === "conversation") {
+  if (kind === "conversation" || kind === "note") {
     throw new PapiersCliResponseValidationError(
-      `${label} was not supported for conversation items.`
+      `${label} was not supported for ${kind} items.`
     );
   }
   return assertDocId(label, value);
@@ -1692,12 +1810,15 @@ function validateOptionalListSearchMetadata(label, value, kind) {
     return validatePassageListSearchMetadata(label, value);
   }
   if (kind === "highlight") {
-    return validateHighlightReadMetadata(label, value);
+    return validateHighlightMetadata(label, value, assertDocId);
   }
   if (kind === "conversation") {
     validateConversationReadMetadata(label, value);
     return void 0;
   }
+  if (kind === "note") {
+    return validateNoteMetadata(label, value, assertDocId);
+  }
   return validateEquationReadMetadata(label, value);
 }
 function validatePassageListSearchMetadata(label, value) {
@@ -1728,11 +1849,54 @@ function validateReadSuccessItem(label, item, kind, options) {
       return validateConversationReadSuccessItem(label, item, options);
     case "equation":
       return validateEquationReadSuccessItem(label, item, options);
+    case "note":
+      return validateNoteReadSuccessItem(label, item, options);
   }
 }
+function validateNoteReadSuccessItem(label, item, options) {
+  rejectUnexpectedKeys(label, item, READ_SUCCESS_NOTE_ITEM_KEYS);
+  const itemFormat = validateCliReadFormat(`${label} format`, item.format);
+  if (!EXPECTED_NOTE_READ_FORMATS.some((format) => format === itemFormat)) {
+    throw new PapiersCliResponseValidationError(
+      `${label} format was not supported for note reads.`
+    );
+  }
+  if (options.expectedFormat !== void 0 && !isResolvedReadFormatAllowed(itemFormat, options.expectedFormat)) {
+    throw new PapiersCliResponseValidationError(
+      `${label} did not echo the requested read format.`
+    );
+  }
+  const contentResult = validateReadContent(label, item, itemFormat, {
+    expectedMaxCharsPerItem: options.expectedMaxCharsPerItem
+  });
+  validateReadItemCursor(
+    label,
+    item.nextCursor,
+    itemFormat,
+    contentResult.truncated,
+    options.singleItemRead
+  );
+  validateNoteMetadata(
+    `${label} metadata`,
+    item.metadata,
+    assertDocumentReadIdentifier
+  );
+  const hasReadTruncatedWarning = validateOptionalReadWarnings(
+    `${label} warnings`,
+    item.warnings,
+    itemFormat,
+    "note"
+  );
+  if (hasReadTruncatedWarning && !contentResult.truncated) {
+    throw new PapiersCliResponseValidationError(
+      `${label} returned read_truncated without truncated=true.`
+    );
+  }
+  return { ...contentResult, contentRead: true };
+}
 function validateDocumentReadSuccessItem(label, item, options) {
   rejectUnexpectedKeys(label, item, READ_SUCCESS_DOCUMENT_ITEM_KEYS);
-  assertDocId(`${label} id`, item.id);
+  assertDocumentReadIdentifier(`${label} id`, item.id);
   const itemFormat = validateCliReadFormat(`${label} format`, item.format);
   if (options.expectedFormat !== void 0 && !isResolvedReadFormatAllowed(itemFormat, options.expectedFormat)) {
     throw new PapiersCliResponseValidationError(
@@ -1854,11 +2018,19 @@ function validateHighlightReadSuccessItem(label, item, options) {
   }
   if (itemFormat === "plain") {
     const contentResult = validatePlainReadContentFields(label, item);
-    validateHighlightReadMetadata(`${label} metadata`, item.metadata);
+    validateHighlightMetadata(
+      `${label} metadata`,
+      item.metadata,
+      assertDocumentReadIdentifier
+    );
     return { ...contentResult, contentRead: true };
   }
   rejectMetadataOnlyContentFields(label, item);
-  validateHighlightReadMetadata(`${label} metadata`, item.metadata);
+  validateHighlightMetadata(
+    `${label} metadata`,
+    item.metadata,
+    assertDocumentReadIdentifier
+  );
   return { returnedChars: 0, truncated: false, contentRead: false };
 }
 function validateConversationReadSuccessItem(label, item, options) {
@@ -1900,18 +2072,21 @@ function validateEquationReadSuccessItem(label, item, options) {
   return { returnedChars: 0, truncated: false, contentRead: false };
 }
 function validateReadItemKind(label, value, id) {
-  const expectedKind = publicReadKindForId(id);
-  if (expectedKind === null || value !== expectedKind || value !== "document" && value !== "passage" && value !== "highlight" && value !== "conversation" && value !== "equation") {
+  const expectedKind = readKindForIdentifier(id);
+  if (expectedKind === null || value !== expectedKind || value !== "document" && value !== "passage" && value !== "highlight" && value !== "conversation" && value !== "equation" && value !== "note") {
     throw new PapiersCliResponseValidationError(
-      `${label} did not match the public id kind.`
+      `${label} did not match the read identifier kind.`
     );
   }
   return value;
 }
-function validateHighlightReadMetadata(label, value) {
+function validateHighlightMetadata(label, value, validateDocumentId) {
   const metadata = assertRecord(label, value);
   rejectUnexpectedKeys(label, metadata, HIGHLIGHT_READ_METADATA_KEYS);
-  const documentId = assertDocId(`${label}.documentId`, metadata.documentId);
+  const documentId = validateDocumentId(
+    `${label}.documentId`,
+    metadata.documentId
+  );
   validateOptionalNullableString(
     `${label}.documentTitle`,
     metadata.documentTitle
@@ -1930,6 +2105,8 @@ function validateHighlightReadMetadata(label, value) {
     `${label}.quoteContext`,
     metadata.quoteContext
   );
+  validateOptionalNullableString(`${label}.quotePrefix`, metadata.quotePrefix);
+  validateOptionalNullableString(`${label}.quoteSuffix`, metadata.quoteSuffix);
   validateOptionalTimestamp(`${label}.createdAt`, metadata.createdAt);
   validateOptionalTimestamp(`${label}.updatedAt`, metadata.updatedAt);
   return documentId;
@@ -1961,6 +2138,21 @@ function validateEquationReadMetadata(label, value) {
   validateOptionalTimestamp(`${label}.updatedAt`, metadata.updatedAt);
   return documentId;
 }
+function validateNoteMetadata(label, value, validateDocumentId) {
+  const metadata = assertRecord(label, value);
+  rejectUnexpectedKeys(label, metadata, NOTE_READ_METADATA_KEYS);
+  const documentId = metadata.documentId === null ? void 0 : validateDocumentId(`${label}.documentId`, metadata.documentId);
+  if (metadata.attachedTitle !== null && typeof metadata.attachedTitle !== "string") {
+    throw new PapiersCliResponseValidationError(
+      `${label}.attachedTitle was not a string or null.`
+    );
+  }
+  assertTimestampString(`${label}.editedAt`, metadata.editedAt);
+  assertTimestampString(`${label}.createdAt`, metadata.createdAt);
+  assertTimestampString(`${label}.updatedAt`, metadata.updatedAt);
+  assertNonEmptyString(`${label}.title`, metadata.title);
+  return documentId;
+}
 function rejectUnexpectedContent(label, item) {
   if (item.content !== void 0 && item.content !== null) {
     throw new PapiersCliResponseValidationError(
@@ -2188,19 +2380,20 @@ function validateReadUsage(label, rawUsage, options) {
 function validateReadItemError(label, value, kind, expectedFormat) {
   const error = assertRecord(label, value);
   rejectUnexpectedKeys(label, error, READ_ITEM_ERROR_KEYS);
-  if (error.code !== DOCUMENT_READ_NOT_FOUND_CODE) {
-    if (kind !== "document" && kind !== "passage" || error.code !== DOCUMENT_READ_SOURCE_SUPERSEDED_CODE) {
-      throw new PapiersCliResponseValidationError(
-        `${label}.code was not a supported read error code.`
-      );
-    }
+  const sourceSupersededAllowed = error.code === DOCUMENT_READ_SOURCE_SUPERSEDED_CODE && (kind === "document" || kind === "passage" || kind === "note" || kind === "conversation");
+  const contentLimitAllowed = error.code === CONVERSATION_READ_CONTENT_LIMIT_CODE && kind === "conversation";
+  const requestLimitAllowed = error.code === CONVERSATION_READ_REQUEST_LIMIT_CODE && kind === "conversation";
+  if (error.code !== DOCUMENT_READ_NOT_FOUND_CODE && !sourceSupersededAllowed && !contentLimitAllowed && !requestLimitAllowed) {
+    throw new PapiersCliResponseValidationError(
+      `${label}.code was not a supported read error code.`
+    );
   }
-  if (expectedFormat === "metadata" && error.code === DOCUMENT_READ_SOURCE_SUPERSEDED_CODE) {
+  if (expectedFormat === "metadata" && (error.code === DOCUMENT_READ_SOURCE_SUPERSEDED_CODE || error.code === CONVERSATION_READ_CONTENT_LIMIT_CODE || error.code === CONVERSATION_READ_REQUEST_LIMIT_CODE)) {
     throw new PapiersCliResponseValidationError(
       `${label}.code was not supported for metadata reads.`
     );
   }
-  const expectedMessage = error.code === DOCUMENT_READ_NOT_FOUND_CODE ? readNotFoundMessageForKind(kind) : kind === "passage" ? PASSAGE_READ_CONTENT_UNAVAILABLE_MESSAGE : DOCUMENT_READ_SOURCE_SUPERSEDED_MESSAGE;
+  const expectedMessage = error.code === DOCUMENT_READ_NOT_FOUND_CODE ? readNotFoundMessageForKind(kind) : error.code === CONVERSATION_READ_CONTENT_LIMIT_CODE ? CONVERSATION_READ_CONTENT_LIMIT_MESSAGE : error.code === CONVERSATION_READ_REQUEST_LIMIT_CODE ? CONVERSATION_READ_REQUEST_LIMIT_MESSAGE : kind === "conversation" ? CONVERSATION_READ_SOURCE_SUPERSEDED_MESSAGE : kind === "passage" ? PASSAGE_READ_CONTENT_UNAVAILABLE_MESSAGE : kind === "note" ? NOTE_READ_SOURCE_SUPERSEDED_MESSAGE : DOCUMENT_READ_SOURCE_SUPERSEDED_MESSAGE;
   if (error.message !== expectedMessage) {
     throw new PapiersCliResponseValidationError(
       `${label}.message was not a supported read error message.`
@@ -2225,6 +2418,8 @@ function readNotFoundMessageForKind(kind) {
       return CONVERSATION_READ_NOT_FOUND_MESSAGE;
     case "equation":
       return EQUATION_READ_NOT_FOUND_MESSAGE;
+    case "note":
+      return NOTE_READ_NOT_FOUND_MESSAGE;
   }
 }
 function validateOptionalSearchQuality(label, value) {
@@ -2289,7 +2484,7 @@ function validateOptionalReadWarnings(label, value, format, kind) {
       );
     }
     hasReadTruncatedWarning = true;
-    const expectedMessage = kind === "document" ? DOCUMENT_READ_TRUNCATED_WARNING_MESSAGE : PASSAGE_READ_TRUNCATED_WARNING_MESSAGE;
+    const expectedMessage = kind === "document" ? DOCUMENT_READ_TRUNCATED_WARNING_MESSAGE : kind === "passage" ? PASSAGE_READ_TRUNCATED_WARNING_MESSAGE : NOTE_READ_TRUNCATED_WARNING_MESSAGE;
     if (warning.message !== expectedMessage) {
       throw new PapiersCliResponseValidationError(
         `${label} ${index}.message was not a supported warning message.`
@@ -2709,10 +2904,18 @@ function assertDocId(label, value) {
   }
   return value;
 }
-function assertReadPublicId(label, value) {
-  if (typeof value !== "string" || publicReadKindForId(value) === null) {
+function assertDocumentReadIdentifier(label, value) {
+  if (typeof value !== "string" || !isDocumentReadIdentifier(value)) {
     throw new PapiersCliResponseValidationError(
-      `${label} was not a supported public read id.`
+      `${label} was not a doc_* public id or papiers://item locator.`
+    );
+  }
+  return value;
+}
+function assertReadIdentifier(label, value) {
+  if (typeof value !== "string" || readKindForIdentifier(value) === null) {
+    throw new PapiersCliResponseValidationError(
+      `${label} was not a supported read identifier.`
     );
   }
   return value;
@@ -2856,7 +3059,7 @@ async function readDocuments(config, fetchImpl, request) {
     "/api/v1/papiers/read",
     { method: "POST", body: request, retryable: true }
   );
-  const readKind = publicReadKindForId(request.ids[0] ?? "");
+  const readKind = readKindForIdentifier(request.ids[0] ?? "");
   assertPapiersReadResponse("read", body, request.ids, {
     // Every kind resolves an omitted format server-side (auto semantics),
     // so there is nothing to echo-check unless the caller pinned one;
@@ -2903,7 +3106,7 @@ function expectedKindForListSearchRequest(request) {
 function expectedKindsForSearchRequest(request) {
   const kinds = request.kinds;
   if (kinds === void 0) {
-    return { expectedKinds: /* @__PURE__ */ new Set(["document", "conversation"]) };
+    return { expectedKinds: /* @__PURE__ */ new Set(["document", "conversation", "note"]) };
   }
   if (!Array.isArray(kinds) || kinds.length === 0) {
     throw new CliUsageError(
@@ -2923,11 +3126,14 @@ function expectedKindsForSearchRequest(request) {
       );
     }
   }
-  const normalizedKinds = new Set(rawKinds);
-  if (normalizedKinds.size === 1 && normalizedKinds.has("conversation")) {
-    return { expectedKind: "conversation" };
+  const expectedKinds = /* @__PURE__ */ new Set();
+  for (const kind of rawKinds) {
+    expectedKinds.add(
+      kind === "conversation" || kind === "note" ? kind : "document"
+    );
   }
-  return normalizedKinds.has("conversation") ? { expectedKinds: /* @__PURE__ */ new Set(["document", "conversation"]) } : { expectedKind: "document" };
+  const [onlyKind] = expectedKinds;
+  return expectedKinds.size === 1 ? { expectedKind: onlyKind } : { expectedKinds };
 }
 async function requestPapiersApi(config, fetchImpl, path, init) {
   if (!config.token) {
@@ -3598,16 +3804,18 @@ var FORMER_KIND_ALIASES = /* @__PURE__ */ new Map([
   ["chat", "conversation"],
   ["chats", "conversation"],
   ["conversations", "conversation"],
-  ["equations", "equation"]
+  ["equations", "equation"],
+  ["notes", "note"]
 ]);
 var MULTI_SEARCH_KINDS = [
   "passage",
   "highlight",
   "conversation",
-  "equation"
+  "equation",
+  "note"
 ];
 var GLOBAL_HELP = `Papiers CLI: search and read your library from the terminal.
-Your saved papers, highlights, and conversations (your chats) \u2014 for you or an AI agent.
+Your saved papers, highlights, notes, and conversations (your chats) \u2014 for you or an AI agent.
 
 GETTING STARTED
   papiers auth login                     Sign in with a token from Papiers (Settings -> API tokens)
@@ -3616,8 +3824,8 @@ GETTING STARTED
 
 COMMANDS
   search        Search across your library
-  list          List your documents, highlights, and conversations
-  read          Print a document, highlight, or conversation
+  list          List your documents, highlights, notes, and conversations
+  read          Print a document, highlight, note, or conversation
   browse        Page through an earlier search's results
   auth          Sign in, check status, or sign out
   tokens        List or revoke your API tokens
@@ -3654,8 +3862,8 @@ USAGE
 
 OPTIONS
   --kind KIND          what to search. Defaults to all \u2014 your passages, highlights,
-                       equations, conversations, and matching titles. Or focus on one:
-                       passage \xB7 highlight \xB7 conversation \xB7 equation.
+                       equations, notes, conversations, and matching titles. Or focus on one:
+                       passage \xB7 highlight \xB7 conversation \xB7 equation \xB7 note.
   --filter FIELD.OP=VALUE   narrow parent documents \u2014 repeatable, up to 25.
                        e.g. --filter publishedYear.gte=2020 --filter author.contains=hinton. Fields/ops: help --all.
   --document-id ID     scope to documents: doc_\u2026 (comma-separated or repeated), or @-/@file.
@@ -3670,7 +3878,7 @@ EXAMPLES
   papiers search retrieval --kind passage --limit 5 --passage-ids | papiers read @- --format plain --json
 
 When capabilities.searchResultsBrowse.enabled is true, a search may return ranking.searchId \u2014 pass it to \`papiers browse\` for more pages.`,
-  list: `papiers list \u2014 list your documents, highlights, and conversations.
+  list: `papiers list \u2014 list your documents, highlights, notes, and conversations.
 
 USAGE
   papiers list [--kind KIND] [--limit N] [--cursor CURSOR] [--pretty|--json|--ids|--ids0|--doc-ids]
@@ -3678,7 +3886,7 @@ USAGE
   papiers list --kind highlight|conversation [--since WHEN]
 
 OPTIONS
-  --kind KIND          document (default) \xB7 passage \xB7 highlight \xB7 conversation \xB7 equation.
+  --kind KIND          document (default) \xB7 passage \xB7 highlight \xB7 conversation \xB7 equation \xB7 note.
   --filter FIELD.OP=VALUE   narrow document results \u2014 repeatable, up to 25. document kind only.
                        e.g. --filter lastEngagedAt.gte=30d --filter annotated=true. Fields/ops: help --all.
   --order-by KEY       addedAt:desc (default) or lastEngagedAt:desc. document kind only.
@@ -3695,29 +3903,32 @@ EXAMPLES
   papiers list --kind highlight --since 30d --pretty
   papiers list --kind document --filter lastEngagedAt.gte=30d --json
   papiers list --kind document --filter annotated=true --json`,
-  read: `papiers read \u2014 print documents, highlights, conversations, passages, or equations.
+  read: `papiers read \u2014 print documents, highlights, notes, conversations, passages, or equations.
 
 USAGE
   papiers read ID [ID ...] [--format FORMAT] [--max-chars-per-item N] [--fail-fast] [--json|--pretty]
   papiers read @- | @file [--input0] [--format FORMAT] [--max-chars-per-item N] [--json|--pretty]
-  Each ID is doc_\u2026 / pas_\u2026 / hl_\u2026 / cnv_\u2026 / eq_\u2026 \u2014 the kind is read from the prefix; don't mix kinds.
+  Read public IDs or papiers://note|highlight|item|conversation/<uuid> locators; don't mix resource kinds.
 
 OPTIONS
   --format FORMAT      how to render each item. Default auto (equation defaults to metadata).
                        document: auto|metadata|markdown|plain.   passage: markdown|plain.
-                       highlight, conversation: metadata|plain.   equation: metadata.
+                       highlight, conversation: metadata|plain.   note: markdown|plain.
+                       equation: metadata.
   --include SECTION    extra sections, comma-separated: metadata, source, locations.
-                       document only (highlight/conversation/equation: metadata only; passage: none).
+                       document only (highlight/conversation/equation/note: metadata only; passage: none).
   --pages RANGE        restrict a document read to pages, e.g. 1,3-5. document only.
   --max-chars-per-item N   truncate each item's content to N chars, 1\u2013200000.
-  --cursor CURSOR      continue one long document \u2014 use items[].nextCursor from the previous
-                       response. One literal doc_\u2026 only, with --format auto, markdown, or plain.
+  --cursor CURSOR      continue one long document or note \u2014 use items[].nextCursor from the
+                       previous response. One literal document or note identifier only, with
+                       --format auto, markdown, or plain.
   --fail-fast          exit non-zero if any item fails (default: succeed if at least one does).
   --json               machine-readable JSON (the default)
   --pretty             human-readable text
 
 EXAMPLES
   papiers read doc_<id> --format markdown --max-chars-per-item 2000 --json
+  papiers read nte_<id> --format markdown --json
   papiers read hl_<id> --json
   papiers search retrieval --doc-ids | papiers read @- --format metadata --json`,
   browse: `papiers browse \u2014 page deeper into an earlier search's results.
@@ -3771,21 +3982,27 @@ var REFERENCE = `REFERENCE \u2014 IDs, piping, pagination, and limits.
 
 ID PREFIXES
   doc_   document        pas_   passage         hl_    highlight
-  cnv_   conversation    eq_    equation        srch_  a saved search ranking (for browse)
+  cnv_   conversation    eq_    equation        nte_   note
+  srch_  a saved search ranking (for browse)
   On read, the kind \u2014 and which --format/--include apply \u2014 is read from the prefix.
 
+RESOURCE LOCATORS
+  papiers://note/<uuid>          papiers://highlight/<uuid>
+  papiers://item/<uuid>          papiers://conversation/<uuid>
+  Locators are accepted by read and resolved with the same ownership checks as public IDs.
+
 PIPING IDS BETWEEN COMMANDS
   --ids        result IDs, one per line, with their native prefix
   --ids0       the same IDs, NUL-separated (for \`xargs -0\`)
   --doc-ids    parent document IDs only (doc_\u2026), deduped; conversation hits are skipped
-  @-           read IDs from stdin          @file   read IDs from a file
-  --input0     read piped IDs NUL-separated instead of whitespace/newlines
-  @- and @file accept plain IDs or a Papiers JSON envelope, and may be mixed with literal IDs.
+  @-           read identifiers from stdin          @file   read identifiers from a file
+  --input0     read piped identifiers NUL-separated instead of whitespace/newlines
+  @- and @file accept IDs, resource locators, or a Papiers JSON envelope, and may be mixed with literals.
 
 PAGINATION \u2014 three separate mechanisms
   list     response has page.nextCursor          \u2192 papiers list \u2026 --cursor CURSOR
   search   response has ranking.searchId           \u2192 papiers browse srch_\u2026 --offset N
-  read     a truncated item has items[].nextCursor \u2192 papiers read doc_\u2026 --cursor CURSOR
+  read     a truncated item has items[].nextCursor \u2192 papiers read NOTE_OR_DOCUMENT --cursor CURSOR
 
 LIMITS
   --limit 1\u201350  \xB7  --max-chars-per-item 1\u2013200000  \xB7  up to 25 filters  \xB7  up to 100 IDs per request
@@ -4085,7 +4302,7 @@ function buildReadRequest(parsed) {
   const ids = orderedReadIdValues(parsed);
   if (ids.length === 0) {
     throw new CliUsageError(
-      "papiers read requires at least one doc_*, pas_*, hl_*, cnv_*, or eq_* ID."
+      "papiers read requires at least one public ID or papiers:// resource locator."
     );
   }
   if (ids.filter((id) => id === "@-").length > 1) {
@@ -4099,7 +4316,7 @@ function buildReadRequest(parsed) {
   const literalKinds = readKindsForLiteralIds(ids);
   if (literalKinds.length > 1) {
     throw new CliUsageError(
-      "papiers read IDs must all use the same public resource kind."
+      "papiers read identifiers must all use the same resource kind."
     );
   }
   const inferredKind = literalKinds[0] ?? requestedKind ?? "document";
@@ -4115,9 +4332,9 @@ function buildReadRequest(parsed) {
   }
   const format = parseReadFormat(parsed, inferredKind);
   const cursor = singleFlagValue(parsed, "cursor");
-  if (cursor !== void 0 && (inferredKind !== "document" || ids.length !== 1 || ids.some((id) => isDocumentIdSource(id)) || !isDocumentPublicId(ids[0]))) {
+  if (cursor !== void 0 && (inferredKind !== "document" && inferredKind !== "note" || ids.length !== 1 || ids.some((id) => isDocumentIdSource(id)) || readKindForIdentifier(ids[0]) !== inferredKind)) {
     throw new CliUsageError(
-      "papiers read --cursor requires exactly one literal doc_* ID."
+      "papiers read --cursor requires exactly one literal document or note identifier."
     );
   }
   if (cursor !== void 0 && format !== "auto" && !DOCUMENT_CONTENT_READ_FORMATS.some((supported) => supported === format)) {
@@ -4237,7 +4454,7 @@ function parseSearchKindScopes(parsed) {
     const kind = normalizeCliPublicKind(rawKind);
     if (!kind) {
       throw new CliUsageError(
-        `papiers search supports --kind passage, highlight, conversation, or equation; received "${rawKind}".${didYouMeanKind(rawKind)}`
+        `papiers search supports --kind passage, highlight, conversation, equation, or note; received "${rawKind}".${didYouMeanKind(rawKind)}`
       );
     }
     if (kind === "document") {
@@ -4247,7 +4464,7 @@ function parseSearchKindScopes(parsed) {
     }
     if (!MULTI_SEARCH_KINDS.includes(kind)) {
       throw new CliUsageError(
-        `papiers search supports --kind passage, highlight, conversation, or equation; received "${rawKind}".`
+        `papiers search supports --kind passage, highlight, conversation, equation, or note; received "${rawKind}".`
       );
     }
     kinds.push(kind);
@@ -4327,7 +4544,7 @@ function parseReadKind(parsed) {
     return normalized;
   }
   throw new CliUsageError(
-    `Public CLI read currently supports --kind document, passage, highlight, conversation, or equation only; received "${kind}".${didYouMeanKind(kind)}`
+    `Public CLI read currently supports --kind document, passage, highlight, conversation, equation, or note only; received "${kind}".${didYouMeanKind(kind)}`
   );
 }
 function readKindsForLiteralIds(ids) {
@@ -4336,10 +4553,10 @@ function readKindsForLiteralIds(ids) {
     if (isDocumentIdSource(id)) {
       continue;
     }
-    const kind = publicReadKindForId(id);
+    const kind = readKindForIdentifier(id);
     if (!kind) {
       throw new CliUsageError(
-        "papiers read currently accepts only doc_*, pas_*, hl_*, cnv_*, or eq_* IDs."
+        "papiers read accepts public IDs or papiers://note, highlight, item, and conversation locators."
       );
     }
     kinds.add(kind);
@@ -4447,6 +4664,21 @@ function validateReadOptionsForKind(parsed, kind, format) {
     });
     return;
   }
+  if (kind === "note") {
+    if (format !== "auto" && !EXPECTED_NOTE_READ_FORMATS.some((supported) => supported === format)) {
+      throw new CliUsageError(
+        "Public note read supports --format markdown, plain, or auto."
+      );
+    }
+    const includes = parseReadInclude(parsed);
+    if (includes?.some((include) => include !== "metadata")) {
+      throw new CliUsageError(
+        "Public note read supports only --include metadata."
+      );
+    }
+    rejectReadFlagsForKind(parsed, kind, ["pages"]);
+    return;
+  }
   validateMetadataReadOptionsForKind(parsed, kind, format, {
     supportedFormats: EXPECTED_EQUATION_READ_FORMATS
   });
@@ -4614,7 +4846,7 @@ function parseListSearchKind(parsed, command) {
     );
   }
   throw new CliUsageError(
-    `papiers ${command} supports --kind document, passage, highlight, conversation, or equation; received "${kind}".${didYouMeanKind(kind)}`
+    `papiers ${command} supports --kind document, passage, highlight, conversation, equation, or note; received "${kind}".${didYouMeanKind(kind)}`
   );
 }
 function normalizeCliPublicKind(value) {
@@ -4921,6 +5153,13 @@ function assertSupportedDocumentCapabilities(value) {
           EXPECTED_EQUATION_READ_FORMATS
         );
         continue;
+      case "note":
+        assertOptionalReadFormats(
+          `capabilities readFormatsByKind.${kind}`,
+          actualFormats,
+          EXPECTED_NOTE_READ_FORMATS
+        );
+        continue;
       default:
         assertSameStringSet(
           `capabilities readFormatsByKind.${kind}`,
@@ -5661,16 +5900,13 @@ async function runAuthLogin(params) {
   }
   assertSafeBearerApiBaseUrl(params.config.apiBaseUrl);
   const token = await loginWithPatStdin(params);
-  const validationConfig = cliConfigWithToken(
-    params.config,
-    token,
-    "stdin"
+  const validationConfig = cliConfigWithToken(params.config, token, "stdin");
+  const capabilities = await getCapabilities(
+    validationConfig,
+    params.fetchImpl
   );
-  let capabilities;
-  capabilities = await getCapabilities(validationConfig, params.fetchImpl);
   assertCliSupportedCapabilities(capabilities);
-  let update;
-  update = writeLocalAuthToken({
+  const update = writeLocalAuthToken({
     root: params.envRoot,
     token,
     apiBaseUrl: params.config.apiBaseUrl
@@ -6085,7 +6321,8 @@ function writeParentDocumentIds(stdout, items) {
   const seen = /* @__PURE__ */ new Set();
   const ids = [];
   for (const item of items) {
-    const docId = item.kind === "document" ? item.id : item.documentId;
+    const metadataDocumentId = item.kind === "note" && typeof item.metadata === "object" && item.metadata !== null && !Array.isArray(item.metadata) ? item.metadata.documentId : void 0;
+    const docId = item.kind === "document" ? item.id : item.documentId ?? metadataDocumentId;
     if (typeof docId !== "string" || !docId) {
       continue;
     }
@@ -6348,23 +6585,23 @@ function validateReadIds(ids, context, sourceLabel) {
   }
   const kinds = /* @__PURE__ */ new Set();
   for (const [index, id] of ids.entries()) {
-    const kind = publicReadKindForId(id);
+    const kind = readKindForIdentifier(id);
     if (!kind) {
       throw new CliUsageError(
-        `${context} ${sourceLabel} item ${index + 1} was not a doc_*, pas_*, hl_*, cnv_*, or eq_* ID.`
+        `${context} ${sourceLabel} item ${index + 1} was not a public ID or papiers:// resource locator.`
       );
     }
     kinds.add(kind);
   }
   if (kinds.size > 1) {
     throw new CliUsageError(
-      `${context} ${sourceLabel} IDs must all use the same public resource kind.`
+      `${context} ${sourceLabel} identifiers must all use the same resource kind.`
     );
   }
   return ids;
 }
 function validateExpandedReadRequest(request, ids, requestedReadKind) {
-  const kind = publicReadKindForId(ids[0] ?? "");
+  const kind = readKindForIdentifier(ids[0] ?? "");
   if (requestedReadKind && kind && requestedReadKind !== kind) {
     throw new CliUsageError(
       `papiers read --kind ${requestedReadKind} does not match ${kind} IDs.`
@@ -6395,6 +6632,25 @@ function validateExpandedReadRequest(request, ids, requestedReadKind) {
   }
   if (kind === "equation") {
     validateMetadataOnlyReadRequest(request, kind);
+    return;
+  }
+  if (kind === "note") {
+    validateNoteReadRequest(request);
+  }
+}
+function validateNoteReadRequest(request) {
+  if (request.format !== void 0 && request.format !== "auto" && request.format !== "markdown" && request.format !== "plain") {
+    throw new CliUsageError(
+      "Public note read supports --format markdown, plain, or auto."
+    );
+  }
+  if (request.include?.some((include) => include !== "metadata")) {
+    throw new CliUsageError(
+      "Public note read supports only --include metadata."
+    );
+  }
+  if (request.scope?.pages || request.scope?.sectionId) {
+    throw new CliUsageError("Public note read does not support --pages.");
   }
 }
 function validateContentCapableReadRequest(request, kind) {
@@ -6501,10 +6757,10 @@ function parseJsonEnvelopeIds(input, context, sourceLabel) {
       );
     }
     const kind = item.kind;
-    const idKind = publicReadKindForId(id);
+    const idKind = envelope.schemaVersion === PAPIERS_SCHEMA_VERSIONS.read ? readKindForIdentifier(id) : publicReadKindForId(id);
     if (kind !== idKind) {
       throw new CliUsageError(
-        `${context} JSON item ${index} kind did not match its public id.`
+        `${context} JSON item ${index} kind did not match its identifier.`
       );
     }
     return id;

package/package.json

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

package/skills/papiers-research/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: papiers-research
-version: 1.2.0
+version: 1.2.1
 description: |
   Ground proposals, experiment designs, reviews, and writing in the user's
-  Papiers library — their highlights, annotations, conversations, and
+  Papiers library — their highlights, notes, annotations, conversations, and
   curated-but-unread saves — before generating. Use whenever output should
   be shaped by what the user has read and thought, not generic knowledge:
   proposing research ideas, designing experiments, advising on decisions,
@@ -17,7 +17,7 @@ allowed-tools:
 The `papiers` CLI is the agent-readable memory of what the user has read and
 thought. It holds two kinds of signal, and you must treat them differently:
 
-- **Judgement** (read and marked): highlights, annotations, and past
+- **Judgement** (read and marked): highlights, notes, annotations, and past
   conversations. These are the user's own words — stances, open questions,
   connections. The strongest signal you have.
 - **Curation** (saved, possibly unread): library membership itself. The user
@@ -36,13 +36,14 @@ once for the full contract. `PAPIERS_TOKEN` must be configured.
 
    ```bash
    papiers list --kind highlight --since 30d --limit 20 --json
+   papiers list --kind note --limit 20 --json
    papiers list --kind document --limit 20 --json   # scan recent titles
    ```
 
 2. **Facet sweep.** Decompose the task into 3–6 facets (for "improve MoE
    router load balancing": expert routing, load balancing loss, expert
    collapse, capacity factor…). One default search covers matching titles,
-   passages, highlights, equations, and conversations in a single fused
+   passages, highlights, equations, notes, and conversations in a single fused
    ranking:
 
    ```bash
@@ -56,9 +57,10 @@ once for the full contract. `PAPIERS_TOKEN` must be configured.
    for an author surname or `author.contains=karpathy` for a handle.
 
    Document results carry nested `evidence[]` for passage, highlight, and
-   equation hits. Use `--passage-ids`, `--highlight-ids`, or `--evidence-ids`
-   to project matching evidence flat for piping. `--doc-ids` pivots any
-   result page to deduped parent documents, skipping conversation hits.
+   equation hits; notes and conversations are standalone results. Use
+   `--passage-ids`, `--highlight-ids`, or `--evidence-ids` to project matching
+   evidence flat for piping. `--doc-ids` pivots any result page to deduped
+   parent documents, including attached notes and skipping conversations.
 
 3. **Delegated reading.** Document hits you cannot tie to any judgement are
    curated-but-unread candidates (`--filter engaged=false` lists the queue).
@@ -68,6 +70,7 @@ once for the full contract. `PAPIERS_TOKEN` must be configured.
 
    ```bash
    papiers read doc_<id> --max-chars-per-item 4000 --json
+   papiers read nte_<id> --max-chars-per-item 4000 --json
    papiers search "<topic>" --doc-ids | papiers read @- --format metadata --json
    papiers search "<subtopic>" --kind passage --document-id doc_<id> --json  # search within one document
    ```
@@ -108,7 +111,7 @@ 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_` IDs are stable; include them so the
+- **Cite IDs.** `hl_/cnv_/doc_/pas_/eq_/nte_` IDs are stable; include them so the
   user can jump to sources.
 - **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