@nomad-e/bluma-cli 0.1.22 → 0.1.23

package/dist/config/skills/pdf/SKILL.md

@@ -5,288 +5,448 @@ description: >
   new PDFs from scratch, reading or extracting text and tables from PDFs,
   merging or splitting PDFs, rotating pages, adding watermarks, encrypting or
   decrypting PDFs, filling PDF forms, extracting images, and OCR on scanned
-  PDFs to make them searchable. Use this skill whenever the user mentions
-  .pdf, "PDF document", "create a report as PDF", "extract from PDF",
-  "merge PDFs", "split PDF", "protect PDF", "fill a form", or any
-  PDF-related task — even if not explicitly stated as such.
-
+  PDFs. Use whenever the user mentions .pdf, "create a report", "generate a
+  document", "extract from PDF", "merge PDFs", or any PDF-related task.
 license: Proprietary. LICENSE.txt has complete terms
 ---
 
-# PDF Processing Guide
+# PDF — Professional Document Creation & Processing
 
-## Overview
+## Design Philosophy
 
-This guide covers essential PDF processing operations using Python libraries
-and command-line tools. For advanced features, JavaScript libraries, and
-detailed examples, see references/REFERENCE.md. If you need to fill out a
-PDF form, read references/FORMS.md and follow its instructions.
+> Every PDF generated by BluMa must look like it was made by a professional
+> design agency, not a script. Typography, spacing, color, and hierarchy are
+> not optional — they are the foundation of a credible document.
 
-## Quick Start
+## MANDATORY: Professional Style System
 
-```python
-from pypdf import PdfReader, PdfWriter
+Every PDF you create MUST use a consistent design system. Define these at the
+top of every script BEFORE building any content.
 
-# Read a PDF
-reader = PdfReader("document.pdf")
-print(f"Pages: {len(reader.pages)}")
+### Color Palette
 
-# Extract text
-text = ""
-for page in reader.pages:
-    text += page.extract_text()
+```python
+from reportlab.lib.colors import HexColor
+
+COLORS = {
+    'primary':    HexColor('#1B2A4A'),  # Dark navy — titles, headers
+    'secondary':  HexColor('#2C5F8A'),  # Steel blue — subtitles, accents
+    'accent':     HexColor('#E67E22'),  # Warm orange — highlights, callouts
+    'text':       HexColor('#2D3436'),  # Near-black — body text
+    'text_light': HexColor('#636E72'),  # Gray — captions, footnotes
+    'bg_light':   HexColor('#F8F9FA'),  # Light gray — callout backgrounds
+    'bg_accent':  HexColor('#EBF5FB'),  # Light blue — info boxes
+    'border':     HexColor('#BDC3C7'),  # Subtle border
+    'white':      HexColor('#FFFFFF'),
+    'success':    HexColor('#27AE60'),  # Green — positive indicators
+    'danger':     HexColor('#E74C3C'),  # Red — warnings
+}
 ```
 
-## Python Libraries
-
-### pypdf — Basic Operations
+### Typography
 
-#### Merge PDFs
 ```python
-from pypdf import PdfWriter, PdfReader
-
-writer = PdfWriter()
-for pdf_file in ["doc1.pdf", "doc2.pdf", "doc3.pdf"]:
-    reader = PdfReader(pdf_file)
-    for page in reader.pages:
-        writer.add_page(page)
-
-with open("merged.pdf", "wb") as output:
-    writer.write(output)
+from reportlab.lib.styles import ParagraphStyle
+from reportlab.lib.enums import TA_LEFT, TA_CENTER, TA_JUSTIFY
+
+FONT_BODY = 'Helvetica'
+FONT_BOLD = 'Helvetica-Bold'
+FONT_ITALIC = 'Helvetica-Oblique'
+FONT_MONO = 'Courier'
+
+STYLES = {
+    'doc_title': ParagraphStyle(
+        'DocTitle', fontName=FONT_BOLD, fontSize=28, leading=34,
+        textColor=COLORS['primary'], alignment=TA_CENTER,
+        spaceAfter=6,
+    ),
+    'doc_subtitle': ParagraphStyle(
+        'DocSubtitle', fontName=FONT_BODY, fontSize=14, leading=18,
+        textColor=COLORS['secondary'], alignment=TA_CENTER,
+        spaceAfter=30,
+    ),
+    'h1': ParagraphStyle(
+        'H1', fontName=FONT_BOLD, fontSize=20, leading=26,
+        textColor=COLORS['primary'], spaceBefore=28, spaceAfter=12,
+        borderWidth=0, borderPadding=0,
+    ),
+    'h2': ParagraphStyle(
+        'H2', fontName=FONT_BOLD, fontSize=15, leading=20,
+        textColor=COLORS['secondary'], spaceBefore=20, spaceAfter=8,
+    ),
+    'h3': ParagraphStyle(
+        'H3', fontName=FONT_BOLD, fontSize=12, leading=16,
+        textColor=COLORS['text'], spaceBefore=14, spaceAfter=6,
+    ),
+    'body': ParagraphStyle(
+        'Body', fontName=FONT_BODY, fontSize=10.5, leading=15,
+        textColor=COLORS['text'], alignment=TA_JUSTIFY,
+        spaceBefore=2, spaceAfter=8,
+    ),
+    'caption': ParagraphStyle(
+        'Caption', fontName=FONT_ITALIC, fontSize=9, leading=12,
+        textColor=COLORS['text_light'], alignment=TA_CENTER,
+        spaceBefore=4, spaceAfter=12,
+    ),
+    'bullet': ParagraphStyle(
+        'Bullet', fontName=FONT_BODY, fontSize=10.5, leading=15,
+        textColor=COLORS['text'], leftIndent=24, bulletIndent=12,
+        spaceBefore=2, spaceAfter=4,
+    ),
+    'code': ParagraphStyle(
+        'Code', fontName=FONT_MONO, fontSize=9, leading=13,
+        textColor=COLORS['text'], backColor=COLORS['bg_light'],
+        leftIndent=12, rightIndent=12,
+        spaceBefore=6, spaceAfter=6,
+        borderWidth=0.5, borderColor=COLORS['border'],
+        borderPadding=8,
+    ),
+    'footer': ParagraphStyle(
+        'Footer', fontName=FONT_BODY, fontSize=8, leading=10,
+        textColor=COLORS['text_light'], alignment=TA_CENTER,
+    ),
+}
 ```
 
-#### Split PDF
-```python
-reader = PdfReader("input.pdf")
-for i, page in enumerate(reader.pages):
-    writer = PdfWriter()
-    writer.add_page(page)
-    with open(f"page_{i+1}.pdf", "wb") as output:
-        writer.write(output)
-```
+### Page Layout
 
-#### Extract Metadata
 ```python
