Kindle Export

Purpose

Get a Claude-generated document onto a Kindle in one command.

Send to Kindle does not accept .md, so conversion is mandatory. The source file stays the source of truth; the EPUB is a derived artifact.

Scope (v1)

Deliberately not in scope: OCR, PDF reconstruction, EPUBCheck, MathML, Mermaid rendering, cover generation, typography CSS, compression, chunking. Amazon re-typesets the EPUB on ingest, so elaborate CSS is wasted work.

Artifact contract

Same contract as html-human-review:

• The source file is the source of truth.
• The EPUB goes to an artifacts/ folder beside the source file.
• The artifact is updated in place, never versioned (doc-v2.epub, doc-final.epub are wrong).

project/notes/
├── prep-entrevista.md
└── artifacts/
    └── prep-entrevista.epub

Required behavior

1. Resolve the source file. Use the path given as argument. If none, prefer the file the user just mentioned; if several are equally plausible, ask instead of converting all.
2. Convert by running the script (never hand-roll the EPUB).
3. Show the report and the recipient address.
4. Ask for explicit confirmation before sending. Only then re-run with --send --yes.
5. Never claim delivery. Send to Kindle returns no acknowledgement. The honest statement is "se envió", never "llegó".

Commands

# 1. Convert only (writes artifacts/<name>.epub, sends nothing)
python3 <skill-dir>/kindle_export.py path/to/document.md

# 2. Convert and send, after the user confirms the recipient
python3 <skill-dir>/kindle_export.py path/to/document.md --send --yes

--lang sets the EPUB language (default es).

Metadata rules

• Title and author come from the YAML front matter when present.
• No front-matter title → infer from the first # H1 (or <title>/<h1> for HTML), falling back to the filename.
• No author → send with no author. Never invent authorship.

Kindle-safe pass (minimal, on purpose)

Semantic emojis render poorly on e-ink, so a small map replaces them with words:

Extend it with an emoji_map.json beside the script. Keep it small.

Position decides the treatment. An emoji that opens a Markdown heading is decoration, not content — substituting a word there corrupts the title and the TOC (## ⭐ Outputs would become "Destacado Outputs"). So: leading emoji in a heading → deleted; emoji anywhere else → replaced via the map. Deletions are never silent — the report lists every heading emoji removed. A heading made up of only an emoji is left to the map instead, so it never ends up empty.

Text arrows (→), em dashes and × are content, not decoration: the pass leaves them alone.

Hard rule, enforced in code: the pass must never alter á é í ó ú ü ñ Á É Í Ó Ú Ü Ñ ¿ ¡. The script counts these characters before and after and aborts if any count changes. Do not weaken this check.

Hard rules (in code, not in the prompt)

• Size ceiling is 25 MB on the built message, not on the file. Gmail — not Amazon — is the binding limit. Above it Gmail swaps the attachment for a Drive link, Amazon receives a mail with no attachment, and it fails silently. The script measures the encoded message and refuses to send. It also warns above ~18 MB of raw attachment, since base64 adds ~37%.
• The App Password comes from the macOS Keychain (service kindle-export, account = the sender address), with KINDLE_SMTP_PASSWORD as a fallback for non-macOS. The two addresses — KINDLE_EMAIL, KINDLE_SENDER_EMAIL — come from the environment. Never write a password, app password, or token into any file, and never ask the user to paste one into the chat.
• If a credential does land in the conversation, say so plainly and tell the user to revoke it at https://myaccount.google.com/apppasswords before anything else. Do not use it, do not echo it, do not store it. Have the user run the send from their own terminal instead.
• Sending requires --send; without a TTY it also requires --yes. Converting never sends.
• Gmail rejects the account password — only an App Password works. The script's auth error explains how to generate one.

Report

The script prints a short terminal report: source, conversion, title, artifact path, size, emojis replaced, send status. Relay it as-is. Do not write a summary .md file.

Setup

One-time setup (approving the sender address with Amazon, generating the App Password, exporting the variables) is documented in README.md. The skill does not automate it — Amazon's approval list is manual by design.