@nomad-e/bluma-cli 0.8.0 → 0.9.0

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

@@ -1,12 +1,11 @@
 ---
 name: pdf
 description: >
-  Use for any PDF task. For **new business/executive reports**, prefer
-  `create_report.py --from-json`: invest effort in **rich, well-structured JSON**
-  (clear sections, tight copy, sparse callouts, scannable tables) — the template
-  already supplies a **modern, restrained** layout; shallow JSON wastes that
-  design. Ad-hoc ReportLab snippets produce amateur PDFs. Also: extract/merge/
-  OCR/forms. Triggers: .pdf, relatório, report, generate document, merge PDF.
+  Use for any PDF task. For reports to mixed audiences (technical + lay readers),
+  set audience "mixed" and use plain_language + technical_note callouts per section.
+  For new reports prefer create_report.py --from-json with rich JSON (see
+  Comunicação técnico-científica in SKILL). Ad-hoc ReportLab = amateur PDFs.
+  Also extract/merge/OCR/forms. Triggers: .pdf, relatório, report, documento técnico.
 license: Proprietary. LICENSE.txt has complete terms
 ---
 
@@ -33,14 +32,28 @@ the user will share externally.
 
 **Preferred (deliverable quality locked in):**
 
-1. Build a UTF-8 JSON file with `title`, optional `subtitle` / `author`, and
+1. Read **references/DOCUMENT_TYPES.md** and set **`document_type`** (and
+   **`letterhead`** when the user wants papel timbrado / cabeçalho corporativo).
+2. Build a UTF-8 JSON file with `title`, optional `subtitle` / `author`, and
    `sections[]` (`num`, `title`, `blocks[]`). Follow the **JSON quality**
    section below — not only the schema (see **Available Scripts** for types).