-reader = PdfReader("document.pdf")
-meta = reader.metadata
-print(f"Title: {meta.title}")
-print(f"Author: {meta.author}")
-print(f"Subject: {meta.subject}")
-print(f"Creator: {meta.creator}")
+from reportlab.lib.pagesizes import A4
+from reportlab.lib.units import cm, mm
+
+PAGE_WIDTH, PAGE_HEIGHT = A4
+MARGIN_LEFT = 2.5 * cm
+MARGIN_RIGHT = 2.5 * cm
+MARGIN_TOP = 2.5 * cm
+MARGIN_BOTTOM = 2.5 * cm
+CONTENT_WIDTH = PAGE_WIDTH - MARGIN_LEFT - MARGIN_RIGHT
 ```
 
-#### Rotate Pages
-```python
-reader = PdfReader("input.pdf")
-writer = PdfWriter()
-
-page = reader.pages[0]
-page.rotate(90)  # Rotate 90 degrees clockwise
-writer.add_page(page)
+## Document Structure Template
 
-with open("rotated.pdf", "wb") as output:
-    writer.write(output)
-```
+Every professional PDF MUST follow this structure:
 
-### pdfplumber — Text and Table Extraction
+### 1. Cover Page
 
-#### Extract Text with Layout
 ```python
-import pdfplumber
-
-with pdfplumber.open("document.pdf") as pdf:
-    for page in pdf.pages:
-        text = page.extract_text()
-        print(text)
+from reportlab.platypus import (
+    SimpleDocTemplate, Paragraph, Spacer, PageBreak,
+    Table, TableStyle, Image, HRFlowable
+)
+
+def build_cover(story, title, subtitle=None, author=None, date=None):
+    story.append(Spacer(1, 6 * cm))
+
+    story.append(Paragraph(title, STYLES['doc_title']))
+
+    story.append(Spacer(1, 0.5 * cm))
+    story.append(HRFlowable(
+        width='40%', thickness=2, color=COLORS['accent'],
+        spaceAfter=20, spaceBefore=10,
+    ))
+
+    if subtitle:
+        story.append(Paragraph(subtitle, STYLES['doc_subtitle']))
+
+    story.append(Spacer(1, 3 * cm))
+
+    if author:
+        meta_style = ParagraphStyle(
+            'Meta', fontName=FONT_BODY, fontSize=11,
+            textColor=COLORS['text_light'], alignment=TA_CENTER,
+            spaceAfter=4,
+        )
+        story.append(Paragraph(author, meta_style))
+
+    if date:
+        date_style = ParagraphStyle(
+            'Date', fontName=FONT_BODY, fontSize=10,
+            textColor=COLORS['secondary'], alignment=TA_CENTER,
+        )
+        story.append(Paragraph(date, date_style))
+
+    story.append(PageBreak())
 ```
 
-#### Extract Tables
-```python
-with pdfplumber.open("document.pdf") as pdf:
-    for i, page in enumerate(pdf.pages):
-        tables = page.extract_tables()
-        for j, table in enumerate(tables):
-            print(f"Table {j+1} on page {i+1}:")
-            for row in table:
-                print(row)
-```
+### 2. Header and Footer
 
-#### Advanced Table Extraction
 ```python
-import pandas as pd
-
-with pdfplumber.open("document.pdf") as pdf:
-    all_tables = []
-    for page in pdf.pages:
-        tables = page.extract_tables()
-        for table in tables:
-            if table:
-                df = pd.DataFrame(table[1:], columns=table[0])
-                all_tables.append(df)
-
-if all_tables:
-    combined_df = pd.concat(all_tables, ignore_index=True)
-    combined_df.to_excel("extracted_tables.xlsx", index=False)
+def header_footer(canvas_obj, doc):
+    canvas_obj.saveState()
+
+    # Header line
+    canvas_obj.setStrokeColor(COLORS['secondary'])
+    canvas_obj.setLineWidth(1.5)
+    y_header = PAGE_HEIGHT - 1.5 * cm
+    canvas_obj.line(MARGIN_LEFT, y_header, PAGE_WIDTH - MARGIN_RIGHT, y_header)
+
+    # Header text
+    canvas_obj.setFont(FONT_BODY, 8)
+    canvas_obj.setFillColor(COLORS['text_light'])
+    canvas_obj.drawString(MARGIN_LEFT, y_header + 4, doc.title or '')
+
+    # Footer line
+    y_footer = 1.2 * cm
+    canvas_obj.setStrokeColor(COLORS['border'])
+    canvas_obj.setLineWidth(0.5)
+    canvas_obj.line(MARGIN_LEFT, y_footer + 8, PAGE_WIDTH - MARGIN_RIGHT, y_footer + 8)
+
+    # Page number
+    canvas_obj.setFont(FONT_BODY, 8)
+    canvas_obj.setFillColor(COLORS['text_light'])
+    page_text = f"Page {doc.page}"
+    canvas_obj.drawCentredString(PAGE_WIDTH / 2, y_footer, page_text)
+
+    canvas_obj.restoreState()
 ```
 
-### reportlab — Create PDFs
+### 3. Table of Contents
 
-#### Basic PDF Creation
 ```python
