brain-pdf

Files (2)

• SKILL.md
• routing-eval.jsonl

SKILL.md (first lines)

# 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:

```bash
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 (nbrain 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

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

# 1. Confirm the page exists.
nbrain 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 nbrain for the body via the API.
BRAIN_DIR=$(nbrain 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)
  nbrain get "$SLUG" --raw > "$RAW"   # whatever flag exposes raw body
fi

# 3. Strip YAML frontmatter — sed: skip the opening '---' through the
#    closing '---' (lines 1..N), then keep everything after.
CLEAN=$(mktemp /tmp/brain-page-clean-XXXXXX.md)
sed '1{/^---$/!q}; /^---$/,/^---$/d' "$RAW" > "$CLEAN"

# 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

```bash
# 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)

From nastechresearch/nbrain, MIT.

More from nastechresearch/nbrain