brain-pdf

brain-pdf — 脳ページを出版品質の PDF にレンダリングする

規約： 出力ルールについては、conventions/quality.md を参照してください。PDF はレンダリング結果であり、決して主要な成果物ではありません。PDF が存在する場合、その元となる脳ページも存在します。

ルール

脳ページが常に信頼できる唯一の情報源です。PDF はそのレンダリング結果であり、単独の成果物ではありません。どこかに PDF が存在する場合、その元となる脳ページも存在しなければなりません。

この機能について

gstack の make-pdf バイナリを使用して、脳ページ（フロントマター付きの Markdown）を出版品質の PDF にレンダリングします。出力は次の用途に適しています。

• パーソナライズした書籍ミラーをメールや Telegram で共有する
• 戦略的読書のプレイブックを読みやすい形式で提供する
• 柱見出しとページ番号付きのブリーフィングやレポートを作成する
• 長文のエッセイを携帯可能な形式でアーカイブする

前提条件：gstack make-pdf

このスキルは、次の場所にある gstack の make-pdf バイナリに依存します。

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

ユーザーは gstack を併せてインストールしている必要があります。インストールされていない場合、このスキルは実行できません。今後の v0.26+ では代替の PDF レンダラーが同梱される可能性がありますが、v0.25.1 では gstack は任意の前提条件です。

実行する前に、存在することを確認してください。

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

ワークフロー

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

実行方法

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 が必須です。Playwright に Chromium のサンドボックスをスキップするよう指示します。ベアメタル環境で設定しても問題ありません。

よくあるパターン

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

デフォルト：表紙なし、目次なし

ほとんどの個人向けナレッジコンテンツでは、これらのフラグを有効にすると企業向けの印象になり、スペースも無駄になるため、デフォルトではオフです。ユーザーが「正式な」出力を明示的に求めた場合（たとえば、取締役会に送る資料や納品物として印刷する資料）のみ追加してください。

フォント要件

レンダラーには次のフォントが必要です。

• fonts-liberation（Helvetica／Arial の代替フォント）
• fonts-noto-cjk（中国語／日本語／韓国語の文字）
• 本文の最小フォントサイズ：10pt（ページ周辺要素は 9pt）
• 本文テキスト：11pt

これらのフォントがない環境で実行する場合は、ホストのパッケージマネージャーを使ってインストールしてください（Debian／Ubuntu コンテナーでは apt install fonts-liberation fonts-noto-cjk）。

配布

レンダリング後、エージェントが推奨するチャネルで配布してください。

• Telegram： filePath="/tmp/<slug>.pdf" の添付ファイルを指定して message ツールを使用してください。生の MEDIA: タグは絶対に使用しないでください。エラーが表示されずに失敗します。
• メール： ホストのメールツールで添付してください。
• ファイルを直接応答： PDF のパスを出力してください。ユーザーは手動で取得できます。

配布メッセージには、ユーザーが GitHub またはローカルでも確認できるよう、必ず脳ページへのリンクを含めてください。PDF はレンダリング結果であり、成果物はソースです。

失敗した場合

gbrain のエラー code、終了コード、[AGENT] ブロック、または通知ブロックについては、エージェント運用プロトコルに従ってください。このスキル固有の対応は次のとおりです。

• gbrain get <slug> が page_not_found で失敗した場合は、レンダリング前に停止して正しいスラッグを特定してください。タイトル検索を行った後にのみ、ページが見つからないことを報告してください。
• make-pdf バイナリが見つからない場合、これは gbrain のエラーではなく、gstack の依存関係によるものです。gstack をインストールするようユーザーに伝えてください。独自に PDF を作成してはいけません。

アンチパターン

• ❌ 脳ページの存在を最初に確認せずに PDF を生成する。 ソースがなければ PDF もありません。
• ❌ フロントマターの削除を省略する。レンダラーはフロントマターを生テキストとして最初のページに出力するため、見栄えが悪くなります。
• ❌ 絵文字のサニタイズを省略する。レンダリング用フォントで表示できない絵文字は、□ の四角で表示されます。
• ❌ デフォルトで --cover または --toc を追加する。求められない限りオフにしてください。
• ❌ Telegram での配布に生の MEDIA: タグを使用する。filePath を指定して message ツールを使用してください。

関連スキル

• skills/book-mirror/SKILL.md — brain-pdf に自然な入力となる脳ページを作成します（章ごとにパーソナライズした分析）。
• skills/strategic-reading/SKILL.md — 同じ形式で、問題の視点を変えたバリエーションです。
• skills/publish/SKILL.md — パスワード保護された HTML として脳ページを共有します（レンダリング先が異なります）。

契約

このスキルでは、次のことを保証します。

• ルーティングがフロントマターの正規トリガーに一致します。
• （該当する場合）writes_to: に記載されたディレクトリ配下に出力を書き込みます。
• 参照されている規約（quality.md、brain-first.md、_brain-filing-rules.md）に従います。
• プライバシー契約を維持します。実名、フォーク固有のファイルシステムパスを示すリテラル、上流フォークへの言及は含めません。

動作契約の全文は上記の本文セクションに記載されています。このセクションは適合性テスト用に設けられています。

出力形式

スキルの出力形式は、本文セクション内に記載されています（「Output」、「Brain page format」または同等の項目を参照）。ここにある見出しは、適合性テスト（test/skills-conformance.test.ts）用のものです。