-from reportlab.lib.pagesizes import A4
-from reportlab.pdfgen import canvas
-
-c = canvas.Canvas("hello.pdf", pagesize=A4)
-width, height = A4
-
-# Add text
-c.drawString(100, height - 100, "Hello World!")
-c.drawString(100, height - 120, "This is a PDF created with reportlab")
-
-# Add a line
-c.line(100, height - 140, 400, height - 140)
-
-c.save()
+def build_toc(story, sections):
+    story.append(Paragraph("Table of Contents", STYLES['h1']))
+    story.append(Spacer(1, 0.5 * cm))
+
+    toc_style = ParagraphStyle(
+        'TOCEntry', fontName=FONT_BODY, fontSize=11, leading=20,
+        textColor=COLORS['text'],
+    )
+    toc_bold = ParagraphStyle(
+        'TOCBold', fontName=FONT_BOLD, fontSize=11, leading=20,
+        textColor=COLORS['primary'],
+    )
+
+    for i, section in enumerate(sections, 1):
+        title = section['title']
+        page = section.get('page', '')
+        is_main = section.get('level', 1) == 1
+
+        style = toc_bold if is_main else toc_style
+        indent = 0 if is_main else 20
+
+        entry = Table(
+            [[Paragraph(f"{' ' * (indent // 4)}{i}. {title}" if is_main else f"   {title}", style),
+              Paragraph(str(page), style)]],
+            colWidths=[CONTENT_WIDTH - 40, 40],
+        )
+        entry.setStyle(TableStyle([
+            ('ALIGN', (1, 0), (1, 0), 'RIGHT'),
+            ('VALIGN', (0, 0), (-1, -1), 'MIDDLE'),
+            ('LINEBELOW', (0, 0), (-1, -1), 0.5, COLORS['bg_light']),
+            ('TOPPADDING', (0, 0), (-1, -1), 4),
+            ('BOTTOMPADDING', (0, 0), (-1, -1), 4),
+        ]))
+        story.append(entry)
+
+    story.append(PageBreak())
 ```
 
-#### Create PDF with Multiple Pages
-```python
-from reportlab.lib.pagesizes import A4
-from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, PageBreak
-from reportlab.lib.styles import getSampleStyleSheet
-
-doc = SimpleDocTemplate("report.pdf", pagesize=A4)
-styles = getSampleStyleSheet()
-story = []
-
-# Add content
-title = Paragraph("Report Title", styles['Title'])
-story.append(title)
-story.append(Spacer(1, 12))
-
-body = Paragraph("This is the body of the report. " * 20, styles['Normal'])
-story.append(body)
-story.append(PageBreak())
+### 4. Section Headers with Accent Bar
 
-# Page 2
-story.append(Paragraph("Page 2", styles['Heading1']))
-story.append(Paragraph("Content for page 2", styles['Normal']))
-
-# Build PDF
-doc.build(story)
+```python
+def add_section(story, number, title):
+    header_table = Table(
+        [[Paragraph(f"{number}.", ParagraphStyle(
+            'SNum', fontName=FONT_BOLD, fontSize=20,
+            textColor=COLORS['accent'],
+        )),
+          Paragraph(title, STYLES['h1'])]],
+        colWidths=[35, CONTENT_WIDTH - 35],
+    )
+    header_table.setStyle(TableStyle([
+        ('VALIGN', (0, 0), (-1, -1), 'TOP'),
+        ('TOPPADDING', (0, 0), (-1, -1), 0),
+        ('BOTTOMPADDING', (0, 0), (-1, -1), 0),
+    ]))
+    story.append(header_table)
+
+    story.append(HRFlowable(
+        width='100%', thickness=1, color=COLORS['secondary'],
+        spaceAfter=12,
+    ))
 ```
 
-#### Subscripts and Superscripts
-
-**IMPORTANT**: Never use Unicode subscript/superscript characters (₀₁₂₃₄₅₆₇₈₉,
-⁰¹²³⁴⁵⁶⁷⁸⁹) in ReportLab PDFs. The built-in fonts do not include these glyphs,
-causing them to render as solid black boxes.
+### 5. Callout / Info Boxes
 
-pdftk file1.pdf file2.pdf cat output merged.pdf
-
-# Split
-pdftk input.pdf burst
-from reportlab.lib.styles import getSampleStyleSheet
-
-styles = getSampleStyleSheet()
+```python
+def add_callout(story, title, text, box_type='info'):
+    bg = COLORS['bg_accent'] if box_type == 'info' else COLORS['bg_light']
+    border = COLORS['secondary'] if box_type == 'info' else COLORS['accent']
+    icon = '💡' if box_type == 'info' else '⚠️'
+
+    content = [
+        [Paragraph(
+            f"<b>{icon} {title}</b>",
+            ParagraphStyle('CalloutTitle', fontName=FONT_BOLD,
+                           fontSize=10, textColor=COLORS['primary'],
+                           spaceAfter=4)
+        )],
+        [Paragraph(
+            text,
+            ParagraphStyle('CalloutBody', fontName=FONT_BODY,
+                           fontSize=9.5, leading=14,
+                           textColor=COLORS['text'])
+        )],
+    ]
+
+    table = Table(content, colWidths=[CONTENT_WIDTH - 20])
+    table.setStyle(TableStyle([
+        ('BACKGROUND', (0, 0), (-1, -1), bg),
+        ('BOX', (0, 0), (-1, -1), 1.5, border),
+        ('LEFTPADDING', (0, 0), (-1, -1), 14),
+        ('RIGHTPADDING', (0, 0), (-1, -1), 14),
+        ('TOPPADDING', (0, 0), (0, 0), 10),
+        ('BOTTOMPADDING', (-1, -1), (-1, -1), 10),
+        ('VALIGN', (0, 0), (-1, -1), 'MIDDLE'),
+    ]))
+    story.append(Spacer(1, 8))
+    story.append(table)
+    story.append(Spacer(1, 8))
+```
 
