Add Calibre import workflow with Unraid setup, OPDS, and KOReader guide

Agent skill doc covering the full Calibre library workflow: importing
books via Unraid Docker containers, metadata management, tag rules,
KOReader OPDS access on Boox, and external serving options.

VAULT_MAP.md

@@ -21,6 +21,7 @@ home.md              — Personal dashboard (Obsidian Tasks widget)
 VAULT_MAP.md         — This file. Vault guide for humans and LLMs.
 README.md            — Git repo description.
 
+agent_skills/        — Runbooks and workflows for LLM/agent tasks (see below)
 copilot/             — Obsidian Copilot plugin data. Do not modify.
 Readwise/            — Readwise sync plugin data. Do not modify.
 templates/           — Note templates for journals, book notes, etc.
@@ -39,6 +40,14 @@ If you are an LLM or agent adding content to this vault, follow the guide for th
 
 The entire vault (not just `documents/`) is indexed by the notesearch skill (LlamaIndex + Ollama vector search).
 
+### Agent Skills (`agent_skills/`)
+
+Step-by-step runbooks for LLM/agent tasks. If you are an agent about to perform a task, check this folder first — there may already be a workflow written for it.
+
+- Files are freeform markdown with CLI commands, rules, and tips
+- One file per workflow (e.g., `calibre_import_workflow.md`)
+- These are living documents — update them when the process changes
+
 ### Journals (`journals/`)
 
 - One file per day, named `YYYY-MM-DD.md`

agent_skills/calibre_import_workflow.md

@@ -0,0 +1,121 @@
+# 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