From a303538ae5b6c19fcdc142c8981debdd76424a48 Mon Sep 17 00:00:00 2001 From: Yanxin Lu Date: Tue, 7 Apr 2026 15:18:42 -0700 Subject: [PATCH] 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 | 9 ++ agent_skills/calibre_import_workflow.md | 121 ++++++++++++++++++++++++ 2 files changed, 130 insertions(+) create mode 100644 agent_skills/calibre_import_workflow.md diff --git a/VAULT_MAP.md b/VAULT_MAP.md index 8fbad74..f699951 100644 --- a/VAULT_MAP.md +++ b/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` diff --git a/agent_skills/calibre_import_workflow.md b/agent_skills/calibre_import_workflow.md new file mode 100644 index 0000000..c6ceb07 --- /dev/null +++ b/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 -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 ` +- Do NOT pass all formats to `calibredb add` at once — it creates separate entries + +### 6. Apply metadata +```bash +calibredb set_metadata \ + -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