/brain-pdf

name: brain-pdf
version: 0.1.0
description: Generate a publication-quality PDF from any brain page via the gstack make-pdf binary. Strips YAML frontmatter, sanitizes emoji, applies running headers and page numbers. Brain page is always the source of truth; PDF is a rendering.
triggers:
  - "make pdf from brain"
  - "brain pdf"
  - "convert brain page to pdf"
  - "publish this page as pdf"
  - "export brain page"

brain-pdf — Render a Brain Page to Publication-Quality PDF

> **Convention:** see [conventions/quality.md](../conventions/quality.md) for > output rules. The PDF is a rendering — never the primary artifact. If a > PDF exists, the source brain page exists behind it.

The rule

The brain page is ALWAYS the source of truth. The PDF is a rendering of it, never a standalone artifact. If a PDF exists somewhere, the brain page must exist behind it.

What this does

Renders a brain page (markdown with frontmatter) into a publication-quality PDF using the gstack `make-pdf` binary. Output is suitable for:

• Sharing a personalized book mirror via email or Telegram
• Delivering a strategic-reading playbook as a clean read
• Producing a briefing or report with running headers and page numbers
• Archiving a long-form essay in a portable format

Prerequisite: gstack make-pdf

This skill depends on the gstack `make-pdf` binary at:

$HOME/.claude/skills/gstack/make-pdf/dist/pdf

The user must have gstack co-installed. If absent, the skill cannot run. A future v0.26+ may bundle a fallback PDF renderer; for v0.25.1 gstack is a soft prereq.

Verify it exists before invoking:

P="$HOME/.claude/skills/gstack/make-pdf/dist/pdf"
[ -x "$P" ] || { echo "make-pdf not installed; install gstack" >&2; exit 1; }

Workflow

1. RESOLVE  → Confirm the brain page exists (gbrain get <slug>).
2. STRIP    → Remove YAML frontmatter — the renderer would otherwise
              dump it as a full page of raw metadata text.
3. RENDER   → Invoke make-pdf with sane defaults (no --cover, no --toc).
4. DELIVER  → Hand the PDF to the requester via the agent's preferred
              channel (do not use raw `MEDIA:` tags on Telegram —
              they fail silently).

Invocation

SLUG="path/to/page"
P="$HOME/.claude/skills/gstack/make-pdf/dist/pdf"

# 1. Confirm the page exists.
gbrain get "$SLUG" > /dev/null || { echo "Page $SLUG not found" >&2; exit 1; }

# 2. Get the raw markdown. Two paths: read from the brain repo (if user
#    syncs locally) OR ask gbrain for the body via the API.
BRAIN_DIR=$(gbrain config get sync.repo_path 2>/dev/null || echo)
if [ -n "$BRAIN_DIR" ] && [ -f "$BRAIN_DIR/$SLUG.md" ]; then
  RAW="$BRAIN_DIR/$SLUG.md"
else
  RAW=$(mktemp /tmp/brain-page-XXXXXX.md)
  gbrain get "$SLUG" > "$RAW"   # prints the page as markdown with frontmatter
fi

# 3. Strip the leading YAML frontmatter block only: line 1 '---' through
#    the next '---'. A later '---' (a horizontal rule) and a page without
#    frontmatter are kept as written. Plain awk, so it behaves the same with
#    BSD (macOS) and GNU tools. Stop if nothing is left to render.
CLEAN=$(mktemp /tmp/brain-page-clean-XXXXXX.md)
awk 'NR==1 && /^---[[:space:]]*$/ {f=1; next} f==1 && /^---[[:space:]]*$/ {f=2; next} f!=1' "$RAW" > "$CLEAN"
[ -s "$CLEAN" ] || { echo "brain-pdf: nothing to render for $SLUG after removing frontmatter" >&2; exit 1; }

# 4. Render. NO --cover, NO --toc by default — they look corporate
#    and waste space. Add them only if explicitly requested.
OUT="/tmp/$(basename "$SLUG").pdf"
CONTAINER=1 "$P" generate "$CLEAN" "$OUT"

echo "Rendered: $OUT"

`CONTAINER=1` is mandatory in containerized environments — it tells Playwright to skip Chromium sandboxing. Harmless on bare-metal.

Common patterns

# Default — clean PDF, no cover, no TOC
brain-pdf <slug>

# Draft watermark for in-progress work
CONTAINER=1 "$P" generate --watermark DRAFT "$CLEAN" "$OUT"

# Optional cover + TOC if the user explicitly asks
CONTAINER=1 "$P" generate --cover --toc "$CLEAN" "$OUT"

# Custom title + author override (otherwise pulled from frontmatter)
CONTAINER=1 "$P" generate --title "Custom Title" --author "Custom Author" "$CLEAN" "$OUT"

Defaults: NO cover, NO TOC

These flags are off by default because they look corporate and waste space on most personal-knowledge content. Only add them when the user explicitly asks for "formal" output (e.g., something they're sending to a board or printing as a deliverable).

Font requirements

The renderer needs:

• `fonts-liberation` (Helvetica/Arial substitute)
• `fonts-noto-cjk` (Chinese/Japanese/Korean characters)
• Minimum body font size: 10pt (page chrome 9pt)
• Body text: 11pt

If running in an environment without these fonts, install them via the host's package manager (`apt install fonts-liberation fonts-noto-cjk` on Debian/Ubuntu containers).

Delivery

After rendering, deliver via the agent's preferred channel:

• **Telegram:** use the `message` tool with `filePath="/tmp/<slug>.pdf"`

attachment. NEVER use raw `MEDIA:` tags — they fail silently.

• **Email:** attach via the host's email tool.
• **Direct file response:** print the PDF path; the user can pull it

manually.

Always include the brain page link in the delivery message so the user can also see it on GitHub / locally. The PDF is a rendering; the source is the artifact.

When it fails

Follow the [agent operator protocol](../conventions/agent-operator-protocol.md) for any gbrain error `code`, exit code, `[AGENT]` block or notice block. Specific to this skill:

• `gbrain get <slug>` fails with `page_not_found`: stop before rendering and resolve the real slug; report the page missing only after a title search.
• The make-pdf binary is missing: this is a gstack dependency, not a gbrain error. Tell the user to install gstack; do not hand-roll a PDF.

Anti-Patterns

• ❌ Generating a PDF without first confirming the brain page exists.

No source = no PDF.

• ❌ Ski