brain-pdf

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

Convention: see 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"