-# Subscripts: use <sub> tag
-chemical = Paragraph("H<sub>2</sub>O", styles['Normal'])
+### 6. Professional Tables
 
-# Superscripts: use <super> tag
-squared = Paragraph("x<super>2</super> + y<super>2</super>", styles['Normal'])
+```python
+def add_table(story, headers, rows, col_widths=None):
+    data = [headers] + rows
+
+    if not col_widths:
+        col_widths = [CONTENT_WIDTH / len(headers)] * len(headers)
+
+    table = Table(data, colWidths=col_widths, repeatRows=1)
+    table.setStyle(TableStyle([
+        # Header
+        ('BACKGROUND', (0, 0), (-1, 0), COLORS['primary']),
+        ('TEXTCOLOR', (0, 0), (-1, 0), COLORS['white']),
+        ('FONTNAME', (0, 0), (-1, 0), FONT_BOLD),
+        ('FONTSIZE', (0, 0), (-1, 0), 10),
+        ('BOTTOMPADDING', (0, 0), (-1, 0), 10),
+        ('TOPPADDING', (0, 0), (-1, 0), 10),
+
+        # Body rows
+        ('FONTNAME', (0, 1), (-1, -1), FONT_BODY),
+        ('FONTSIZE', (0, 1), (-1, -1), 9.5),
+        ('TEXTCOLOR', (0, 1), (-1, -1), COLORS['text']),
+        ('TOPPADDING', (0, 1), (-1, -1), 7),
+        ('BOTTOMPADDING', (0, 1), (-1, -1), 7),
+
+        # Alternating row colors
+        *[('BACKGROUND', (0, i), (-1, i), COLORS['bg_light'])
+          for i in range(1, len(data), 2)],
+
+        # Grid
+        ('LINEBELOW', (0, 0), (-1, 0), 1.5, COLORS['secondary']),
+        ('LINEBELOW', (0, 1), (-1, -2), 0.5, COLORS['border']),
+        ('LINEBELOW', (0, -1), (-1, -1), 1, COLORS['secondary']),
+
+        ('ALIGN', (0, 0), (-1, -1), 'LEFT'),
+        ('VALIGN', (0, 0), (-1, -1), 'MIDDLE'),
+        ('LEFTPADDING', (0, 0), (-1, -1), 10),
+        ('RIGHTPADDING', (0, 0), (-1, -1), 10),
+    ]))
+    story.append(table)
+    story.append(Spacer(1, 12))
 ```
 
-For canvas-drawn text (not Paragraph objects), manually adjust font size and
-position rather than using Unicode subscripts/superscripts.
-
-## Command-Line Tools
+### 7. Building the Document
 
-### pdftotext (poppler-utils)
-```bash
-# Extract text
-pdftotext input.pdf output.txt
+```python
+from datetime import date
+
+doc = SimpleDocTemplate(
+    "output.pdf",
+    pagesize=A4,
+    leftMargin=MARGIN_LEFT,
+    rightMargin=MARGIN_RIGHT,
+    topMargin=MARGIN_TOP,
+    bottomMargin=MARGIN_BOTTOM,
+    title="Document Title",
+    author="BluMa",
+)
 
-# Extract text preserving layout
-pdftotext -layout input.pdf output.txt
+story = []
 
-# Extract specific pages
-pdftotext -f 1 -l 5 input.pdf output.txt  # Pages 1-5
-```
+build_cover(story, "Document Title", subtitle="A Professional Report",
+            author="Generated by BluMa", date=date.today().strftime('%B %Y'))
 
-### qpdf
-```bash
-# Merge PDFs
-qpdf --empty --pages file1.pdf file2.pdf -- merged.pdf
+build_toc(story, [
+    {'title': 'Introduction', 'level': 1, 'page': 3},
+    {'title': 'Analysis', 'level': 1, 'page': 5},
+])
 
-# Split pages
-qpdf input.pdf --pages . 1-5 -- pages1-5.pdf
-qpdf input.pdf --pages . 6-10 -- pages6-10.pdf
+add_section(story, 1, "Introduction")
+story.append(Paragraph("Body text here...", STYLES['body']))
+add_callout(story, "Key Insight", "Important information goes here.")
 
-# Rotate pages
-qpdf input.pdf output.pdf --rotate=+90:1  # Rotate page 1 by 90 degrees
+add_section(story, 2, "Analysis")
+add_table(story,
+    ['Metric', 'Value', 'Change'],
+    [['Revenue', '$1.2M', '+15%'], ['Users', '50K', '+22%']],
+)
 