-2. Run: `python /absolute/path/to/scripts/create_report.py --from-json
+3. Run: `python /absolute/path/to/scripts/create_report.py --from-json
    your.json --output .bluma/artifacts/your.pdf` (or the path in `artifacts_dir` from `task_boundary`)
-3. Attach that **absolute** path as the deliverable. Do **not** paste huge
+4. Attach that **absolute** path as the deliverable. Do **not** paste huge
    ReportLab source into the chat unless the user explicitly wants code.
 
+### Pick the layout — do not use one template for everything
+
+| User asks for | `document_type` | Notes |
+|---------------|-----------------|-------|
+| Relatório executivo, board, entrega formal | `executive_report` | Capa + sumário; quebras só em capítulos densos |
+| Inventário hardware, specs, sistema | `technical` | Fluxo contínuo; tabelas com texto resumido (não IPv6 novel) |
+| Carta, proposta, documento com marca | `letterhead` | Preencher `letterhead.organization`, morada, `logo_path` opcional |
+| Nota curta | `memo` | Sem sumário |
+| Artigo técnico, MCP, whitepaper | `article` | Sem capítulos numerados excessivos |
+
+Override any preset with top-level `layout: { "include_toc": false, "page_break_per_section": false }`.
+
 **Acceptable alternative:** copy `create_report.py` and edit only data / story
 assembly — keep the same colors, margins, `cover_story`, `section`, `pro_table`,
 `callout`, and `onFirstPage` / `onLaterPages` callbacks.
@@ -50,6 +63,67 @@ with no cover; tables without a styled header row; margins under 2cm; emoji in
 corporate PDFs (font/rendering inconsistency); “nota rodapé” as raw
 `canvas.drawString` for body paragraphs instead of `Paragraph` styles.
 
+## Comunicação técnico-científica — público misto (técnico + leigo)
+
+Use when the deliverable is a **technical, scientific, or enterprise report** read by
+both specialists and non-specialists (management, clients, audit, mixed teams).
+
+Set in JSON: `"audience": "mixed"` (alternatives: `"technical"` = só especialistas;
+`"general"` = priorizar clareza; default implícito em relatórios empresariais:
+**`mixed`** quando o pedido não especificar).
+
+### Princípios (obrigatório em `audience: "mixed"`)
+
+1. **Integridade dos dados** — números, unidades, nomes de sistemas e conclusões
+   factuais **não são simplificados até ficarem errados**. A precisão vem nas
+   tabelas e na nota técnica; a clareza vem no resumo em linguagem simples.
+2. **Dupla camada por secção** (ritmo recomendado):
+   - 1× **`callout`** com `"variant": "plain_language"` — 2–4 frases: o que isto
+     significa para quem não é da área (sem jargão, sem siglas sem explicar).
+   - **`paragraph`** ou **`table`** com o detalhe técnico (dados completos mas
+     **resumidos** em células — não dumps de log).
+   - Opcional: **`callout`** `"variant": "technical_note"` para limitações,
+     método, ou definição de um termo (1–3 frases).
+3. **Linguagem** — frases curtas; definir siglas na primeira ocorrência
+   (“MCP (Model Context Protocol)”); evitar tom marketing; evitar humor.
+4. **Tabelas** — cabeçalhos claros; na coluna de valor, preferir texto legível
+   (“Ubuntu 24.04 LTS”) em vez de strings brutas; mover detalhe excessivo para nota
+   ou parágrafo seguinte.
+5. **Não patronizar** — o bloco `plain_language` explica *significado*, não
+   repete a tabela palavra por palavra.
+
+### Exemplo de blocos numa secção (`audience: "mixed"`)
+
+```json
+{
+  "num": 2,
+  "title": "Sistema operativo",
+  "blocks": [
+    {
+      "type": "callout",
+      "variant": "plain_language",
+      "title": "O essencial",
+      "text": "O computador corre Ubuntu 24.04, uma versão estável e suportada, em arquitetura de 64 bits. Está ligado há cerca de 10 horas desde o último reinício."
+    },
+  {
+      "type": "table",
+      "headers": ["Propriedade", "Valor"],
+      "rows": [
+        ["SO", "Ubuntu 24.04.3 LTS"],
+        ["Kernel", "6.17.x"],
+        ["Arquitetura", "x64"],
+        ["Uptime", "~10 h (36 736 s)"]
+      ]
+    }
+  ]
+}
+```
+
+### Quando NÃO usar `mixed`
+
+- Relatório só para engenharia/DevOps interno → `"audience": "technical"`.
+- FAQ ou carta comercial → `memo` / `letterhead`, linguagem já simples.
+
 ## JSON quality — make the PDF look “designed”, not “filled in”
 
 The `--from-json` pipeline already applies a **clean, modern, understated**
@@ -106,22 +180,31 @@ When you author JSON, treat it like briefing a human designer:
 - Omit `col_widths` unless you need to weight columns; the generator normalises
   widths.
 
-### `callout` (`variant`: `info` | `warning`)
+### `callout` (`variant`: `info` | `warning` | `plain_language` | `technical_note`)
 
 - **Info**: synthesis, definition, or “how to read this document”.
 - **Warning**: real risk, compliance, or “requires action” — not routine stats.
+- **plain_language**: mandatory in `audience: "mixed"` — explains meaning for
+  non-specialists (see section above).
+- **technical_note**: precision, caveats, method, or definition — for specialists.
 - **Title**: 2–5 words; **text**: 1–3 sentences. **Never** stack two callouts in
-  a row.
+  a row unless the second is `technical_note` after `plain_language`.
 
 ### `h2`
 
 - Use sparingly inside long sections; keeps hierarchy without visual noise.
 
+### `document_type`, `letterhead`, `layout`
+
+- **`document_type`**: `executive_report` | `technical` | `letterhead` | `memo` | `article` (see DOCUMENT_TYPES.md).
+- **`letterhead`**: `{ organization, department?, tagline?, address_lines[], contact?, logo_path? }` — obrigatório para timbrado.
+- **`layout`**: `{ include_toc?, page_break_per_section?, cover_style?: corporate|minimal|letterhead }`.
+
 ### `page_break_per_section`
 
-- Default **`true`** for multi-topic reports (calm, one chapter per page).
-- Set **`false`** only for a short, single-thread document where breaks would
-  feel wasteful.
+- Default **`false`** in the generator (evita páginas quase vazias).
+- `executive_report` preset uses **`true`** only before **dense** sections (tabelas grandes ou muito texto).
+- Inventários técnicos: manter **`false`**.
 
 ### Restraint checklist (before you run the script)
 
@@ -624,9 +707,9 @@ for i, img in enumerate(images):
 - **create_report.py** — default: demo PDF; **production:** `--from-json FILE`
   - Before writing JSON, follow **“JSON quality”** (this file) so content matches
     the clean template — schema alone is not enough.
-  - Schema (top-level keys): `title` (str), `subtitle` (optional str),
-    `author` (optional str), `page_break_per_section` (optional bool, default
-    `true` — cada capítulo começa em página nova), `sections` (array).
+  - Schema (top-level keys): `title`, `subtitle?`, `author?`, `audience?`
+    (`technical` | `mixed` | `general`), `document_type?`, `letterhead?`,
+    `layout?`, `page_break_per_section?` (override do preset), `sections[]`.
   - Each section: `num` (int), `title` (str), `blocks` (array).
   - Each block: `type` is one of:
     - `paragraph` — `{ "type": "paragraph", "text": "..." }` (use `\n` for line breaks)

package/dist/config/skills/pdf/references/DOCUMENT_TYPES.md

@@ -0,0 +1,59 @@
+# PDF document types — choose before writing JSON
+
+Always run `create_report.py --from-json`. Pick **`document_type`** first; do not improvise ReportLab.
+
+| Type | When to use | TOC | Page breaks | Letterhead band |
+|------|-------------|-----|-------------|-----------------|
+| `executive_report` | Relatórios multi-capítulo para gestão (vendas, hardware, auditoria) | yes | yes (secções densas) | no |
+| `technical` | Inventários, specs, dumps estruturados | yes | no (fluxo contínuo) | no |
+| `letterhead` | Cartas, propostas, documentos com marca da empresa | yes | no | yes (cabeçalho em todas as páginas) |
+| `memo` | Notas curtas, 1–2 secções | no | no | no |
+| `article` | Ensaios, MCP, documentação longa sem capítulos executivos | no | no | no |
+
+## Letterhead block (required for `document_type: "letterhead"`)
+
+```json
+{
+  "document_type": "letterhead",
+  "title": "Proposta comercial",
+  "subtitle": "Renovação de licenças 2026",
+  "author": "Departamento Comercial",
+  "letterhead": {
+    "organization": "Empresa Exemplo Lda.",
+    "department": "Comercial",
+    "tagline": "Soluções empresariais",
+    "address_lines": ["Rua das Flores, 10", "1000-001 Lisboa"],
+    "contact": "comercial@exemplo.pt · +351 210 000 000",
+    "logo_path": ".bluma/artifacts/logo.png"
+  },
+  "sections": [ ... ]
+}
+```
+
+`logo_path` is optional; file must exist under the workspace.
+
+## Público misto (técnico + leigo)
+
+```json
+{
+  "document_type": "technical",
+  "audience": "mixed",
+  "title": "Relatório de Hardware e Sistema",
+  "subtitle": "Inventário com leitura acessível",
+  ...
+}
+```
+
+Em cada secção: primeiro `callout` `plain_language`, depois tabela/parágrafo técnico.
+Ver secção **Comunicação técnico-científica** em SKILL.md.
+
+## Hardware / system inventory → use `technical`
+
+- `page_break_per_section`: false (default for technical)
+- 4–6 sections with tables; paraphrase long IPv6/MAC in cells
+- Do not use `executive_report` for raw machine dumps — it wastes pages
+
+## MCP / whitepaper → use `article`
+
+- No cover theatre; optional short cover via `cover_style: "minimal"` in `layout`
+- Continuous flow; use `h2` inside sections instead of many numbered chapters

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

@@ -11,10 +11,16 @@ Usage:
 
 JSON schema (UTF-8 file):
 {
+  "document_type": "technical",
   "title": "Relatório",
   "subtitle": "Subtítulo opcional",
   "author": "Equipe / Cliente (opcional)",
-  "page_break_per_section": true,
+  "letterhead": {
+    "organization": "Empresa",
+    "address_lines": ["Morada"],
+    "logo_path": ".bluma/artifacts/logo.png"
+  },
+  "layout": { "include_toc": true, "page_break_per_section": false },
   "sections": [
     {
       "num": 1,
@@ -29,7 +35,8 @@ JSON schema (UTF-8 file):
   ]
 }
 
-variant for callout: "info" | "warning"
+variant for callout: "info" | "warning" | "plain_language" | "technical_note"
+Top-level audience: "technical" | "mixed" | "general"
 Text in JSON is escaped for XML/HTML safety; use plain text, not ReportLab tags.
 
 Editorial guidance for agents (structure, copy, restraint): see pdf/SKILL.md
@@ -200,9 +207,112 @@ S = {
         leading=18,
         textColor=COLORS["primary"],
     ),
+    "cell": ParagraphStyle(
+        "Cell",
+        fontName=FONT,
+        fontSize=8.5,
+        leading=11,
+        textColor=COLORS["text"],
+        alignment=TA_JUSTIFY,
+    ),
+    "letterhead_org": ParagraphStyle(
+        "LHOrg",
+        fontName=FONT_B,
+        fontSize=11,
+        leading=14,
+        textColor=COLORS["primary"],
+        alignment=TA_CENTER,
+        spaceAfter=2,
+    ),
+    "letterhead_meta": ParagraphStyle(
+        "LHMeta",
+        fontName=FONT,
+        fontSize=8.5,
+        leading=11,
+        textColor=COLORS["muted"],
+        alignment=TA_CENTER,
+        spaceAfter=2,
+    ),
 }
 
 
+def _resolve_layout(data: dict[str, Any]) -> dict[str, Any]:
+    """Merge document_type presets with explicit layout / letterhead overrides."""
+    doc_type = str(data.get("document_type") or "executive_report").strip().lower()
+    layout = dict(data.get("layout") or {})
+    letterhead = dict(data.get("letterhead") or {})
+
+    presets: dict[str, dict[str, Any]] = {
+        "executive_report": {
+            "include_toc": True,
+            "page_break_per_section": True,
+            "cover_style": "corporate",
+            "use_letterhead_band": False,
+        },
+        "technical": {
+            "include_toc": True,
+            "page_break_per_section": False,
+            "cover_style": "minimal",
+            "use_letterhead_band": False,
+        },
+        "letterhead": {
+            "include_toc": True,
+            "page_break_per_section": False,
+            "cover_style": "letterhead",
+            "use_letterhead_band": True,
+        },
+        "memo": {
+            "include_toc": False,
+            "page_break_per_section": False,
+            "cover_style": "minimal",
+            "use_letterhead_band": False,
+        },
+        "article": {
+            "include_toc": False,
+            "page_break_per_section": False,
+            "cover_style": "minimal",
+            "use_letterhead_band": False,
+        },
+    }
+    base = dict(presets.get(doc_type, presets["executive_report"]))
+    for key in ("include_toc", "page_break_per_section", "cover_style", "use_letterhead_band"):
+        if key in layout:
+            base[key] = layout[key]
+    audience = str(data.get("audience") or layout.get("audience") or "technical").strip().lower()
+    if audience not in ("technical", "mixed", "general"):
+        audience = "mixed" if audience in ("lay", "public", "mixed_audience") else "technical"
+    base["document_type"] = doc_type
+    base["letterhead"] = letterhead
+    base["audience"] = audience
+    return base
+
+
+def _section_char_count(sec: dict[str, Any]) -> int:
+    total = len(str(sec.get("title") or ""))
+    for block in sec.get("blocks") or []:
+        if not isinstance(block, dict):
+            continue
+        btype = block.get("type")
+        if btype == "paragraph":
+            total += len(str(block.get("text") or ""))
+        elif btype == "bullets":
+            total += sum(len(str(x)) for x in (block.get("items") or []))
+        elif btype == "table":
+            total += 120 * len(block.get("rows") or [])
+        elif btype == "callout":
+            total += len(str(block.get("text") or ""))
+    return total
+
+
+def _should_page_break_before_section(
+    sec: dict[str, Any], *, page_per_section: bool, index: int
+) -> bool:
+    if index == 0 or not page_per_section:
+        return False
+    # Evita páginas quase vazias: só quebra se a secção anterior tinha conteúdo denso
+    return _section_char_count(sec) >= 280 or len(sec.get("blocks") or []) >= 3
+
+
 def _ptext(s: str) -> str:
     """Plain text → safe Paragraph markup (preserva quebras como <br/>)."""
     if s is None:
@@ -271,8 +381,52 @@ def _normalize_col_widths(
 # ── Cover (story + canvas) ─────────────────────────────────────
 
 
-def cover_story(story: list, title: str, subtitle: str | None, author: str | None) -> None:
-    story.append(Spacer(1, 5.5 * cm))
+def _letterhead_block_story(story: list, letterhead: dict[str, Any]) -> None:
+    org = str(letterhead.get("organization") or "").strip()
+    if org:
+        story.append(Paragraph(_ptext(org), S["letterhead_org"]))
+    for key in ("department", "tagline"):
+        line = str(letterhead.get(key) or "").strip()
+        if line:
+            story.append(Paragraph(_ptext(line), S["letterhead_meta"]))
+    for line in letterhead.get("address_lines") or []:
+        if str(line).strip():
+            story.append(Paragraph(_ptext(str(line)), S["letterhead_meta"]))
+    contact = str(letterhead.get("contact") or "").strip()
+    if contact:
+        story.append(Paragraph(_ptext(contact), S["letterhead_meta"]))
+    logo_path = letterhead.get("logo_path")
+    if logo_path and Path(str(logo_path)).is_file():
+        try:
+            from reportlab.platypus import Image
+
+            story.append(Spacer(1, 0.3 * cm))
+            img = Image(str(logo_path), width=3.2 * cm, height=1.2 * cm, kind="proportional")
+            img.hAlign = "CENTER"
+            story.append(img)
+        except Exception:
+            pass
+    story.append(Spacer(1, 0.6 * cm))
+
+
+def cover_story(
+    story: list,
+    title: str,
+    subtitle: str | None,
+    author: str | None,
+    *,
+    cover_style: str = "corporate",
+    letterhead: dict[str, Any] | None = None,
+) -> None:
+    lh = letterhead or {}
+    if cover_style == "letterhead" and lh:
+        story.append(Spacer(1, 1.2 * cm))
+        _letterhead_block_story(story, lh)
+        story.append(Spacer(1, 2.2 * cm))
+    elif cover_style == "minimal":
+        story.append(Spacer(1, 4.5 * cm))
+    else:
+        story.append(Spacer(1, 5.5 * cm))
     story.append(_cover_title_paragraph(title))
     if subtitle:
         story.append(Paragraph(_ptext(subtitle), S["subtitle"]))
@@ -308,6 +462,7 @@ def draw_cover_canvas(canvas_obj, doc) -> None:
 
 
 def toc(story: list, sections: list[dict[str, Any]]) -> None:
+    """Sumário limpo — sem linhas horizontais a atravessar a página inteira."""
     story.append(Paragraph("Sumário", S["h1"]))
     story.append(Spacer(1, 0.35 * cm))
     for sec in sections:
@@ -320,22 +475,16 @@ def toc(story: list, sections: list[dict[str, Any]]) -> None:
         else:
             left = f"{indent}{title}"
         row = Table(
-            [
-                [
-                    Paragraph(left, style),
-                    Paragraph(str(sec.get("page", "")), style),
-                ]
-            ],
-            colWidths=[CW - 36, 36],
+            [[Paragraph(left, style)]],
+            colWidths=[CW],
         )
         row.setStyle(
             TableStyle(
                 [
-                    ("ALIGN", (1, 0), (1, 0), "RIGHT"),
                     ("VALIGN", (0, 0), (-1, -1), "MIDDLE"),
-                    ("LINEBELOW", (0, 0), (-1, -1), 0.35, COLORS["border"]),
-                    ("TOPPADDING", (0, 0), (-1, -1), 5),
-                    ("BOTTOMPADDING", (0, 0), (-1, -1), 5),
+                    ("TOPPADDING", (0, 0), (-1, -1), 3),
+                    ("BOTTOMPADDING", (0, 0), (-1, -1), 3),
+                    ("LEFTPADDING", (0, 0), (-1, -1), 0),
                 ]
             )
         )
@@ -382,10 +531,24 @@ def section(story: list, num: int | str, title: str) -> None:
 
 
 def callout(story: list, title: str, text: str, box_type: str = "info") -> None:
-    box_type = box_type if box_type in ("info", "warning") else "info"
-    bg = COLORS["bg_accent"] if box_type == "info" else COLORS["bg_light"]
-    border = COLORS["secondary"] if box_type == "info" else COLORS["accent"]
-    label = "Informação" if box_type == "info" else "Atenção"
+    allowed = ("info", "warning", "plain_language", "technical_note")
+    box_type = box_type if box_type in allowed else "info"
+    if box_type == "plain_language":
+        bg = COLORS["bg_light"]
+        border = COLORS["secondary"]
+        label = "Em linguagem simples"
+    elif box_type == "technical_note":
+        bg = HexColor("#F8FAFC")
+        border = COLORS["primary"]
+        label = "Nota técnica"
+    elif box_type == "warning":
+        bg = COLORS["bg_light"]
+        border = COLORS["accent"]
+        label = "Atenção"
+    else:
+        bg = COLORS["bg_accent"]
+        border = COLORS["secondary"]
+        label = "Informação"
     content = [
         [
             Paragraph(
@@ -430,14 +593,30 @@ def callout(story: list, title: str, text: str, box_type: str = "info") -> None:
     story.append(Spacer(1, 6))
 
 
+def _cell_paragraph(text: str, *, header: bool = False) -> Paragraph:
+    raw = str(text or "")
+    if len(raw) > 120 or "\n" in raw:
+        sty = ParagraphStyle(
+            "CellLong",
+            fontName=FONT_B if header else FONT,
+            fontSize=9 if header else 8.5,
+            leading=11 if header else 10,
+            textColor=COLORS["white"] if header else COLORS["text"],
+        )
+        return Paragraph(_ptext(raw), sty)
+    return Paragraph(_ptext(raw), S["cell"] if not header else ParagraphStyle(
+        "CellH", parent=S["cell"], fontName=FONT_B, textColor=COLORS["white"], fontSize=9
+    ))
+
+
 def pro_table(
     story: list,
     headers: list[str],
     rows: list[list[str]],
     col_widths: list[float] | None = None,
 ) -> None:
-    h_esc = [_ptext(h) for h in headers]
-    data = [h_esc] + [[_ptext(c) for c in row] for row in rows]
+    data = [[_cell_paragraph(h, header=True) for h in headers]]
+    data += [[_cell_paragraph(c) for c in row] for row in rows]
     col_widths = _normalize_col_widths(col_widths, len(headers))
     t = Table(data, colWidths=col_widths, repeatRows=1)
     t.setStyle(
@@ -473,9 +652,31 @@ def pro_table(
     story.append(Spacer(1, 10))
 
 
-def header_footer(canvas_obj, doc) -> None:
+def _draw_letterhead_band(canvas_obj, letterhead: dict[str, Any]) -> None:
+    org = str(letterhead.get("organization") or "").strip()[:80]
+    if not org:
+        return
     canvas_obj.saveState()
-    y_h = PAGE_H - 1.35 * cm
+    y = PAGE_H - 1.15 * cm
+    canvas_obj.setFont(FONT_B, 9)
+    canvas_obj.setFillColor(COLORS["primary"])
+    canvas_obj.drawString(M, y, org)
+    dept = str(letterhead.get("department") or "").strip()[:60]
+    if dept:
+        canvas_obj.setFont(FONT, 7.5)
+        canvas_obj.setFillColor(COLORS["muted"])
+        canvas_obj.drawRightString(PAGE_W - M, y, dept)
+    canvas_obj.setStrokeColor(COLORS["border"])
+    canvas_obj.setLineWidth(0.5)
+    canvas_obj.line(M, y - 5, PAGE_W - M, y - 5)
+    canvas_obj.restoreState()
+
+
+def header_footer(canvas_obj, doc, *, letterhead: dict[str, Any] | None = None) -> None:
+    if letterhead and getattr(doc, "_bluma_letterhead", False):
+        _draw_letterhead_band(canvas_obj, letterhead)
+    canvas_obj.saveState()
+    y_h = PAGE_H - (1.75 * cm if getattr(doc, "_bluma_letterhead", False) else 1.35 * cm)
     canvas_obj.setStrokeColor(COLORS["border"])
     canvas_obj.setLineWidth(0.6)
     canvas_obj.line(M, y_h, PAGE_W - M, y_h)
@@ -499,7 +700,8 @@ def on_first_page(canvas_obj, doc) -> None:
 
 
 def on_later_pages(canvas_obj, doc) -> None:
-    header_footer(canvas_obj, doc)
+    lh = getattr(doc, "_bluma_letterhead_data", None) or {}
+    header_footer(canvas_obj, doc, letterhead=lh)
 
 
 # ── JSON-driven build ──────────────────────────────────────────
@@ -509,8 +711,12 @@ def build_from_json(data: dict[str, Any], output_path: str) -> None:
     title = data.get("title") or "Relatório"
     subtitle = data.get("subtitle")
     author = data.get("author")
-    # True = cada capítulo em página nova (relatório executivo); False = fluxo contínuo
-    page_per_section = data.get("page_break_per_section", True)
+    layout = _resolve_layout(data)
+    letterhead = layout.get("letterhead") or {}
+
+    page_per_section = layout.get("page_break_per_section", False)
+    if "page_break_per_section" in data and data["page_break_per_section"] is not None:
+        page_per_section = bool(data["page_break_per_section"])
     if not isinstance(page_per_section, bool):
         page_per_section = bool(page_per_section)
 
@@ -518,37 +724,64 @@ def build_from_json(data: dict[str, Any], output_path: str) -> None:
     if not isinstance(sections, list):
         raise ValueError('"sections" must be a list')
 
+    include_toc = layout.get("include_toc", True)
+    if len(sections) < 2:
+        include_toc = False
+
     toc_rows: list[dict[str, Any]] = []
     for i, sec in enumerate(sections, start=1):
         if not isinstance(sec, dict):
             continue
         num = sec.get("num", i)
-        toc_rows.append({"num": num, "title": sec.get("title", f"Seção {i}"), "level": 1, "page": ""})
+        toc_rows.append({"num": num, "title": sec.get("title", f"Seção {i}"), "level": 1})
 
     doc = SimpleDocTemplate(
         output_path,
         pagesize=A4,
         leftMargin=M,
         rightMargin=M,
-        topMargin=M,
+        topMargin=M + (0.4 * cm if layout.get("use_letterhead_band") else 0),
         bottomMargin=M,
         title=title,
-        author="BluMa",
+        author=str(author or letterhead.get("organization") or "BluMa"),
     )
+    doc._bluma_letterhead = bool(layout.get("use_letterhead_band") and letterhead)  # type: ignore[attr-defined]
+    doc._bluma_letterhead_data = letterhead  # type: ignore[attr-defined]
 
     story: list = []
-    cover_story(story, title, subtitle, author)
-    toc(story, toc_rows)
+    cover_story(
+        story,
+        title,
+        subtitle,
+        author,
+        cover_style=str(layout.get("cover_style") or "corporate"),
+        letterhead=letterhead,
+    )
+    if include_toc and toc_rows:
+        toc(story, toc_rows)
 
-    first_section = True
-    for sec in sections:
+    audience = str(layout.get("audience") or "technical")
+    if audience == "mixed":
+        story.append(
+            Paragraph(
+                _ptext(
+                    "Este documento apresenta dados com rigor técnico e, em cada secção, "
+                    "resumos em linguagem acessível para leitores sem formação especializada na área."
+                ),
+                S["body"],
+            )
+        )
+        story.append(Spacer(1, 10))
+
+    for idx, sec in enumerate(sections):
         if not isinstance(sec, dict):
             continue
         num = sec.get("num", 0)
         sec_title = sec.get("title", "")
-        if page_per_section and not first_section:
+        if _should_page_break_before_section(
+            sec, page_per_section=page_per_section, index=idx
+        ):
             story.append(PageBreak())
-        first_section = False
 
         blocks = [b for b in (sec.get("blocks") or []) if isinstance(b, dict)]
         section(story, num, sec_title)

package/dist/main.js

@@ -24473,6 +24473,7 @@ Timeouts mean the orchestrator should raise the limit \u2014 not that the sandbo
 - Never create a top-level \`./artifacts/\` folder \u2014 it is auto-remapped to \`.bluma/artifacts/\`.
 - **Never invent URLs** or paths outside \`.bluma/artifacts/\` in \`attachments[]\`.
 - Live deploy URLs (if any) may appear in \`content\` when returned by \`factorai.sh.deploy_app\`; downloadable files still go through \`attachments[]\`.
+- **PDFs for mixed audiences:** load skill \`pdf\`; use \`create_report.py --from-json\` with \`audience: "mixed"\` \u2014 rigor in tables, \`plain_language\` callouts per section for non-specialists.
 - Remove temp files and generator scripts before finishing.
 </sandbox_context>
 `;

package/package.json

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