freeharness 0.4.1

package/canonical/skills/report-formatting/scripts/pptx/theme_claro_pptx.py

@@ -0,0 +1,473 @@
+"""Claro pptx theme: palette, typography, layout helpers (python-pptx) and
+template-edit helpers (lxml). Default theme for report-formatting .pptx output.
+Import: `import theme_claro_pptx as T`. Reusable across status reports.
+"""
+import os
+from pptx.util import Inches, Pt, Emu
+from pptx.dml.color import RGBColor
+from pptx.enum.shapes import MSO_SHAPE
+from pptx.enum.text import PP_ALIGN, MSO_ANCHOR
+from lxml import etree
+import copy as _copy
+
+FONT = "Calibri"
+
+# Claro logo asset (red orb wordmark, transparent PNG). Resolved relative to this
+# file so it works wherever the skill is emitted.
+LOGO_PATH = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "assets", "claro-logo.png")
+
+# Claro institutional palette
+CLARO_RED = RGBColor(0xE2, 0x00, 0x0F)
+CLARO_RED_DARK = RGBColor(0xB8, 0x00, 0x0D)
+DARK_GRAY = RGBColor(0x33, 0x33, 0x33)
+MID_GRAY = RGBColor(0x66, 0x66, 0x66)
+LIGHT_GRAY = RGBColor(0xE8, 0xE8, 0xE8)
+VERY_LIGHT_GRAY = RGBColor(0xF5, 0xF5, 0xF5)
+WHITE = RGBColor(0xFF, 0xFF, 0xFF)
+
+# Status colors (heatmap, ROAM, badges)
+STATUS_DONE = RGBColor(0x2E, 0x7D, 0x32)
+STATUS_INPROGRESS = RGBColor(0xF9, 0xA8, 0x25)
+STATUS_PENDING = RGBColor(0xE6, 0x7E, 0x22)
+STATUS_BACKLOG = RGBColor(0x95, 0xA5, 0xA6)
+STATUS_RISK = RGBColor(0xC0, 0x39, 0x2B)
+
+# Timeline track / category colors
+CAT_COLOR = {
+    "Backlog": RGBColor(0xE6, 0x7E, 0x22),
+    "WhisperX": RGBColor(0x8E, 0x24, 0xAA),
+    "Pipeline": RGBColor(0x1E, 0x88, 0xE5),
+    "Data Core": RGBColor(0x00, 0x89, 0x7B),
+    "Infraestrutura": RGBColor(0x5D, 0x6D, 0x7E),
+    "Documentação": RGBColor(0xB8, 0x00, 0x0D),
+    "Análises": RGBColor(0x5E, 0x35, 0xB1),
+}
+
+# Heatmap status config: key -> (label, fill, text_color, icon)
+STATUS_CFG = {
+    "done": ("Concluído", STATUS_DONE, WHITE, "✓"),
+    "inprogress": ("Em Andamento", STATUS_INPROGRESS, WHITE, "▶"),
+    "pending": ("Pendente", STATUS_PENDING, WHITE, "○"),
+    "backlog": ("Backlog", STATUS_BACKLOG, WHITE, "–"),
+}
+
+
+def clear_slide_shapes(slide):
+    """Remove all editable shapes from the slide, keeping layout and master.
+
+    Mutates the slide in place, leaving it blank for a rebuild.
+
+    Args:
+        slide: The python-pptx slide to strip.
+    """
+    spTree = slide.shapes._spTree
+    for sp in list(spTree):
+        tag = etree.QName(sp).localname
+        if tag in ("sp", "pic", "graphicFrame", "cxnSp", "grpSp"):
+            spTree.remove(sp)
+
+
+def add_text(slide, x, y, w, h, text, *, size=11, bold=False, color=DARK_GRAY,
+             align=PP_ALIGN.LEFT, anchor=MSO_ANCHOR.TOP, italic=False,
+             font=FONT, fill=None, line=None):
+    """Add a formatted text box to the slide; supports fill, border, alignment.
+
+    Args:
+        slide: Target slide.
+        x, y, w, h: Text-box position and size in EMU.
+        text: The text content.
+        size: Font size in points.
+        bold: Whether the text is bold.
+        color: Font color.
+        align: Horizontal paragraph alignment.
+        anchor: Vertical anchor of the text frame.
+        italic: Whether the text is italic.
+        font: Font name.
+        fill: Background fill color, or None for no fill.
+        line: Border color, or None for no border.
+
+    Returns:
+        The created textbox shape.
+    """
+    tb = slide.shapes.add_textbox(x, y, w, h)
+    tf = tb.text_frame
+    tf.margin_left = Emu(45720)
+    tf.margin_right = Emu(45720)
+    tf.margin_top = Emu(22860)
+    tf.margin_bottom = Emu(22860)
+    tf.word_wrap = True
+    tf.vertical_anchor = anchor
+    p = tf.paragraphs[0]
+    p.alignment = align
+    run = p.add_run()
+    run.text = text
+    run.font.name = font
+    run.font.size = Pt(size)
+    run.font.bold = bold
+    run.font.italic = italic
+    run.font.color.rgb = color
+    if fill is not None:
+        tb.fill.solid()
+        tb.fill.fore_color.rgb = fill
+    else:
+        tb.fill.background()
+    if line is not None:
+        tb.line.color.rgb = line
+        tb.line.width = Pt(0.5)
+    else:
+        tb.line.fill.background()
+    return tb
+
+
+def add_rect(slide, x, y, w, h, fill, *, line=None, line_w=None, corner=False):
+    """Add a filled rectangle to the slide.
+
+    Args:
+        slide: Target slide.
+        x, y, w, h: Position and size in EMU.
+        fill: Fill color.
+        line: Border color, or None for no border.
+        line_w: Border width; defaults to 0.25pt when a border is set.
+        corner: If True, use a rounded rectangle.
+
+    Returns:
+        The created shape.
+    """
+    st = MSO_SHAPE.ROUNDED_RECTANGLE if corner else MSO_SHAPE.RECTANGLE
+    shape = slide.shapes.add_shape(st, x, y, w, h)
+    shape.fill.solid()
+    shape.fill.fore_color.rgb = fill
+    if line is None:
+        shape.line.fill.background()
+    else:
+        shape.line.color.rgb = line
+        shape.line.width = line_w or Pt(0.25)
+    shape.shadow.inherit = False
+    if shape.has_text_frame:
+        shape.text_frame.text = ""
+    if corner:
+        try:
+            shape.adjustments[0] = 0.15
+        except Exception:
+            pass
+    return shape
+
+
+def add_filled_text(slide, x, y, w, h, text, *, fill, tcolor=WHITE, size=10,
+                    bold=True, align=PP_ALIGN.CENTER, anchor=MSO_ANCHOR.MIDDLE,
+                    corner=False):
+    """Add a filled rectangle with centered text (chips, badges, headers).
+
+    Args:
+        slide: Target slide.
+        x, y, w, h: Position and size in EMU.
+        text: The text content.
+        fill: Fill color.
+        tcolor: Text color.
+        size: Font size in points.
+        bold: Whether the text is bold.
+        align: Horizontal alignment.
+        anchor: Vertical anchor.
+        corner: If True, use a rounded rectangle.
+
+    Returns:
+        The created shape.
+    """
+    st = MSO_SHAPE.ROUNDED_RECTANGLE if corner else MSO_SHAPE.RECTANGLE
+    shape = slide.shapes.add_shape(st, x, y, w, h)
+    shape.fill.solid()
+    shape.fill.fore_color.rgb = fill
+    shape.line.fill.background()
+    shape.shadow.inherit = False
+    if corner:
+        try:
+            shape.adjustments[0] = 0.18
+        except Exception:
+            pass
+    tf = shape.text_frame
+    tf.margin_left = Emu(36000)
+    tf.margin_right = Emu(36000)
+    tf.margin_top = Emu(9000)
+    tf.margin_bottom = Emu(9000)
+    tf.word_wrap = True
+    tf.vertical_anchor = anchor
+    p = tf.paragraphs[0]
+    p.alignment = align
+    run = p.add_run()
+    run.text = text
+    run.font.name = FONT
+    run.font.size = Pt(size)
+    run.font.bold = bold
+    run.font.color.rgb = tcolor
+    return shape
+
+
+def add_logo(slide, *, x=None, y=Inches(0.28), height=Inches(0.5)):
+    """Place the Claro logo on the slide, preserving aspect ratio.
+
+    Default position is the top-right header corner (right-aligned to the
+    0.45in margin).
+
+    Args:
+        slide: Target slide.
+        x: Left offset in EMU, or None to right-align to the margin.
+        y: Top offset in EMU.
+        height: Logo height in EMU (width scales to keep aspect ratio).
+
+    Returns:
+        The picture shape, or None if the logo asset is missing (so callers
+        degrade cleanly).
+    """
+    if not os.path.exists(LOGO_PATH):
+        return None
+    pic = slide.shapes.add_picture(LOGO_PATH, Inches(0), y, height=height)
+    pic.left = x if x is not None else int(Inches(13.333) - Inches(0.45) - pic.width)
+    return pic
+
+
+def add_page_header(slide, title, subtitle=None, logo=True):
+    """Add the Claro header: red accent flag, title, optional subtitle, logo.
+
+    Args:
+        slide: Target slide.
+        title: Header title text.
+        subtitle: Optional italic subtitle.
+        logo: If True, place the logo in the top-right corner.
+    """
+    add_rect(slide, Inches(0.5), Inches(0.35), Inches(0.6), Inches(0.08), CLARO_RED)
+    add_text(slide, Inches(0.45), Inches(0.48), Inches(11.2), Inches(0.55),
+             title, size=23, bold=True, color=DARK_GRAY)
+    if subtitle:
+        add_text(slide, Inches(0.45), Inches(1.0), Inches(11.2), Inches(0.3),
+                 subtitle, size=11, color=MID_GRAY, italic=True)
+    if logo:
+        add_logo(slide)
+
+
+def add_page_footer(slide, page, total=10,
+                    left="Status Report | Pipeline STT - Dados & IA"):
+    """Add the Claro footer: left label and right page number.
+
+    Args:
+        slide: Target slide.
+        page: Current page number.
+        total: Total page count.
+        left: Left-aligned footer label.
+    """
+    add_text(slide, Inches(0.45), Inches(7.15), Inches(7), Inches(0.25),
+             left, size=9, color=MID_GRAY)
+    add_text(slide, Inches(12.2), Inches(7.15), Inches(0.9), Inches(0.25),
+             f"{page} / {total}", size=9, color=MID_GRAY, align=PP_ALIGN.RIGHT)
+
+
+def build_bullet_list(slide, x, y, w, h, items, size=10, color=DARK_GRAY,
+                      bullet_color=CLARO_RED):
+    """Add a bullet list with a red marker on the left.
+
+    Args:
+        slide: Target slide.
+        x, y, w, h: Position and size in EMU.
+        items: Bullet strings, one per line.
+        size: Font size in points.
+        color: Text color.
+        bullet_color: Marker color.
+    """
+    tb = slide.shapes.add_textbox(x, y, w, h)
+    tf = tb.text_frame
+    tf.margin_left = Emu(36000)
+    tf.word_wrap = True
+    for i, item in enumerate(items):
+        p = tf.paragraphs[0] if i == 0 else tf.add_paragraph()
+        r1 = p.add_run()
+        r1.text = "▪  "
+        r1.font.name = FONT
+        r1.font.size = Pt(size)
+        r1.font.bold = True
+        r1.font.color.rgb = bullet_color
+        r2 = p.add_run()
+        r2.text = item
+        r2.font.name = FONT
+        r2.font.size = Pt(size)
+        r2.font.color.rgb = color
+
+
+# ---------------------------------------------------------------------------
+# lxml helpers — edit template slides in place (preserve complex Claro layouts)
+# ---------------------------------------------------------------------------
+NS = {
+    "a": "http://schemas.openxmlformats.org/drawingml/2006/main",
+    "p": "http://schemas.openxmlformats.org/presentationml/2006/main",
+    "r": "http://schemas.openxmlformats.org/officeDocument/2006/relationships",
+}
+A_NS = NS["a"]
+
+
+def get_shape(root, sid):
+    """Find a shape by its cNvPr id.
+
+    Returns:
+        The matching <p:sp> element, or None if not found.
+    """
+    r = root.xpath(f".//p:sp[.//p:cNvPr[@id='{sid}']]", namespaces=NS)
+    return r[0] if r else None
+
+
+def set_pos(shape, x, y):
+    """Set the shape's (x, y) offset in EMU, mutating the xfrm in place.
+
+    A None x leaves the x offset unchanged.
+    """
+    off = shape.find(".//p:spPr/a:xfrm/a:off", NS)
+    if off is not None:
+        if x is not None:
+            off.set("x", str(int(x)))
+        off.set("y", str(int(y)))
+
+
+def get_dims(shape):
+    """Return the shape's (cx, cy) extent in EMU, or (None, None) if absent."""
+    ext = shape.find(".//p:spPr/a:xfrm/a:ext", NS)
+    if ext is None:
+        return None, None
+    return int(ext.get("cx")), int(ext.get("cy"))
+
+
+def set_fill(shape, hex_color):
+    """Set the shape's fill color in place (hex without '#', e.g. '2E7D32')."""
+    fill = shape.find(".//p:spPr/a:solidFill/a:srgbClr", NS)
+    if fill is not None:
+        fill.set("val", hex_color)
+
+
+def set_text(shape, new_text):
+    """Replace all text in a shape, preserving formatting; mutates in place.
+
+    Preserves the first run's rPr and the first paragraph's pPr, so font, size,
+    color, and alignment carry over. Most-used template helper.
+
+    Args:
+        shape: The <p:sp> element to edit.
+        new_text: Replacement text; newlines become separate paragraphs.
+
+    Returns:
+        True if the text was replaced, False if the shape has no txBody.
+    """
+    txBody = shape.find("p:txBody", NS)
+    if txBody is None:
+        return False
+    first_run = txBody.find(".//a:r", NS)
+    tmpl_rPr = None
+    if first_run is not None:
+        rPr = first_run.find("a:rPr", NS)
+        if rPr is not None:
+            tmpl_rPr = etree.tostring(rPr)
+    first_p = txBody.find("a:p", NS)
+    tmpl_pPr = None
+    if first_p is not None:
+        pPr = first_p.find("a:pPr", NS)
+        if pPr is not None:
+            tmpl_pPr = etree.tostring(pPr)
+    for p in txBody.findall("a:p", NS):
+        txBody.remove(p)
+    for line in new_text.split("\n"):
+        p = etree.SubElement(txBody, f"{{{A_NS}}}p")
+        if tmpl_pPr is not None:
+            p.append(etree.fromstring(tmpl_pPr))
+        r = etree.SubElement(p, f"{{{A_NS}}}r")
+        if tmpl_rPr is not None:
+            r.append(etree.fromstring(tmpl_rPr))
+        else:
+            etree.SubElement(r, f"{{{A_NS}}}rPr").set("lang", "pt-BR")
+        t = etree.SubElement(r, f"{{{A_NS}}}t")
+        t.text = line
+    return True
+
+
+def del_shape(root, sid):
+    """Remove a shape by id from the tree (e.g. discard unused markers)."""
+    sh = get_shape(root, sid)
+    if sh is not None:
+        sh.getparent().remove(sh)
+
+
+def clone_shape(root, src_shape, new_id):
+    """Clone a shape and append it to its parent, returning the copy.
+
+    Assigns a new cNvPr id and drops extLst to avoid duplicate GUIDs. Used to
+    add markers to a timeline track.
+
+    Args:
+        root: Document root (unused; kept for API symmetry).
+        src_shape: The shape to clone.
+        new_id: cNvPr id to assign to the clone.
+
+    Returns:
+        The newly appended clone element.
+    """
+    new = _copy.deepcopy(src_shape)
+    cNvPr = new.find(".//p:cNvPr", NS)
+    cNvPr.set("id", str(new_id))
+    cNvPr.set("name", f'{cNvPr.get("name")}_clone{new_id}')
+    for ext in new.findall(".//a:extLst", NS):
+        ext.getparent().remove(ext)
+    src_shape.getparent().append(new)
+    return new
+
+
+def max_shape_id(root):
+    """Return the largest cNvPr id in use, or 1000 if none (for unique ids)."""
+    ids = []
+    for c in root.xpath(".//p:cNvPr", namespaces=NS):
+        try:
+            ids.append(int(c.get("id")))
+        except (TypeError, ValueError):
+            pass
+    return max(ids) if ids else 1000
+
+
+# ---------------------------------------------------------------------------
+# Timeline math (EMU axis) — from the Claro template
+# ---------------------------------------------------------------------------
+AXIS_START = 1_692_580
+AXIS_END = 11_970_955
+AXIS_WIDTH = AXIS_END - AXIS_START
+OFF_SLIDE_Y = -2_000_000  # park unused markers off-slide
+
+# Track Y centers (diamond_y, label_y)
+TRACK_Y = {
+    1: (3_004_739, 3_148_143),
+    2: (4_137_219, 4_280_623),
+    3: (5_449_646, 5_597_150),
+}
+
+
+def day_to_x(day, total_days):
+    """Map a day index to an X coordinate on the timeline axis."""
+    return AXIS_START + int(AXIS_WIDTH * (day / total_days))
+
+
+def place_event(root, diamond_id, label_id, day, total_days, text, dy, ly):
+    """Place a diamond+label pair at the given day, editing the tree in place.
+
+    Args:
+        root: Document root to search.
+        diamond_id: cNvPr id of the diamond marker shape.
+        label_id: cNvPr id of the label shape.
+        day: Day index of the event.
+        total_days: Total span of the axis in days.
+        text: Label text to set.
+        dy: Diamond Y offset in EMU.
+        ly: Label Y offset in EMU.
+    """
+    cx = day_to_x(day, total_days)
+    d = get_shape(root, diamond_id)
+    if d is not None:
+        dw, _ = get_dims(d)
+        set_pos(d, cx - (dw // 2 if dw else 94518), dy)
+    lb = get_shape(root, label_id)
+    if lb is not None:
+        lw, _ = get_dims(lb)
+        if lw is None:
+            lw = 859133
+        set_pos(lb, cx - lw // 2, ly)
+        set_text(lb, text)

package/canonical/skills/report-formatting/scripts/release-template.md

@@ -0,0 +1,80 @@
+---
+lang: pt-BR
+app: <app>
+version: <x.y.z>
+type: <patch | minor | major> — <uma linha: por que esta release existe>
+artifact: <registry>/<repo>/<app>:<x.y.z>-<commit>
+digest: sha256:<12 primeiros caracteres>…
+date: <DD/MM/AAAA>
+status: <Publicada | Para execução | Executada em DD/MM>
+previous: <x.y.(z-1)>-<commit>
+audience: <CCoE / operação / time X>
+risk: <baixo | médio | alto> — <por quê>; <janela, ticket/aprovação se houver>
+author: André Negrelli
+role: Tech Lead AI Data Engineer
+area: DADOS & IA
+project: <Projeto> — Claro / <app>
+---
+<!--
+Release document model (reference/RELEASE.md). Fixed sections, in this order; the
+build fails on an unknown or missing mandatory section. Only what changed in THIS
+version: no history of earlier releases, no deploy/installation guide (those are
+other documents — link them in "Referências"). Target: two pages. Every claim comes
+from a commit, a test run, a manifest or a measurement. Inline `code` for commands,
+keys, values and log events; **bold** for the one thing the reader must not miss.
+Comments like this one are never rendered.
+-->
+
+## Resumo
+<!-- mandatory · 2-3 sentences: what this release delivers and why now. -->
+<O que esta release entrega e por quê, em duas ou três frases.>
+
+## Mudanças incompatíveis
+<!-- mandatory · "Nenhuma." or one bullet per break with the action the operator must take. -->
+Nenhuma.
+
+## Mudanças
+<!-- mandatory · Keep a Changelog categories (### Adicionado | Alterado | Corrigido | Removido | Obsoleto | Segurança);
+     use only the ones that apply; one bullet per change: what + why + operational impact, with commit/PR id. -->
+### Corrigido
+- <mudança em uma frase — causa, efeito, impacto para a operação> (`<commit>`).
+
+### Alterado
+- <valor ou comportamento que mudou: antes -> depois> (`<commit>`).
+
+## Modelos, prompts e avaliação
+<!-- agentic/LLM/ASR systems · pinned model/prompt/tool/guardrail versions and the eval gate that released the build;
+     "Sem mudança." when nothing moved, plus the evidence line. -->
+| Componente | Nesta release | Evidência / gate |
+|---|---|---|
+| Modelo | `<id/snapshot, quantização>` — <inalterado \| novo> | <suite@versão, métrica, limiar, resultado vs anterior> |
+| Prompt / ferramentas / guardrails | `<id@versão>` | <eval de regressão; n casos> |
+| Telemetria | <spans/métricas novos ou renomeados; conteúdo nunca capturado> | <dashboard / alerta> |
+| Imagem / build | `<tag>` — <como foi validada> | <testes da imagem; gates> |
+
+## Configuração
+<!-- optional · delta only, key by key; Secret keys by name, never values. "Sem mudança." when nothing moved. -->
+| Variável / chave | Antes | Depois | Onde / efeito |
+|---|---|---|---|
+| `<CHAVE>` | `<antes>` | `<depois>` | <ConfigMap/Secret; efeito observável> |
+
+## Rollout e rollback
+<!-- mandatory · how the release enters (one line), who executes, what happens to in-flight work, and the rollback target. -->
+- **Entrada:** <ação única e quem executa — ex.: Restart do Deployment; `latest` já promovida>.
+- **Em andamento:** <o que acontece com mensagens/jobs em voo>.
+- **Rollback:** <alvo imutável `<tag anterior>` e o passo — ou por que não há alvo e qual é o caminho>.
+
+## Verificação
+<!-- mandatory · 2-4 objective signals that prove the release is live and healthy. -->
+- <sinal 1: estado do pod / probe / digest do container>.
+- <sinal 2: evento de log esperado; o que NÃO deve aparecer>.
+- <sinal 3: métrica ou resultado funcional>.
+
+## Problemas conhecidos e pendências
+<!-- optional · open items with owner and closing condition. -->
+- <item, dono, condição para fechar>.
+
+## Referências
+<!-- optional · commits, PRs, the deploy guide, previous release doc, changelog. -->
+- Commits: `<sha>` <título>; `<sha>` <título>.
+- Guia de deploy: <documento/caminho>; release anterior: <documento>.

package/canonical/skills/report-formatting/scripts/render-mermaid.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * render-mermaid.js — Extrai blocos ```mermaid de um arquivo .md e renderiza
+ * cada um como PNG de alta resolução (fundo branco), prontos para embutir no docx.
+ *
+ * Uso:
+ *   node render-mermaid.js <arquivo.md> <diretorio-saida>
+ *
+ * Saída: <saida>/diagram_01.png, diagram_02.png, ...
+ *        imprime um JSON no stdout com a lista de PNGs gerados (na ordem do .md).
+ *
+ * Requer: @mermaid-js/mermaid-cli (mmdc) + Chrome/Chromium.
+ *   npm i -g @mermaid-js/mermaid-cli
+ *   npx puppeteer browsers install chrome-headless-shell   # se faltar o Chrome
+ *
+ * Tema do Mermaid: "neutral" + fonte Arial, para casar com o tema Claro do docx.
+ * As cores definidas via classDef no próprio diagrama (azul/verde/vermelho/amarelo)
+ * são preservadas e combinam com a paleta Claro.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { execFileSync } = require("child_process");
+
+/**
+ * Locate a Chrome/Chromium executable for mmdc (Puppeteer).
+ * Checks, in order: the PUPPETEER_EXECUTABLE_PATH env var, the puppeteer cache,
+ * then common system paths.
+ * @returns {string|null} path to the browser, or null if none is found.
+ */
+function findChrome() {
+  // 1) variável de ambiente explícita
+  if (process.env.PUPPETEER_EXECUTABLE_PATH && fs.existsSync(process.env.PUPPETEER_EXECUTABLE_PATH)) {
+    return process.env.PUPPETEER_EXECUTABLE_PATH;
+  }
+  // 2) cache do puppeteer (~/.cache/puppeteer/**/chrome-headless-shell|chrome)
+  const cache = path.join(os.homedir(), ".cache", "puppeteer");
+  const hits = [];
+  const walk = (dir) => {
+    let ents = [];
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      const p = path.join(dir, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (e.isFile() && (e.name === "chrome-headless-shell" || e.name === "chrome" || e.name === "chromium")) hits.push(p);
+    }
+  };
+  walk(cache);
+  if (hits.length) return hits.sort().reverse()[0]; // versão mais recente
+  // 3) Chrome do sistema
+  for (const p of ["/usr/bin/google-chrome", "/usr/bin/chromium", "/usr/bin/chromium-browser"]) {
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+/**
+ * CLI entry point. Reads the .md at argv[2], renders each ```mermaid block to a
+ * high-res PNG under argv[3], and prints a JSON `{ pngs: [...] }` list to stdout.
+ * Exits with code 2 on missing arguments. Side effects: creates the output
+ * directory and writes .mmd/.png plus temporary config files into it.
+ * @returns {void}
+ */
+function main() {
+  const [, , mdPath, outDir] = process.argv;
+  if (!mdPath || !outDir) {
+    console.error("Uso: node render-mermaid.js <arquivo.md> <diretorio-saida>");
+    process.exit(2);
+  }
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const md = fs.readFileSync(mdPath, "utf8");
+  const blocks = [...md.matchAll(/```mermaid\s*\n([\s\S]*?)```/g)].map((m) => m[1]);
+  if (!blocks.length) { console.log(JSON.stringify({ pngs: [] })); return; }
+
+  // configs para o mmdc
+  const chrome = findChrome();
+  const pptr = path.join(outDir, "_puppeteer.json");
+  fs.writeFileSync(pptr, JSON.stringify({
+    ...(chrome ? { executablePath: chrome } : {}),
+    args: ["--no-sandbox", "--disable-setuid-sandbox"],
+  }));
+  const mconf = path.join(outDir, "_mermaid.json");
+  fs.writeFileSync(mconf, JSON.stringify({ theme: "neutral", themeVariables: { fontFamily: "Arial" } }));
+
+  const pngs = [];
+  blocks.forEach((src, i) => {
+    const n = String(i + 1).padStart(2, "0");
+    const mmd = path.join(outDir, `diagram_${n}.mmd`);
+    const png = path.join(outDir, `diagram_${n}.png`);
+    fs.writeFileSync(mmd, src);
+    try {
+      execFileSync("mmdc", ["-i", mmd, "-o", png, "-b", "white", "-s", "3", "-p", pptr, "-c", mconf], { stdio: "pipe" });
+      pngs.push(png);
+    } catch (e) {
+      console.error(`Falha ao renderizar diagrama ${n}:`, (e.stderr || e.message || "").toString().slice(0, 500));
+    }
+  });
+
+  console.log(JSON.stringify({ pngs }, null, 2));
+}
+
+main();