Books #

Minimal--inteded as canonical--book tracking lexicons for atproto.

Two records:

com.hectorsector.book.book       - a book in a user's library
com.hectorsector.book.status     - a change in the user's reading journey

This repo is #

We define irreducible primitives for book tracking here: what book, what status, when.

1. CLI importer for goodreads and storygraph data

   • Input: CSV -> Output: com.hectorsector.book.* stores in PDS

2. Viewer

   • Read-only
   • Input: handles -> Output: renders shelves

Future #

Import UI in the viewer

User flow #

Setup #

1. Clone the repo and build:

   cd cli
   make
   

2. Set BSKY_HANDLE and BSKY_APP_PASSWORD in a .env file or your environment
3. Export your library from StoryGraph as a CSV
4. Parse the CSV:

   books import storygraph.csv
   # will create a data store, defaults to: ~/.books/store.json
   # can be changed with `books import storygraph.csv --store <location>`
   

5. Look up OpenLibrary Work IDs for each book; re-runnable, skips books already enriched

   books enrich
   

6. Ceate records on your PDS for each book and the reading status; re-runnable, skips already-published books

   books publish
   

(FUTURE) Web viewer #

7. Run books serve — starts a local web server at localhost:8080
8. Open the viewer in a browser; use the file picker to import a StoryGraph CSV
9. Review your book list, trigger enrichment, and publish — all with live per-book feedback in the UI

This repo is NOT #

Anything beyond the primitives we've defined is either for apps to implement on their own or for future lexicons to develop. We do not concern ourselves here with: shelves, ratings, reviews, reading progress, mood, tags, social features.

This is infra, not a product.

Why? #

The book tracking ecosystem is fragmented across predictable lines. Each existing app (atproto and otherwise) has tried to solve book tracking as products that are Goodreads-like replacements. But that leads to some of the same burdens from the pre-atproto tech, namely nontransferrable book records, reviews, users are siloed even though the underlying data is essentially identical.