Disciplines · Proposals

YSD-20036 — Reference-manager import routes

PureRef, Milanote, Are.na, Pinterest and Zotero were named as import sources in YSD-5010 and an importer was built for all five.

6sections2 minread
Markdown source
On this page
  • Status: approved (2026-08-14)
  • Priority: EXT — non-blocking (no route is approved, so every reference-manager import is refused)
  • Decision owner: @GreyChimp
  • Drafted: 2026-08-11 by Claude Code (Opus 5)
  • Approval: approved as recommended by @GreyChimp on 2026-08-14; outcome recorded in decision-log.json; review by 2027-08-14

Question#

PureRef, Milanote, Are.na, Pinterest and Zotero were named as import sources in YSD-5010 and an importer was built for all five. Which routes into those services may this product actually use?

The unit is not the service, it is the route. PureRef and Pinterest are unavailable for opposite reasons — one has no service to call, the other has one whose terms forbid keeping what it returns — and a decision recorded per service cannot say either thing.

Recommendation#

Approve route by route against the readings recorded in reference-import-terms.ts, each quoting the provider's own page. On those readings the expected outcomes are: Zotero's Web API approved; Are.na's API approved only once the one-to-one permission its terms require has been obtained and recorded; PureRef, Milanote and Pinterest declined.

Pinterest deserves its own sentence, because the checklist item mis-states it. The item says API access is restricted, which reads as a queue. The developer guidelines say a developer may not store information accessed through the API and must call it each time — and an imported reference is a stored record, so an approved Pinterest developer application would not make this importer compliant. This is not an approval we are waiting for; it is one that would not help.

Options considered#

  • Approve per service — rejected: it cannot express that Are.na's API is one application away while scraping Are.na is refused outright.
  • Ship the importer and record the terms later — rejected: that is the order this item exists to forbid, and it is the order that actually happened.
  • Approve per (service, route), with declines recorded as decisions — recommended.

Consequences#

  • Reference-manager import stays off until a person signs a route, and the refusal names which of several different things is wrong.
  • Three of the five are expected to be declined permanently, so the importer's reachable surface is smaller than YSD-5010 assumed.
  • Browser clips and desktop screenshots are unaffected: the user's own browser and screen have no third party whose terms could be read.

Machine-enforced outcome#

An import declares the route it travelled, is checked against the recorded reading and approval before anything is written, and the route is recorded on every reference so a later audit can tell an API call from a scrape.

Control in force#

One route is open and every other import is still refused. assertApprovedImportPath runs before the first read or write, and a refusal carries the reading, every blocker, and the licensor's quoted clause. Zotero's Web API is signed and available; PureRef, Milanote and Pinterest carry recorded declines, which refuse for a reason a reader can face rather than by silence; Are.na's API stays shut because its approval was conditioned on the one-to-one grant its terms require and this project does not hold one — signing it anyway would be the proposed default YSD-22055 forbids.