-# Remove password
-qpdf --password=mypassword --decrypt encrypted.pdf decrypted.pdf
+doc.build(story, onFirstPage=lambda c, d: None,
+          onLaterPages=header_footer)
 ```
 
-### pdftk (if available)
-```bash
-# Merge
-pdftk file1.pdf file2.pdf cat output merged.pdf
-
-# Split
-pdftk input.pdf burst
+## Design Rules (MANDATORY)
+
+1. **Never use default reportlab styles** — always create custom styles
+2. **Font hierarchy**: Title 28pt > H1 20pt > H2 15pt > H3 12pt > Body 10.5pt
+3. **Line height**: Always 1.4x font size minimum (e.g. 10.5pt font → 15pt leading)
+4. **Margins**: Minimum 2.5cm on all sides
+5. **Color**: Maximum 3-4 colors per document. Use the palette above
+6. **Tables**: Always have header styling, alternating rows, proper padding
+7. **Spacing**: Generous whitespace. Use `Spacer` between sections
+8. **Cover page**: Every document with 3+ pages MUST have a cover page
+9. **Headers/Footers**: Every multi-page document MUST have page numbers
+10. **No raw `drawString`**: Use `Paragraph` with styles for all text
+11. **Alignment**: Body text justified, titles centered, code left-aligned
+12. **Callout boxes**: Use for key insights, warnings, important notes
+13. **Section dividers**: Use `HRFlowable` or colored bars between major sections
+14. **Subscripts/Superscripts**: Use `<sub>` and `<super>` tags, NEVER Unicode chars
+
+## Reading & Extracting from PDFs
+
+### Extract Text
+```python
+import pdfplumber
 
-# Rotate
-pdftk input.pdf rotate 1east output rotated.pdf
+with pdfplumber.open("document.pdf") as pdf:
+    for page in pdf.pages:
+        print(page.extract_text())
 ```
 
-## Common Tasks
-
-### Extract Text from Scanned PDFs
+### Extract Tables to DataFrame
 ```python
-# Requires: pip install pytesseract pdf2image
-import pytesseract
-from pdf2image import convert_from_path
-
-# Convert PDF to images
-images = convert_from_path('scanned.pdf')
+import pandas as pd
+import pdfplumber
 
-# OCR each page
-text = ""
-for i, image in enumerate(images):
-    text += f"Page {i+1}:\n"
-    text += pytesseract.image_to_string(image, lang="por+eng")
-    text += "\n\n"
+with pdfplumber.open("document.pdf") as pdf:
+    tables = []
+    for page in pdf.pages:
+        for table in page.extract_tables():
+            if table:
+                df = pd.DataFrame(table[1:], columns=table[0])
+                tables.append(df)
 
-print(text)
+    if tables:
+        combined = pd.concat(tables, ignore_index=True)
+        combined.to_excel("extracted.xlsx", index=False)
 ```
 
-### Add Watermark
-```python
-from pypdf import PdfReader, PdfWriter
+## Merge, Split, Protect
 
-# Load watermark
-watermark = PdfReader("watermark.pdf").pages[0]
+### Merge PDFs
+```python
+from pypdf import PdfWriter, PdfReader
 
-# Apply to all pages
-reader = PdfReader("document.pdf")
 writer = PdfWriter()
+for f in ["doc1.pdf", "doc2.pdf"]:
+    for page in PdfReader(f).pages:
+        writer.add_page(page)
 
-for page in reader.pages:
-    page.merge_page(watermark)
-    writer.add_page(page)
-
-with open("watermarked.pdf", "wb") as output:
-    writer.write(output)
-```
-
-### Extract Images
-```bash
-# Using pdfimages (poppler-utils)
-pdfimages -j input.pdf output_prefix
-# Extracts all images as output_prefix-000.jpg, output_prefix-001.jpg, etc.
+with open("merged.pdf", "wb") as out:
+    writer.write(out)
 ```
 
 ### Password Protection
@@ -295,33 +455,48 @@ from pypdf import PdfReader, PdfWriter
 
 reader = PdfReader("input.pdf")
 writer = PdfWriter()
-
 for page in reader.pages:
     writer.add_page(page)
+writer.encrypt("user_password", "owner_password")
 
-# Add password
-writer.encrypt("userpassword", "ownerpassword")
+with open("protected.pdf", "wb") as out:
+    writer.write(out)
+```
+
+## OCR (Scanned PDFs)
+```python
+import pytesseract
+from pdf2image import convert_from_path
 
-with open("encrypted.pdf", "wb") as output:
-    writer.write(output)
+images = convert_from_path('scanned.pdf')
+text = ""
+for i, img in enumerate(images):
+    text += f"--- Page {i+1} ---\n"
+    text += pytesseract.image_to_string(img, lang="por+eng")
+    text += "\n\n"
 ```
 
 ## Quick Reference
 
-| Task                  | Best Tool    | Command/Code                        |
-|-----------------------|--------------|-------------------------------------|
-| Merge PDFs            | pypdf        | `writer.add_page(page)`             |
-| Split PDFs            | pypdf        | One page per file                   |
-| Extract text          | pdfplumber   | `page.extract_text()`               |
-| Extract tables        | pdfplumber   | `page.extract_tables()`             |
-| Create PDFs           | reportlab    | Canvas or Platypus                  |
-| Command line merge    | qpdf         | `qpdf --empty --pages ...`          |
-| OCR scanned PDFs      | pytesseract  | Convert to image first              |
-| Fill PDF forms        | pypdf / pdf-lib (see FORMS.md) | See references/FORMS.md |
-
-## Next Steps
-
-- For advanced pypdfium2 usage, see references/REFERENCE.md
-- For JavaScript libraries (pdf-lib), see references/REFERENCE.md
-- If you need to fill out a PDF form, follow the instructions in references/FORMS.md
-- For troubleshooting guides, see references/REFERENCE.md
+| Task | Tool | Key API |
+|------|------|---------|
+| Create PDF | reportlab | `SimpleDocTemplate` + `Platypus` |
+| Read text | pdfplumber | `page.extract_text()` |
+| Read tables | pdfplumber | `page.extract_tables()` |
+| Merge | pypdf | `PdfWriter.add_page()` |
+| Split | pypdf | One page per `PdfWriter` |
+| Protect | pypdf | `writer.encrypt()` |
+| Watermark | pypdf | `page.merge_page()` |
+| OCR | pytesseract | `image_to_string()` |
+| Forms | pypdf | See references/FORMS.md |
+| CLI merge | qpdf | `qpdf --empty --pages` |
+
+## Available References
+
+- REFERENCE.md: Advanced reportlab features, JavaScript pdf-lib, CLI tools
+- FORMS.md: Filling and creating PDF forms
+
+## Available Scripts
+
+- create_report.py: Professional report template with cover, TOC, styled sections
+- merge_pdfs.py: Merge multiple PDFs into one

