@adaptic/maestro 1.1.6 → 1.1.8

package/docs/guides/pdf-generation-setup.md

@@ -0,0 +1,315 @@
+# PDF Generation Setup Guide
+
+How to generate branded PDF documents from Markdown using Pandoc + XeLaTeX. Covers installation, template system, brand integration, npm script shortcuts, customisation for new agents, testing, and troubleshooting.
+
+**Prerequisites**: Complete the [Mac Mini Bootstrap](../runbooks/mac-mini-bootstrap.md). Node.js 20+ must be installed.
+
+---
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Input: Markdown file (authored by agent or manually)            │
+│         │                                                        │
+│         ▼                                                        │
+│  build-document.mjs                                              │
+│    ├── Reads Markdown content                                    │
+│    ├── Selects LaTeX template based on --template flag           │
+│    ├── Injects metadata (title, author, date)                    │
+│    └── Calls Pandoc                                              │
+│         │                                                        │
+│         ▼                                                        │
+│  Pandoc + XeLaTeX                                                │
+│    ├── Applies LaTeX template (margins, fonts, headers/footers)  │
+│    ├── Embeds brand assets (logo from public/assets/)            │
+│    ├── Renders typography (Georgia, Helvetica Neue)              │
+│    └── Produces PDF                                              │
+│         │                                                        │
+│         ▼                                                        │
+│  Output: Branded PDF alongside source or at --output path       │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 1. Installation
+
+### 1.1 Install Pandoc
+
+```bash
+brew install pandoc
+pandoc --version  # Verify: should be 3.x+
+```
+
+### 1.2 Install XeLaTeX
+
+Two options depending on disk space:
+
+**Option A — TinyTeX (recommended, ~250MB)**:
+
+```bash
+# Install TinyTeX via Pandoc's helper
+pandoc +RTS -M512M -RTS --pdf-engine=xelatex -o /dev/null <(echo "test") 2>&1 || true
+
+# Or install directly
+curl -sL "https://yihui.org/tinytex/install-bin-unix.sh" | sh
+```
+
+TinyTeX installs to `~/Library/TinyTeX/`. The `build-document.mjs` script looks for XeLaTeX at `~/Library/TinyTeX/bin/universal-darwin/xelatex` by default.
+
+**Option B — Full MacTeX (~5GB)**:
+
+```bash
+brew install --cask mactex-no-gui
+```
+
+### 1.3 Install Node.js Dependencies
+
+```bash
+cd ~/agent-repo && npm install
+```
+
+The generator uses `execa` for subprocess management (included in the project's `package.json`).
+
+### 1.4 Verify Installation
+
+```bash
+# Check Pandoc
+pandoc --version
+
+# Check XeLaTeX
+xelatex --version 2>/dev/null || ~/Library/TinyTeX/bin/universal-darwin/xelatex --version
+
+# Quick test: generate a PDF from a test Markdown
+echo "# Test\nHello world" > /tmp/test.md
+node scripts/pdf-generation/build-document.mjs --input /tmp/test.md --template memo --output /tmp/test.pdf
+open /tmp/test.pdf
+```
+
+---
+
+## 2. Usage
+
+### 2.1 Direct Script
+
+```bash
+node scripts/pdf-generation/build-document.mjs \
+  --input <markdown-file> \
+  --template <template-name> \
+  [--output <pdf-path>] \
+  [--title "Document Title"] \
+  [--author "Author Name"] \
+  [--date "2026-04-09"]
+```
+
+### 2.2 npm Script Shortcuts
+
+Defined in `package.json`:
+
+```bash
+npm run pdf:memo -- --input <file>           # Internal memos and briefs
+npm run pdf:board-pack -- --input <file>     # Board materials with cover + TOC
+npm run pdf:letter -- --input <file>         # Corporate correspondence
+npm run pdf:investor -- --input <file>       # Investor communications
+```
+
+### 2.3 Arguments
+
+| Argument | Required | Default | Description |
+|---|---|---|---|
+| `--input`, `-i` | Yes | — | Path to Markdown source file |
+| `--template`, `-t` | No | `memo` | Template name (see section 3) |
+| `--output`, `-o` | No | Same dir as input, `.pdf` extension | Output PDF path |
+| `--title` | No | Extracted from Markdown `# heading` | Document title |
+| `--author` | No | Agent name from config | Author name |
+| `--date` | No | Today's date | Document date |
+
+---
+
+## 3. Templates
+
+Templates are LaTeX files in `scripts/pdf-generation/templates/`:
+
+| Template | File | Page Size | Margins | Use Case |
+|---|---|---|---|---|
+| `memo` | `memo.latex` | A4 | 20mm | Internal briefs, memos, decision documents |
+| `corporate-letter` | `corporate-letter.latex` | A4 | 25mm | Standard correspondence, regulatory submissions |
+| `board-pack` | `board-pack.latex` | A4 | 20mm | Board packs with cover page, TOC, section headers |
+| `investor-letter` | `corporate-letter.latex` | A4 | 30mm | Investor letters, LP updates (uses corporate-letter base) |
+
+### 3.1 Template Features
+
+**memo.latex**:
+- Clean single-column layout
+- Agent name and title in header
+- Date in header
+- Adaptic icon in header area
+- No TOC
+
+**corporate-letter.latex**:
+- Formal letterhead layout
+- Full Adaptic logo on first page
+- Sender address block
+- Confidentiality footer
+- Wider margins for readability
+
+**board-pack.latex**:
+- Branded cover page with full logo
+- Auto-generated table of contents
+- Section headers with visual hierarchy
+- Page numbers in footer
+- Designed for 10-50+ page documents
+
+### 3.2 Customising Templates
+
+To create a new template:
+
+1. Copy an existing template: `cp templates/memo.latex templates/proposal.latex`
+2. Edit the LaTeX file (typography, margins, header/footer, logo placement)
+3. Register it in `build-document.mjs` by adding to the `TEMPLATES` object:
+
+```javascript
+const TEMPLATES = {
+  // ... existing templates
+  "proposal": {
+    file: "proposal.latex",
+    description: "Client proposals and pitch documents",
+  },
+};
+```
+
+---
+
+## 4. Brand Integration
+
+### 4.1 Typography
+
+| Font | Usage | Source |
+|---|---|---|
+| Georgia | Main body text, headings | System font (macOS built-in) |
+| Helvetica Neue | Sans-serif elements, captions | System font (macOS built-in) |
+
+Configured in `config/brand-assets.yaml` → `typography.pdf`.
+
+### 4.2 Logo Placement
+
+Templates reference brand assets from `public/assets/`:
+
+| Asset | Template Usage |
+|---|---|
+| `adaptic-logo-dark.svg` | Cover pages, letterheads (light backgrounds) |
+| `adaptic-icon-dark.svg` | Page headers, footers (compact mark) |
+
+### 4.3 Colour Scheme
+
+Sourced from `config/brand-assets.yaml`:
+
+- Primary dark: `#151919`
+- Canvas background: `#f5f4f2` (light mode)
+- Accent colours for headings and rules
+
+### 4.4 Customising for a New Agent
+
+When deploying a new agent:
+
+1. Update author default in `build-document.mjs` (`config.author`)
+2. Update logo paths in templates if using a different brand
+3. Update font selections in templates if brand guidelines specify different fonts
+4. Keep the Adaptic brand assets for Adaptic agents — only change for non-Adaptic entities
+
+---
+
+## 5. XeLaTeX Path Configuration
+
+The generator looks for XeLaTeX in this order:
+
+1. `XELATEX_PATH` environment variable (if set)
+2. `~/Library/TinyTeX/bin/universal-darwin/xelatex` (TinyTeX default)
+3. System PATH (for full MacTeX installation)
+
+If XeLaTeX is installed elsewhere, set in `.env`:
+
+```bash
+XELATEX_PATH=/usr/local/texlive/2024/bin/universal-darwin/xelatex
+```
+
+---
+
+## 6. Testing
+
+| # | Test | How to Verify |
+|---|---|---|
+| 1 | Pandoc installed | `pandoc --version` |
+| 2 | XeLaTeX installed | `xelatex --version` or check TinyTeX path |
+| 3 | Memo generation | `npm run pdf:memo -- --input <test.md>` → opens clean PDF |
+| 4 | Board pack generation | `npm run pdf:board-pack -- --input <test.md>` → has cover + TOC |
+| 5 | Logo renders | Check generated PDF for Adaptic logo in header |
+| 6 | Typography correct | Body text should be Georgia, sans elements Helvetica Neue |
+| 7 | Custom output path | Use `--output /tmp/test.pdf` → PDF created at specified path |
+
+---
+
+## 7. Troubleshooting
+
+### "xelatex not found"
+
+1. Check TinyTeX: `ls ~/Library/TinyTeX/bin/universal-darwin/xelatex`
+2. Check MacTeX: `which xelatex`
+3. Set explicit path: `XELATEX_PATH=/path/to/xelatex`
+4. Install: see section 1.2
+
+### "Missing LaTeX package"
+
+TinyTeX installs minimal packages. If a template requires one that's missing:
+
+```bash
+# Install a specific package
+~/Library/TinyTeX/bin/universal-darwin/tlmgr install <package-name>
+
+# Common packages needed
+~/Library/TinyTeX/bin/universal-darwin/tlmgr install fontspec geometry fancyhdr graphicx
+```
+
+### "Font not found"
+
+1. Verify Georgia and Helvetica Neue are available: `fc-list | grep Georgia`
+2. These are macOS system fonts — should be pre-installed
+3. If missing, install via Font Book or use alternative fonts in the template
+
+### PDF output is blank or malformed
+
+1. Check Pandoc version: `pandoc --version` (need 3.x+)
+2. Run with verbose output to see LaTeX errors:
+   ```bash
+   pandoc --pdf-engine=xelatex --verbose -o output.pdf input.md
+   ```
+3. Check the LaTeX template for syntax errors
+4. Verify Markdown input is valid (no unclosed tags, proper heading hierarchy)
+
+### Logo not appearing in PDF
+
+1. Check logo file exists: `ls public/assets/adaptic-logo-dark.svg`
+2. SVG support requires the `svg` LaTeX package or convert to PDF first
+3. Some templates use PDF versions of logos — check the template's `\includegraphics` paths
+
+---
+
+## Key Files
+
+| File | Purpose |
+|---|---|
+| `scripts/pdf-generation/build-document.mjs` | Main generator script |
+| `scripts/pdf-generation/templates/memo.latex` | Memo template |
+| `scripts/pdf-generation/templates/corporate-letter.latex` | Correspondence template |
+| `scripts/pdf-generation/templates/board-pack.latex` | Board pack template (cover + TOC) |
+| `config/brand-assets.yaml` | Brand colours, typography, logo paths |
+| `public/assets/` | SVG brand assets (logos, icons) |
+
+---
+
+## Related Documents
+
+- [Agent Persona Setup](agent-persona-setup.md) — Author name configuration
+- [Media Generation Setup](media-generation-setup.md) — Visual asset generation for documents
+- [Mac Mini Bootstrap](../runbooks/mac-mini-bootstrap.md) — Pandoc/MacTeX installation