/book-mirror

name: book-mirror
version: 0.1.0
description: Take any book (EPUB/PDF), produce a personalized chapter-by-chapter analysis with two-column tables. Left column preserves the chapter content; right column maps every idea to the reader's actual life using brain context. Output is a single brain page at media/books/<slug>-personalized.md plus an optional PDF via brain-pdf.
triggers:
  - "personalized version of this book"
  - "mirror this book"
  - "two-column book analysis"
  - "apply this book to my life"
  - "how does this book apply to me"
mutating: true
writes_pages: true
writes_to:
  - media/books/

book-mirror — Personalized Chapter-by-Chapter Book Analysis

> **Convention:** see [_brain-filing-rules.md](../_brain-filing-rules.md) for the > sanctioned `media/<format>/<slug>` exception this skill files under. > > **Convention:** see [conventions/quality.md](../conventions/quality.md) for > citation rules, back-link enforcement, and output quality bars. > > **Convention:** see [conventions/brain-first.md](../conventions/brain-first.md) > for the lookup chain (brain → search → external) the context-gathering > phase follows.

What this does

Given a book (EPUB or PDF), produce a brain page where every chapter is summarized in detail on the left and mirrored back to the reader's actual life on the right, using their own words, situations, people, and patterns from the brain. Output is a brain page at `media/books/<slug>-personalized.md`.

This is NOT a generic book summary. The right column is the value: it makes the book read like a therapist who knows the reader is leaving notes in the margins. If the user wants a flat summary instead, route them to a different skill.

Trust contract (read this before running)

book-mirror runs as a CLI command (`gbrain book-mirror`), NOT as a pure markdown skill that the agent dispatches via tools. The CLI is the trusted runtime; the skill is the orchestration prose around it.

What this means for the agent:

• The CLI submits N read-only subagent jobs (one per chapter). Each subagent

has `allowed_tools: ['get_page', 'search']` only. They CANNOT call put_page or any mutating op. They produce markdown analysis via their final message.

• The CLI reads each child's `job.result`, assembles the final

two-column page, and writes it via a single operator-trust `put_page`.

• This means untrusted EPUB/PDF content cannot prompt-inject any

`people/*` page. The trust narrowing happens at the tool allowlist, not at the slug-prefix layer.

The pipeline

1. ACQUIRE   → User has the EPUB/PDF locally (manual; book-acquisition is
               not currently shipped — see "Acquiring the book" below).
2. EXTRACT   → Pull chapter text from EPUB/PDF into one .txt per chapter.
3. CONTEXT   → Gather everything the brain knows about the reader.
4. ANALYZE   → `gbrain book-mirror` fans out N read-only subagents.
5. ASSEMBLE  → CLI reads each child result and writes one put_page.
6. PDF       → Optional: render via skills/brain-pdf for delivery.

1. Acquiring the book

book-acquisition (legal-grey-area downloader) was deliberately not shipped in this skill wave. The user drops the EPUB/PDF manually. Common paths the user might use:

# User-supplied path
ls path/to/book.epub
ls path/to/book.pdf

# Or already in the brain repo (recommended for tracking)
ls $BRAIN_DIR/media/books/

Resolve `$BRAIN_DIR` from the gbrain config (`gbrain config get sync.repo_path`) or accept it from the user.

2. Text extraction

Goal: one `.txt` file per chapter under a temp directory. The agent has shell + python access; the CLI is downstream of this and takes the extracted directory as input.

EPUB

SLUG="this-book"                                # kebab-case
WORK="$(mktemp -d)/$SLUG"
mkdir -p "$WORK/chapters"
unzip -o path/to/book.epub -d "$WORK/unpacked"

# Find content files (XHTML/HTML), sorted (chapter order = sort order)
find "$WORK/unpacked" -name "*.xhtml" -o -name "*.html" | sort > "$WORK/files.txt"

# Strip HTML to text per chapter
python3 - <<'PY'
from bs4 import BeautifulSoup
import os, sys
work = os.environ['WORK']
files = open(f'{work}/files.txt').read().splitlines()
for i, path in enumerate(files, 1):
    html = open(path, encoding='utf-8', errors='replace').read()
    text = BeautifulSoup(html, 'html.parser').get_text('\n')
    text = '\n'.join(line.strip() for line in text.splitlines() if line.strip())
    with open(f'{work}/chapters/{i:02d}.txt', 'w') as f:
        f.write(text)
PY

If `bs4` is missing: `pip3 install beautifulsoup4 lxml`.

Inspect the chapter files to identify which are real chapters vs front matter (TOC, copyright, acknowledgments). Often the EPUB ships one file per chapter; sometimes multiple chapters per file. Use `head -5 "$WORK/chapters/"*.txt` to spot-check.

PDF

pdftotext -layout path/to/book.pdf "$WORK/full.txt"

Then split by chapter heading (look for "Chapter N", "CHAPTER N", or all-caps title lines) using `awk` or `python`. If the PDF is a scan with no embedded text, fall back to OCR via `skills/brain-pdf` or another vision tool.

Quality check

For each chapter file:

• Word count > 1500 (typical chapter range 2k–8k words).
• No HTML tags.
• Paragraphs preserved with `\n\n`.

Save a `chapters/INDEX.md` mapping chapter number → title → file → word count for reference.

3. Context gathering

This is the most critical step. The right column is only as good as the context fed to each chapter subagent.

What to pull

1. **Templates: USER.md and SOUL.md** if the user maintains them (gbrain ships templates at `templates/USER.md` and `templates/SOUL.md`; they live in the brain repo when populated). Read full. 2. **Recent daily memory** — last 14 days of brain pages under `wiki/personal/reflections/` or wherever the user files daily notes. 3. **Topic-relevant brain searches** tuned to the book's themes:

• `gbrain query "marriage"`, `gbrain query "cou