package/dist/config/skills/pdf/scripts/create_report.py

@@ -1,59 +1,289 @@
+#!/usr/bin/env python3
 """
-Create a simple PDF report from CSV data using reportlab.
+Professional PDF Report Generator — BluMa Template
 
 Usage:
-    python create_report.py --input data.csv --output ./artifacts/report.pdf
-    python create_report.py --input data.csv --output report.pdf --title "Sales Report Q1 2026"
+    python create_report.py [--title TITLE] [--subtitle SUBTITLE] [--output FILE]
+
+Generates a professional report PDF with cover page, table of contents,
+styled sections, tables, and callout boxes.
 """
+
 import argparse
-import csv
-import sys
-
-def create_report(input_csv: str, output_pdf: str, title: str = "Report") -> None:
-    try:
-        from reportlab.lib.pagesizes import A4
-        from reportlab.lib import colors
-        from reportlab.platypus import SimpleDocTemplate, Table, TableStyle, Paragraph, Spacer
-        from reportlab.lib.styles import getSampleStyleSheet
-    except ImportError:
-        print("Error: reportlab is required. Install with: pip install reportlab", file=sys.stderr)
-        sys.exit(1)
-
-    with open(input_csv, "r", encoding="utf-8") as f:
-        reader = csv.reader(f)
-        data = list(reader)
-
-    if not data:
-        print("Error: CSV file is empty", file=sys.stderr)
-        sys.exit(1)
-
-    doc = SimpleDocTemplate(output_pdf, pagesize=A4)
-    styles = getSampleStyleSheet()
-    elements = []
-
-    elements.append(Paragraph(title, styles["Title"]))
-    elements.append(Spacer(1, 20))
-
-    table = Table(data)
-    table.setStyle(TableStyle([
-        ("BACKGROUND", (0, 0), (-1, 0), colors.grey),
-        ("TEXTCOLOR", (0, 0), (-1, 0), colors.whitesmoke),
-        ("ALIGN", (0, 0), (-1, -1), "CENTER"),
-        ("FONTNAME", (0, 0), (-1, 0), "Helvetica-Bold"),
-        ("FONTSIZE", (0, 0), (-1, 0), 12),
-        ("BOTTOMPADDING", (0, 0), (-1, 0), 12),
-        ("BACKGROUND", (0, 1), (-1, -1), colors.beige),
-        ("GRID", (0, 0), (-1, -1), 1, colors.black),
+from datetime import date
+
+from reportlab.lib.pagesizes import A4
+from reportlab.lib.units import cm
+from reportlab.lib.colors import HexColor
+from reportlab.lib.styles import ParagraphStyle
+from reportlab.lib.enums import TA_CENTER, TA_JUSTIFY, TA_LEFT
+from reportlab.platypus import (
+    SimpleDocTemplate, Paragraph, Spacer, PageBreak,
+    Table, TableStyle, HRFlowable,
+)
+
+
+# ── Color Palette ──────────────────────────────────────────────
+
+COLORS = {
+    'primary':    HexColor('#1B2A4A'),
+    'secondary':  HexColor('#2C5F8A'),
+    'accent':     HexColor('#E67E22'),
+    'text':       HexColor('#2D3436'),
+    'text_light': HexColor('#636E72'),
+    'bg_light':   HexColor('#F8F9FA'),
+    'bg_accent':  HexColor('#EBF5FB'),
+    'border':     HexColor('#BDC3C7'),
+    'white':      HexColor('#FFFFFF'),
+}
+
+# ── Typography ─────────────────────────────────────────────────
+
+FONT = 'Helvetica'
+FONT_B = 'Helvetica-Bold'
+FONT_I = 'Helvetica-Oblique'
+
+PAGE_W, PAGE_H = A4
+M = 2.5 * cm
+CW = PAGE_W - 2 * M
+
+S = {
+    'title': ParagraphStyle('T', fontName=FONT_B, fontSize=28, leading=34,
+                            textColor=COLORS['primary'], alignment=TA_CENTER, spaceAfter=6),
+    'subtitle': ParagraphStyle('ST', fontName=FONT, fontSize=14, leading=18,
+                               textColor=COLORS['secondary'], alignment=TA_CENTER, spaceAfter=30),
+    'h1': ParagraphStyle('H1', fontName=FONT_B, fontSize=20, leading=26,
+                         textColor=COLORS['primary'], spaceBefore=28, spaceAfter=12),
+    'h2': ParagraphStyle('H2', fontName=FONT_B, fontSize=15, leading=20,
+                         textColor=COLORS['secondary'], spaceBefore=20, spaceAfter=8),
+    'body': ParagraphStyle('B', fontName=FONT, fontSize=10.5, leading=15,
+                           textColor=COLORS['text'], alignment=TA_JUSTIFY,
+                           spaceBefore=2, spaceAfter=8),
+    'bullet': ParagraphStyle('BL', fontName=FONT, fontSize=10.5, leading=15,
+                             textColor=COLORS['text'], leftIndent=24, bulletIndent=12,
+                             spaceBefore=2, spaceAfter=4),
+    'meta': ParagraphStyle('M', fontName=FONT, fontSize=11,
+                           textColor=COLORS['text_light'], alignment=TA_CENTER, spaceAfter=4),
+    'date': ParagraphStyle('D', fontName=FONT, fontSize=10,
+                           textColor=COLORS['secondary'], alignment=TA_CENTER),
+    'toc': ParagraphStyle('TOC', fontName=FONT, fontSize=11, leading=20,
+                          textColor=COLORS['text']),
+    'toc_b': ParagraphStyle('TOCB', fontName=FONT_B, fontSize=11, leading=20,
+                            textColor=COLORS['primary']),
+}
+
+
+# ── Components ─────────────────────────────────────────────────
+
+def cover(story, title, subtitle=None, author=None):
+    story.append(Spacer(1, 6 * cm))
+    story.append(Paragraph(title, S['title']))
+    story.append(Spacer(1, 0.5 * cm))
+    story.append(HRFlowable(width='40%', thickness=2, color=COLORS['accent'],
+                             spaceAfter=20, spaceBefore=10))
+    if subtitle:
+        story.append(Paragraph(subtitle, S['subtitle']))
+    story.append(Spacer(1, 3 * cm))
+    if author:
+        story.append(Paragraph(author, S['meta']))
+    story.append(Paragraph(date.today().strftime('%B %Y'), S['date']))
+    story.append(PageBreak())
+
+
+def toc(story, sections):
+    story.append(Paragraph("Table of Contents", S['h1']))
+    story.append(Spacer(1, 0.5 * cm))
+    for sec in sections:
+        style = S['toc_b'] if sec.get('level', 1) == 1 else S['toc']
+        indent = '' if sec.get('level', 1) == 1 else '    '
+        row = Table(
+            [[Paragraph(f"{indent}{sec['num']}. {sec['title']}" if sec.get('level', 1) == 1
+                        else f"{indent}{sec['title']}", style),
+              Paragraph(str(sec.get('page', '')), style)]],
+            colWidths=[CW - 40, 40],
+        )
+        row.setStyle(TableStyle([
+            ('ALIGN', (1, 0), (1, 0), 'RIGHT'),
+            ('VALIGN', (0, 0), (-1, -1), 'MIDDLE'),
+            ('LINEBELOW', (0, 0), (-1, -1), 0.5, COLORS['bg_light']),
+            ('TOPPADDING', (0, 0), (-1, -1), 4),
+            ('BOTTOMPADDING', (0, 0), (-1, -1), 4),
+        ]))
+        story.append(row)
+    story.append(PageBreak())
+
+
+def section(story, num, title):
+    header = Table(
+        [[Paragraph(f"{num}.", ParagraphStyle('SN', fontName=FONT_B, fontSize=20,
+                                              textColor=COLORS['accent'])),
+          Paragraph(title, S['h1'])]],
+        colWidths=[35, CW - 35],
+    )
+    header.setStyle(TableStyle([
+        ('VALIGN', (0, 0), (-1, -1), 'TOP'),
+        ('TOPPADDING', (0, 0), (-1, -1), 0),
+        ('BOTTOMPADDING', (0, 0), (-1, -1), 0),
+    ]))
+    story.append(header)
+    story.append(HRFlowable(width='100%', thickness=1, color=COLORS['secondary'],
+                             spaceAfter=12))
+
+
+def callout(story, title, text, box_type='info'):
+    bg = COLORS['bg_accent'] if box_type == 'info' else COLORS['bg_light']
+    border = COLORS['secondary'] if box_type == 'info' else COLORS['accent']
+    content = [
+        [Paragraph(f"<b>{title}</b>",
+                   ParagraphStyle('CT', fontName=FONT_B, fontSize=10,
+                                  textColor=COLORS['primary'], spaceAfter=4))],
+        [Paragraph(text, ParagraphStyle('CB', fontName=FONT, fontSize=9.5,
+                                        leading=14, textColor=COLORS['text']))],
+    ]
+    t = Table(content, colWidths=[CW - 20])
+    t.setStyle(TableStyle([
+        ('BACKGROUND', (0, 0), (-1, -1), bg),
+        ('BOX', (0, 0), (-1, -1), 1.5, border),
+        ('LEFTPADDING', (0, 0), (-1, -1), 14),
+        ('RIGHTPADDING', (0, 0), (-1, -1), 14),
+        ('TOPPADDING', (0, 0), (0, 0), 10),
+        ('BOTTOMPADDING', (-1, -1), (-1, -1), 10),
     ]))
-    elements.append(table)
+    story.append(Spacer(1, 8))
+    story.append(t)
+    story.append(Spacer(1, 8))
 
-    doc.build(elements)
-    print(f"Report created: {output_pdf} ({len(data)-1} data rows)")
 
-if __name__ == "__main__":
-    parser = argparse.ArgumentParser(description="Create PDF report from CSV")
-    parser.add_argument("--input", "-i", required=True, help="Input CSV file")
-    parser.add_argument("--output", "-o", required=True, help="Output PDF path")
-    parser.add_argument("--title", "-t", default="Report", help="Report title")
+def pro_table(story, headers, rows, col_widths=None):
+    data = [headers] + rows
+    if not col_widths:
+        col_widths = [CW / len(headers)] * len(headers)
+    t = Table(data, colWidths=col_widths, repeatRows=1)
+    t.setStyle(TableStyle([
+        ('BACKGROUND', (0, 0), (-1, 0), COLORS['primary']),
+        ('TEXTCOLOR', (0, 0), (-1, 0), COLORS['white']),
+        ('FONTNAME', (0, 0), (-1, 0), FONT_B),
+        ('FONTSIZE', (0, 0), (-1, 0), 10),
+        ('BOTTOMPADDING', (0, 0), (-1, 0), 10),
+        ('TOPPADDING', (0, 0), (-1, 0), 10),
+        ('FONTNAME', (0, 1), (-1, -1), FONT),
+        ('FONTSIZE', (0, 1), (-1, -1), 9.5),
+        ('TEXTCOLOR', (0, 1), (-1, -1), COLORS['text']),
+        ('TOPPADDING', (0, 1), (-1, -1), 7),
+        ('BOTTOMPADDING', (0, 1), (-1, -1), 7),
+        *[('BACKGROUND', (0, i), (-1, i), COLORS['bg_light'])
+          for i in range(1, len(data), 2)],
+        ('LINEBELOW', (0, 0), (-1, 0), 1.5, COLORS['secondary']),
+        ('LINEBELOW', (0, 1), (-1, -2), 0.5, COLORS['border']),
+        ('LINEBELOW', (0, -1), (-1, -1), 1, COLORS['secondary']),
+        ('ALIGN', (0, 0), (-1, -1), 'LEFT'),
+        ('VALIGN', (0, 0), (-1, -1), 'MIDDLE'),
+        ('LEFTPADDING', (0, 0), (-1, -1), 10),
+        ('RIGHTPADDING', (0, 0), (-1, -1), 10),
+    ]))
+    story.append(t)
+    story.append(Spacer(1, 12))
+
+
+def header_footer(canvas_obj, doc):
+    canvas_obj.saveState()
+    y_h = PAGE_H - 1.5 * cm
+    canvas_obj.setStrokeColor(COLORS['secondary'])
+    canvas_obj.setLineWidth(1.5)
+    canvas_obj.line(M, y_h, PAGE_W - M, y_h)
+    canvas_obj.setFont(FONT, 8)
+    canvas_obj.setFillColor(COLORS['text_light'])
+    canvas_obj.drawString(M, y_h + 4, doc.title or '')
+
+    y_f = 1.2 * cm
+    canvas_obj.setStrokeColor(COLORS['border'])
+    canvas_obj.setLineWidth(0.5)
+    canvas_obj.line(M, y_f + 8, PAGE_W - M, y_f + 8)
+    canvas_obj.drawCentredString(PAGE_W / 2, y_f, f"Page {doc.page}")
+    canvas_obj.restoreState()
+
+
+# ── Main ───────────────────────────────────────────────────────
+
+def main():
+    parser = argparse.ArgumentParser(description='Generate professional PDF report')
+    parser.add_argument('--title', default='Sample Report')
+    parser.add_argument('--subtitle', default='A Professional Document')
+    parser.add_argument('--output', default='report.pdf')
     args = parser.parse_args()
-    create_report(args.input, args.output, args.title)
+
+    doc = SimpleDocTemplate(
+        args.output, pagesize=A4,
+        leftMargin=M, rightMargin=M, topMargin=M, bottomMargin=M,
+        title=args.title, author='BluMa',
+    )
+
+    story = []
+
+    cover(story, args.title, args.subtitle, "Generated by BluMa")
+
+    toc(story, [
+        {'num': 1, 'title': 'Introduction', 'level': 1, 'page': 3},
+        {'num': 2, 'title': 'Key Findings', 'level': 1, 'page': 4},
+        {'num': 3, 'title': 'Conclusion', 'level': 1, 'page': 5},
+    ])
+
+    section(story, 1, "Introduction")
+    story.append(Paragraph(
+        "This document demonstrates the professional PDF generation capabilities "
+        "of BluMa. Every element — from typography to color palette — follows a "
+        "consistent design system that ensures readability and visual appeal.",
+        S['body'],
+    ))
+    story.append(Paragraph(
+        "The design system uses a navy and steel blue palette with warm orange "
+        "accents, Helvetica typography with a clear hierarchy, and generous "
+        "whitespace for a clean, modern look.",
+        S['body'],
+    ))
+
+    callout(story, "Key Insight",
+            "Professional documents communicate credibility before the reader "
+            "processes a single word. Design is the first impression.")
+
+    section(story, 2, "Key Findings")
+    story.append(Paragraph("Analysis results are summarized in the table below:", S['body']))
+    pro_table(story,
+              ['Metric', 'Q1 2026', 'Q2 2026', 'Change'],
+              [
+                  ['Revenue', '$1.2M', '$1.5M', '+25%'],
+                  ['Active Users', '45,000', '58,000', '+29%'],
+                  ['Retention', '82%', '87%', '+5pp'],
+                  ['NPS Score', '42', '56', '+14'],
+              ])
+    story.append(Paragraph(
+        "All metrics show significant improvement quarter-over-quarter, "
+        "driven primarily by the new onboarding flow and retention campaigns.",
+        S['body'],
+    ))
+
+    story.append(Paragraph("Key highlights:", S['body']))
+    for item in [
+        "Revenue growth exceeded targets by 10 percentage points",
+        "User retention improved across all cohorts",
+        "NPS score moved from 'good' to 'excellent' territory",
+    ]:
+        story.append(Paragraph(f"•  {item}", S['bullet']))
+
+    callout(story, "Note", "Growth rates are compared to the same period in the "
+            "prior fiscal year, adjusted for seasonality.", box_type='warning')
+
+    section(story, 3, "Conclusion")
+    story.append(Paragraph(
+        "The data confirms that the strategic initiatives launched in Q4 2025 "
+        "are delivering measurable results. We recommend continuing the current "
+        "trajectory while monitoring customer acquisition costs closely.",
+        S['body'],
+    ))
+
+    doc.build(story, onFirstPage=lambda c, d: None, onLaterPages=header_footer)
+    print(f"Report generated: {args.output}")
+
+
+if __name__ == '__main__':
+    main()

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nomad-e/bluma-cli",
-	"version": "0.1.22",
+	"version": "0.1.23",
 	"description": "BluMa independent agent for automation and advanced software engineering.",
 	"author": "Alex Fonseca",
 	"license": "Apache-2.0",