Skip to content

Audit every source adapter against the collection-import principle #3

Description

@oojBuffalo

Problem

docs/adapters.md catalogs what each adapter captures — identity rules, fidelity boundary — but says nothing about how a user's existing saved collection gets in. That omission is why the gap in #2 went unnoticed: every adapter looks complete when judged on capture alone.

Audit performed 2026-07-29 against src/scrolls/sources/ (40 catalogued adapters) and the live scrolls import --help:

Has a bulk on-ramp (5):

Path Covers Shape
import bookmarks any URL bookmarked in a browser file export
import pocket Pocket saves file export
import google-takeout YouTube watch history only file export
import fieldtheory X bookmarks another app's local store (see #5)
follow + sync anything with an RSS/Atom feed live delta

Has a real user collection and no path to it (one URL at a time only): wikipedia (reading lists, watchlist), youtube (liked videos, playlists, Watch Later, subscriptions — Takeout covers only history), github (stars, watched repos), hackernews (favorites, upvoted), stackexchange (saves), lobsters (saved), huggingface (likes, collections), mastodon / misskey (bookmarks, favourites), lemmy / piefed (saved), discourse (bookmarks), devto (reading list), openlibrary (reading log), bluesky (likes, lists).

Genuinely N/A — no per-user collection exists to import: the package registries (pypi, npm, crates, rubygems, go, hex, pub, nuget, hackage, maven, packagist), DOI resolution (crossref, datacite, content-negotiation), rfc, zenodo, and the raw shapes (pdf, web, text). These pass the audit by not having a collection, and the catalog should say so explicitly rather than leaving it blank.

Scope

Make "how does a user's collection get in?" a standing, visible property of every adapter — so a new adapter cannot be added without answering it.

Acceptance criteria

  • docs/adapters.md gains a Collections field per adapter with one of three honest values: the collection(s) reachable and how, none — no user collection exists for the N/A set, or gap — collection exists upstream, no on-ramp for the unfixed ones.
  • A summary table at the top of docs/adapters.md scoring all adapters at a glance, so the gap count is visible without reading the whole catalog.
  • The adapter contract in docs/architecture.md requires the field for any new adapter.
  • Vision §2.7 (new adapters need a genuinely new custody shape) is cross-referenced — this audit is the argument that depth on existing adapters beats breadth, with a concrete count behind it.

Verification

grep -c "Collections" docs/adapters.md    # one per catalogued adapter
uv run pytest -q

Depends on #2 for the vocabulary of what a "collection" formally is.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationready-for-agentFully specified and ready for an AFK agent

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions