Add AGENTS.md with instructions for adding new books

Documents project structure, data format, and process for:
- Adding entries to books.json
- Finding and validating cover images
- Fetching summaries from APIs
- Troubleshooting common issues

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

1 files changed, 142 insertions, 0 deletions

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..7464b45
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,142 @@
+# 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.
+
+## 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 (THE source of truth)
+├── 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",
+  "summary": "A compelling summary of the book...",
+  "summarySource": "manual"
+}
+```
+
+**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
+- `summary`: Book description (aim for 50-200 words)
+- `summarySource`: Where summary came from ("OpenLibrary", "Wikipedia", "manual", etc.)
+
+### 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. Finding Summaries
+
+**Sources (in order of preference):**
+
+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.
+
+## 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)