# Sci-Fi Book Showcase - Agent Instructions

This is a static HTML page showcasing a sci-fi book collection. It works fully offline with all assets stored locally.

## Quick Reference

- **Book data**: `data/books.json` (54 books)
- **Summaries**: `summaries/{id}.md` (one file per book, easy to edit)
- **Covers**: `images/covers/{id}.jpg`
- **Build command**: `node build.js`

## Key Points

- Summaries are markdown files in `summaries/` - edit directly, then run `node build.js`
- Always search by title+author first when looking for covers (not just ISBN)
- German books (Brandhorst, Reimer) often need alternative ISBN lookups
- Verify covers are real images (>10KB, JPEG format, not placeholders)

## Project Structure

```
/home/paul/git/scifi/
├── index.html              # Main page
├── css/styles.css          # Styling
├── js/app.js               # Client-side logic (filtering, modals)
├── data/books.json         # Book metadata (id, title, author, year, format, isbn, language, coverLocal)
├── summaries/{id}.md       # Book summaries as markdown files (easy to edit!)
├── images/covers/{id}.jpg  # Cover images (named by book ID)
├── input.json              # Original source data (reference only)
└── scripts/                # Utility scripts (not part of site)
```

## Adding a New Book

### 1. Update `data/books.json`

Add a new entry to the `books` array:

```json
{
  "id": 55,
  "title": "Book Title",
  "author": "Author Name",
  "year": 2024,
  "format": "Paperback",
  "isbn": "9781234567890",
  "language": "en",
  "coverLocal": "images/covers/55.jpg"
}
```

**Fields:**
- `id`: Unique integer (use next available number)
- `title`: Display title (use German title for German books)
- `author`: Author name
- `year`: Publication year
- `format`: One of "Paperback", "eBook", "Audiobook"
- `isbn`: ISBN-13 preferred (used for cover lookups)
- `language`: "en" or "de"
- `coverLocal`: Path to local cover image

### 2. Add Cover Image

Save cover as `images/covers/{id}.jpg`

**Finding covers (in order of preference):**

1. **OpenLibrary by title/author** (best for finding covers not indexed by ISBN):
   ```
   https://openlibrary.org/search.json?q={title}+{author}&limit=5
   ```
   Then get cover: `https://covers.openlibrary.org/b/id/{cover_i}-L.jpg`

2. **OpenLibrary by ISBN**:
   ```
   https://covers.openlibrary.org/b/isbn/{isbn}-L.jpg
   ```

3. **Google Books API**:
   ```
   https://www.googleapis.com/books/v1/volumes?q=isbn:{isbn}
   ```
   Extract `volumeInfo.imageLinks.thumbnail`, replace `zoom=1` with `zoom=2` or `zoom=3`

**Cover quality checks:**
- File size should be > 10KB (smaller = likely placeholder)
- Should be JPEG (check with `file` command)
- Resolution should be ~300x500 or better
- MD5 hash `c96309220b9cbd205c36d879d09a3647` = Google Books placeholder (reject it)

### 3. Add Summary

Create `summaries/{id}.md` with:

```markdown
# Book Title

Summary text goes here. Aim for 50-200 words describing the book's
plot, themes, and significance. This file is easy to edit manually.
```

**Finding summaries:**

1. **OpenLibrary Works API**:
   ```
   https://openlibrary.org/isbn/{isbn}.json  → get works[0].key
   https://openlibrary.org{works_key}.json   → get description
   ```

2. **Wikipedia API** (good for well-known books):
   ```
   https://{lang}.wikipedia.org/w/api.php?action=query&list=search&srsearch={title}+{author}&format=json
   https://{lang}.wikipedia.org/w/api.php?action=query&prop=extracts&exintro=true&explaintext=true&pageids={pageid}&format=json
   ```
   Use `de.wikipedia.org` for German books, `en.wikipedia.org` for English.

3. **Manual**: Write a summary based on publisher descriptions or reviews.

## Editing Summaries

Summaries are stored as individual markdown files in `summaries/`. To edit:

1. Open `summaries/{id}.md`
2. Edit the text (keep the `# Title` header)
3. Run `node build.js` to embed summaries into books.json
4. Refresh the page

This makes it easy to edit summaries in markdown without touching JSON directly.

## Building the Site

After editing any summary markdown files, run:

```bash
node build.js
```

This embeds all summaries from `summaries/*.md` into `data/books.json`, allowing the site to work offline without a server.

## Common Issues

### German books missing covers
German publishers (Piper, Heyne) often aren't in OpenLibrary. Try:
- Search by title+author instead of ISBN
- Try multiple ISBN editions (paperback, ebook, audiobook)
- Check if book exists under slightly different title

### Placeholder images
Google Books returns a 15567-byte placeholder for missing covers. Always verify:
```bash
file images/covers/{id}.jpg  # Should show JPEG, decent resolution
ls -la images/covers/{id}.jpg  # Should be > 10KB
```

### Cover is wrong book
Search by title+author can return wrong matches. Verify the cover matches by checking:
- Author name on cover
- Title spelling
- Publisher logo matches expected publisher

## Utility Scripts (in `scripts/`)

These are development utilities, not part of the deployed site:

- `download-assets.js` - Bulk download covers and summaries
- `fix-missing-covers.js` - Try alternative ISBNs for missing covers
- `fix-placeholders.js` - Replace placeholder images
- `fetch-all-summaries.js` - Fetch summaries from Wikipedia
- `sync-summaries.js` - Copy summaries from input.json to books.json

## Testing

```bash
cd /home/paul/git/scifi
python -m http.server 8000
# Open http://localhost:8000
```

Verify:
- All books display in grid
- Covers load (no broken images)
- Click opens modal with summary
- Filters work (author, format, search)