# Calibre Book Import Workflow

## Library Setup

The Calibre library lives on an **Unraid server** with two Docker containers:
- **linuxserver/calibre** — full desktop GUI, accessible via browser (for manual imports/editing)
- **linuxserver/calibre-web** — web reader frontend for reading books

Library path on Unraid: `/mnt/user/la-share/home/books/calibre_library/`

### Docker permissions
- Containers should use `PUID=99` and `PGID=100` (maps to `nobody:users`)
- If SMB write issues occur: `chown -R nobody:users /mnt/user/la-share/home/books/calibre_library/`

## Importing New Books

### Option 1: Calibre GUI container (recommended for routine imports)
1. Upload new book files to Unraid (via copyparty or SMB)
2. Open the Calibre GUI container in browser
3. Drag and drop to import, edit metadata, fetch covers

### Option 2: With Claude's help (for bulk imports or metadata cleanup)
1. Upload new book files to Unraid
2. Import into the Calibre GUI container
3. Ask Claude to generate `calibredb` commands for metadata fixes
4. Run commands via Unraid terminal or `docker exec`:
   ```bash
   docker exec calibre calibredb list --library-path /config/library
   docker exec calibre calibredb set_metadata <id> -f title:"Title" --library-path /config/library
   ```
   (Adjust container name and library path as needed)

### Option 3: Local import then sync (for large batches)
1. Import and fix metadata locally on Mac using CLI tools at `/Applications/calibre.app/Contents/MacOS/`
2. Copy the specific book folders + updated `metadata.db` to Unraid via copyparty
3. Stop containers before overwriting `metadata.db`, restart after

## Import Steps (Detail)

### 1. List files to import
Show file names, sizes, and formats from the source folder.

### 2. Check for duplicates
```bash
# Local
sqlite3 "$HOME/Calibre Library/metadata.db" "SELECT id, title FROM books ORDER BY title;"

# Or on Unraid
docker exec calibre calibredb list --library-path /config/library
```

### 3. Fetch metadata (do NOT import yet)
```bash
fetch-ebook-metadata -t "Title" -a "Author"
```
Uses 3 plugins: New Douban Books, Google Books, Amazon.com.

If not found online, read embedded metadata:
- `ebook-meta file.epub` (often has good embedded data)
- `ebook-convert file.pdf /tmp/out.txt` (extract text to identify unknown files)

### 4. Show complete metadata for approval
Present ALL metadata for ALL books before importing:
- Title, Author(s), Publisher, Tags, ISBN

**Wait for explicit approval before proceeding.**

### 5. Import
```bash
calibredb add "file.epub" --library-path "$LIB"
```

For multi-format books (same book in epub + mobi + pdf):
- Import the first format with `calibredb add`
- Add additional formats with `calibredb add_format <id> <file>`
- Do NOT pass all formats to `calibredb add` at once — it creates separate entries

### 6. Apply metadata
```bash
calibredb set_metadata <id> \
  -f title:"Book Title" \
  -f authors:"Author Name" \
  -f publisher:"Publisher" \
  -f tags:"tag1,tag2,tag3" \
  -f identifiers:"isbn:1234567890" \
  -f series:"Series Name" \
  -f series_index:"1" \
  --library-path "$LIB"
```

### 7. Verify and clean up
- Check for split entries — merge with `add_format` + `remove`
- Verify titles, authors, tags are correct
- Delete source files after successful import

## Tag Rules

- **Chinese tags for Chinese books** — never English equivalents
- **No publisher/author/year/title as tags** — use their dedicated fields
- **No overly generic tags** — avoid 经典, 中国, 人文, 入门, 教程, 参考
- **Consolidate similar tags** — check existing tags before creating new ones

## Reading on Boox (KOReader + OPDS)

Calibre-web serves an OPDS catalog automatically. KOReader on Boox has built-in OPDS support.

### Setup
1. Open KOReader → **Search** (magnifying glass) → **OPDS catalog**
2. Add a new catalog: `http://UNRAID_IP:8083/opds` (adjust port to match Calibre-web)
3. Browse library, tap a book to download directly to the e-reader

### Reading strategy
- **KOReader** for books — optimized for e-ink, great typography control, PDF reflow, offline dictionary
- **Readwise Reader** for articles, RSS, newsletters — highlight sync, cross-device reading

## Serving Externally

Options for accessing the library outside the home network:
- **Tailscale** (recommended) — install on Unraid (community plugin) + Boox (Android app). Access Calibre-web OPDS via Tailscale IP: `http://100.x.x.x:8083/opds`. Free tier supports 100 devices.
- **Cloudflare Tunnel** — free, no open ports, gives public URL like `books.yourdomain.com`
- **Reverse proxy** — Nginx Proxy Manager + domain, requires port 443 open