# 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: 
    ```sh
    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:
    ```sh
    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
    ```sh
    books enrich
    ```
6. Ceate records on your PDS for each book and the reading status; re-runnable, skips already-published books
    ```sh
    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.