garrytan/gbrain

brain-pdf

Generate a publication-quality PDF from any brain page via the gstack make-pdf binary.

Vedi sorgente

Come usare

  1. Copia il comando e controlla il pacchetto prima di installarlo nel tuo ambiente agente.
  2. Controlla strumenti, credenziali e ambienti richiesti nel documento originale.
  3. Descrivi input e risultato desiderato; confronta l’output con le fonti.
npx skills add https://github.com/garrytan/gbrain --skill brain-pdf

Prima di iniziare

  • L’installazione non include abbonamenti, quote API o accesso ai file.
  • Stelle e installazioni indicano attività, non un test indipendente di qualità o sicurezza.
Documento Skill originale

Contenuto dal repository con titoli, esempi, codice, tabelle, link e immagini preservati.

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:

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 (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

bash
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

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)
  • 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 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.

  • ❌ Skipping the frontmatter strip. The renderer dumps frontmatter as

raw text on the first page; ugly.

  • ❌ Skipping emoji sanitization. Emoji that don't map to the rendering

font show up as □ boxes.

  • ❌ Adding --cover or --toc by default. Off unless asked.
  • ❌ Using raw MEDIA: tags for Telegram delivery. Use the message

tool with filePath.

Related skills

  • skills/book-mirror/SKILL.md — produces a brain page that's a

natural input to brain-pdf (chapter-by-chapter personalized analysis).

  • skills/strategic-reading/SKILL.md — same shape, problem-lens variant.
  • skills/publish/SKILL.md — share brain pages as password-protected

HTML (different rendering target).

Contract

This skill guarantees:

  • Routing matches the canonical triggers in the frontmatter.
  • Output written under the directories listed in writes_to: (when applicable).
  • Conventions referenced (quality.md, brain-first.md, _brain-filing-rules.md) are followed.
  • Privacy contract preserved: no real names, no fork-specific filesystem path literals, no upstream-fork references.

The full behavior contract is documented in the body sections above; this section exists for the conformance test.

Output Format

The skill's output shape is documented inline in the body sections above (see "Output", "Brain page format", or equivalent). The literal section header here exists for the conformance test (test/skills-conformance.test.ts).

dallo stesso repository

Altri Skills

Tutti gli Skills
garrytan
Community

academic-verify

Verify a research claim or academic citation by tracing it through publication → methodology → raw data → independent replication. Routes through perplexity-research for the actual web lookup, then formats results as a citation-checked brain page. Use when a book/article/conversation cites a study and you want to confirm the claim is real, replicated, and accurately characterized.

Installazioni / 1h
1
GitHub Stars
32,5K
Aggiornato
11 nov
garrytan
Community

ask-user

Reusable pattern for presenting the user with explicit choices and gating execution until they respond. Used by other skills when a decision point requires human input before proceeding. Platform-agnostic — works on Telegram (inline buttons), Discord, CLI, or any agent with a message tool.

Installazioni / 1h
1
GitHub Stars
32,5K
Aggiornato
11 nov
garrytan
Community

brain-ingest-gate

Pre-write quality gate for content entering the brain. No raw copies: a bare cp/mv into the brain repo is a bug. Before any new page lands, resolve named entities registry-first (a vector score is a floor for prose, never a gate for named things), then run the read-the-top-hit dedup decision tree (clear-dup / plausible-dup / clear). Owns dedup; delegates enrichment to the shipped ingestion skills. Routing convention, not an operation-boundary enforcement.

Installazioni / 1h
1
GitHub Stars
32,5K
Aggiornato
11 nov
garrytan
Community

brain-ops

Brain knowledge base operations. The core read/write cycle: brain-first lookup, read-enrich-write loop, source attribution, ambient enrichment, back-linking. Read this before any brain interaction.

Installazioni / 1h
1
GitHub Stars
32,5K
Aggiornato
11 nov