freeharness 0.4.1

package/canonical/skills/report-formatting/reference/HELPERS.md

@@ -0,0 +1,120 @@
+# Reference — theme-claro.js API
+
+Import: `const T = require("./theme-claro");`
+
+## House typography (applied by default)
+
+- Two fonts only: Arial (prose) and Consolas (commands, identifiers, logs). Never a third.
+- Body text justified with automatic hyphenation (pt-BR), line spacing 1.15 (`line: 276`)
+  everywhere, widow/orphan control. `T.configure({ justify: false, hyphenate: false })`
+  opts out for one build.
+- Headings keep with the next paragraph (`keepNext` + `keepLines`); table rows never
+  split across pages (`cantSplit`); header rows repeat on each page; tables with up to
+  12 rows, meta tables, code blocks, callouts and the authorship block stay on one page.
+- Lead-in sentences before a code block or table take `{ keepNext: true }` so the
+  sentence and the block never separate.
+- Page geometry by layout — select it with `T.configure({ layout })` **before building
+  any block**, because the usable width derives from it: `report` (2 cm all round,
+  header/footer at 1.25 cm) and `compact` (release documents: 1 cm left/right, top
+  1.35 cm, bottom 1.03 cm, header 0.31 cm, footer 0.29 cm from the page edge).
+  `T.configure({ page: { left, right, top, bottom, header, footer } })` overrides in DXA
+  ("personalizado"). `T.contentWidth()` is the usable width; tables, code blocks,
+  callouts, stat cards and images span exactly that width and are centered, so their
+  edges meet the justified text. Column widths given to `makeTable` are scaled to it
+  (`T.fitCols`), so 9640-based tables from older scripts stay aligned.
+
+## Design tokens — T.C (Claro palette)
+
+| Token | Hex | Use |
+| --- | --- | --- |
+| title / h1 | B8000D | cover title, H1 |
+| subtitle / h2 | 333333 | subtitle, H2, highlighted names |
+| h3 | 666666 | H3 |
+| accent / rule / red | E2000F | emphasis labels, cover rule, critical |
+| deepRed | B8000D | blocker |
+| muted | 666666 | secondary text, captions |
+| body | 333333 | body text |
+| green | 2E7D32 | healthy / recommendation |
+| amber | B36B00 | attention / hypothesis |
+| tblHeadFill / tblHeadText | B8000D / FFFFFF | table header |
+| tblBorder / zebra | E5D3D3 / F7F1F1 | table borders, alternating rows |
+| noteFill / dangerFill / successFill / infoFill | FFF2CC / FFE0E0 / E2EFDA / FBEDED | callout fills |
+| codeFill / codeText / codeBar | F5F5F5 / 1F1F1F / 555555 | code block |
+
+`T.contentWidth()` = usable width in DXA for the configured layout (`T.CONTENT_W` = 9640 is the legacy report constant; column widths are scaled to the real width).
+`T.SZ` = `{ body: 22, mono: 18, cell: 20, cellMono: 17 }` (half-points).
+`T.LAYOUTS` = the two page geometries; `T.DEFAULTS` = `{ layout, page, justify, hyphenate, line, lang }`; `T.geometry()` = the effective one.
+
+## Runs
+
+- `T.t(text, opts)` — Arial TextRun. Common opts: `{ size: 22, bold: true, italics: true, color: T.C.red }`.
+- `T.mono(text, sz=18)` — Consolas TextRun for code identifiers.
+- `T.cap(label, color)` — bold "Label " run to start callouts/paragraphs.
+- `T.rich(text, { size, monoSize, color })` — markdown-lite inline: `` `code` `` -> mono,
+  `**bold**` (may wrap code), `*italic*`. Returns runs. `T.rc(text)` = rich at cell sizes.
+
+## Text blocks
+
+- `T.h1("1. Title", o)`, `T.h2(...)`, `T.h3(...)` — `o` e.g. `{ pageBreakBefore: true }`.
+- `T.body(runs, o)` — body paragraph from text or runs; `o` = Paragraph options plus
+  `before` (DXA), e.g. `{ keepNext: true }`, `{ before: 100 }` after a code block.
+- `T.p(text, o)` — `body(rich(text), o)`. Preferred for prose with inline code/bold.
+- `T.bullet(runs, lvl=0, o)` / `T.li(text, lvl=0, o)` — bullets (rich for `li`).
+- `T.numItem(runs, instance|{instance,lvl}, o)` / `T.num(text, instance, o)` — numbered
+  items; each distinct `instance` restarts at 1 (one instance per section).
+  `T.numbered(["a","b"], instance)` -> array of items.
+- `T.caption("Tabela 1 – ...", { center: true })` — italic grey caption.
+- `T.spacer(after=120)`, `T.pageBreak()`.
+
+## Tables
+
+- `T.makeTable(cols, head, rows, { keepTogether, rich })`
+  - cols: DXA widths (e.g. `[3200, 1600, 4840]`, summing ~9640).
+  - head: `["Col1", "Col2", ...]` (red header row, repeats on each page).
+  - rows: array of rows; each cell is a string or
+    `{ runs: "txt" | [T.t(...)], align: AlignmentType.RIGHT, fill: T.C.noteFill }`.
+  - `rich: true` parses string cells with `T.rc` (`code`, **bold**).
+  - `keepTogether` holds the whole table on one page (default: rows <= 12). Rows never split.
+- `T.metaTable(rows, col1=2500)` — memo layout; `rows = [["Aplicação","..."],["Data","..."]]`;
+  string values go through `T.rc`. Always held on one page.
+
+## Highlights
+
+- `T.callout(paras | "rich text", kind)` — kind: `"info"|"note"|"danger"|"success"`. Never splits.
+- `T.calloutLine(label, text, kind)` — one-line shortcut; text accepts rich syntax.
+- `T.codeBlock(["line1","line2"])` — Consolas block with a grey bar (commands, logs,
+  trees); held on one page. Put `{ keepNext: true }` on the sentence that introduces it.
+- `T.statCards([{ value:"99.9%", label:"...", color:T.C.red, fill:"FFEDED" }])` — metrics strip.
+
+## Media and structure
+
+- `T.image(pngPath, maxWidthEmu, { keepNext, maxHeightEmu })` — centered, auto-sized to the
+  text width and at most ~half a page tall by default; glued to its caption.
+- `T.coverBlock({ title, subtitle, tagline, org, metaLines, rule })` -> paragraphs
+  (spread: `children.push(...T.coverBlock({...}))`). `rule: false` for the compact
+  release front page (title + metaTable, no cover rule).
+- `T.authorBlock({ heading, name, role, area, project })` -> array; heading defaults to
+  "ELABORAÇÃO E ANÁLISE" ("ELABORAÇÃO" for release docs).
+- `T.buildDocument({ children, headerText, footerAuthor, footerNote, layout, page })` ->
+  Document for `Packer.toBuffer`. `footerNote` defaults to "Confidencial – Uso Interno".
+  Prefer `T.configure({ layout })` at the top of the script; passing `layout`/`page` here
+  applies them to the page only and warns (blocks were already sized).
+
+## Semaphore cell example
+
+```js
+[{ runs: "Row A" },
+ { runs: [T.t("12,775", { size: 20, bold: true, color: T.C.red })], align: AlignmentType.RIGHT },
+ { runs: [T.t("ok", { size: 20, color: T.C.green })] }]
+```
+
+## Content-file models (docmodel.js)
+
+`scripts/docmodel.js` renders a .docx from a Markdown content file with fixed sections
+declared by a model script: `build-release.js` (release-template.md) and
+`build-architecture.js` (architecture-template.md). Blocks: paragraphs, bullets,
+numbered steps (restart per list), pipe tables (`<!-- cols: 30 70 -->`), fenced code,
+```mermaid (rendered via render-mermaid.js; `<!-- width: 70 -->`), `![caption](img.png)`,
+`> ` callouts, `###`/`####` sub-headings, "Figura N –" captions, HTML comments ignored.
+The build fails on unknown/missing sections and malformed tables; it never overwrites a
+.docx that Word holds open (writes `-new.docx`).

package/canonical/skills/report-formatting/reference/PPTX.md

@@ -0,0 +1,136 @@
+# Reference — .pptx presentations / status reports (Claro theme)
+
+Methodology for creating, editing, and updating .pptx decks (default theme:
+Claro). Library: scripts/pptx/theme_claro_pptx.py (import as `T`). Self-contained
+office ops: scripts/pptx/pptx_office.py (unpack/pack/clean/render) — no Anthropic
+container dependency.
+
+## Environment
+
+```bash
+python3 -m pip install -r scripts/pptx/requirements.txt --break-system-packages
+# python-pptx, lxml, Pillow, defusedxml
+# System tools for QA render: soffice (LibreOffice headless) + pdftoppm (poppler).
+```
+
+Use Calibri/Arial only. Non-safe fonts (Aptos, Georgia, Trebuchet) render with
+different widths under LibreOffice and break QA.
+
+## Two build strategies (pick per slide)
+
+- Rebuild with python-pptx: for custom slides (summary tables, Gantt, heatmap,
+  ROAM map). `clear_slide_shapes(slide)` then build with the T helpers. Guarantees
+  visual consistency across versions.
+- Clone + edit via lxml: for complex template slides (the Claro timeline has ~150
+  shapes — cylinder, gears, custom forms). Do NOT rebuild these from scratch;
+  duplicate the model slide and edit text/positions by cNvPr id with the lxml
+  helpers (set_text, set_pos, set_fill, clone_shape).
+
+## Workflow
+
+1. Analyze the template: render a thumbnail/PDF, extract text, unpack the .pptx
+   (`python scripts/pptx/pptx_office.py unpack in.pptx unpacked/`).
+2. Parse the input activity report: extract activities + dates, group into 3
+   tracks/fronts, detect the period (earliest/latest date). Never invent dates;
+   label inferred ones.
+3. Plan the structure (cover + historical timelines kept + summary + current
+   timeline + detail timelines + Gantt + heatmap + ROAM).
+4. Manipulate slide order in ppt/presentation.xml `sldIdLst` (see rules below);
+   then `pptx_office.py clean unpacked/`.
+5. Edit each slide: cover date (lxml), timelines (reposition diamonds + edit
+   labels via lxml paired by X), custom slides (clear + rebuild via python-pptx),
+   page numbers.
+6. Pack once: `python scripts/pptx/pptx_office.py pack unpacked/ out.pptx`.
+   Do ALL edits in unpacked/ first, then a single pack (re-packing over a stale
+   unpacked/ overwrites edits).
+7. QA render: `python scripts/pptx/pptx_office.py render out.pptx ./_qa` -> inspect
+   each slide jpg; fix and re-pack. Limit to 1-2 correction cycles.
+8. Deliver the .pptx + a short summary (structure, inferred dates to validate).
+
+## sldIdLst rules (ppt/presentation.xml)
+
+- Each `<p:sldId>` needs a unique id (use ids > 2_147_480_300 for new slides) and
+  an `r:id` that references a Relationship in ppt/_rels/presentation.xml.rels.
+- Reorder = reorder the `<p:sldId>` entries. Remove = delete the entry. Add =
+  create the slide part + a rel, then insert the entry at the desired position.
+- Always run `pptx_office.py clean unpacked/` after editing sldIdLst (sweep orphans).
+
+## Reusable status-report blocks (status_report_blocks.py)
+
+For the two recurring status-report slides, prefer the generic builders in
+scripts/pptx/status_report_blocks.py over hand-rebuilding — they encode the refined
+Claro layout and carry no project data. Both CLEAR and rebuild the given slide, so
+they work for new blank slides and in-place rebuilds.
+
+```python
+import status_report_blocks as B
+B.build_heatmap(slide, title=..., subtitle=..., banner=..., rows=[(label, [keys], data)],
+                stages=[...], backlog_col=True, data_header="Backlog (TIDs)", page=n, total=N)
+B.build_gantt(slide, title=..., subtitle=..., activities=[{name,cat,start,end,prio}],
+              week_labels=[...], page=n, total=N)
+```
+
+- build_heatmap: período × estágio grid with status keys done/inprogress/pending/
+  parcial/backlog (note the Parcial gold category), an optional trailing data column,
+  and a full legend. `rows` = list of (label, [status_key per stage], data_str|None).
+- build_gantt: Claro "Cronograma / Próximos Passos" — red header, dark week columns,
+  per-row accent + category chip + priority bar sharing CAT_COLOR[cat], category
+  legend. `activities` use 1-based start/end week indices and prio in Alta/Média/Baixa.
+
+## Slide patterns (built with theme_claro_pptx)
+
+- Summary of deliverables: red header + zebra rows; columns = strategic delivery
+  (red accent + bold title + italic subtitle) / deliveries (bullets) / maturity
+  (colored status) / business impact (bullets).
+- Timeline ("Status até DD/MM"): cloned template slide; banner, executive note,
+  observations cylinder, current-date label aligned to the dashed line, month
+  labels, 3 tracks of diamond+label pairs positioned via `day_to_x`. Unused
+  markers: del_shape or park at OFF_SLIDE_Y. Enrich by cloning pairs with
+  `max_shape_id + 1`.
+- Gantt (weekly): week columns x activity rows. Use B.build_gantt; chip + accent bar
+  + Gantt bar share CAT_COLOR[category] (the builder keeps them in sync).
+- Heatmap: período x estágio grid with status icons + optional data column. Use
+  B.build_heatmap (handles header, rows, legend, and row sizing for n>8).
+- ROAM risk map: 7-column table; ROAM badge is a (circle + letter) pair — on a
+  ROAM change update both set_fill and set_text.
+
+## QA checklist
+
+No overflow; no overlapping timeline labels; elements within 0.45in of edges;
+correct page numbering X/N; chips/bars/accents/badges share the category color;
+title/current-date/axis dates aligned; table zebra preserved; status badge fill
+matches its letter.
+
+## Anti-patterns
+
+- Rebuilding the timeline from scratch with python-pptx (loses fidelity) — clone
+  + edit via lxml instead.
+- Editing the final .pptx with python-pptx then re-running pack over unpacked/ —
+  do all edits in unpacked/, pack once.
+- str_replace on XML with repeated texts — identify shapes by unique cNvPr id and
+  edit via lxml xpath.
+- Crowding markers in a short window (gap < 2 days) — consolidate near events.
+- Updating a chip color but not the accent/bar — one function updates all.
+
+## EMU glossary
+
+914_400 EMU = 1 inch. 16:9 slide = 12_192_000 x 6_858_000 EMU. cNvPr = unique
+shape id. sldIdLst = slide order. txBody/rPr/pPr = text body / run / paragraph
+properties. srgbClr = hex RGB. xfrm/off = position; xfrm/ext = size.
+
+## Logo (Claro brand)
+
+`add_page_header` already places the Claro logo (scripts/assets/claro-logo.png) small
+in the top-right of every content slide. On the cover, call `T.add_logo(slide,
+x=Inches(0.5), y=Inches(0.7), height=Inches(1.3))` for a prominent mark. `add_logo`
+preserves aspect and right-aligns by default; it returns None if the asset is missing
+(so builds degrade cleanly). Replace scripts/assets/claro-logo.png to rebrand.
+
+## Palette (T.* constants)
+
+CLARO_RED E2000F, CLARO_RED_DARK B8000D; DARK_GRAY 333333, MID_GRAY 666666,
+LIGHT_GRAY E8E8E8, VERY_LIGHT_GRAY F5F5F5; STATUS_DONE 2E7D32 (green),
+STATUS_INPROGRESS F9A825 (amber), STATUS_PENDING E67E22 (orange), STATUS_BACKLOG
+95A5A6 (grey), STATUS_RISK C0392B; CAT_COLOR per track (Pipeline blue, WhisperX
+purple, Data Core teal, Backlog orange, Infra grey-blue, Documentação red,
+Análises violet). ROAM: R green, O blue, A amber, M teal.

package/canonical/skills/report-formatting/reference/RELEASE.md

@@ -0,0 +1,99 @@
+# Reference — Release document (model)
+
+What the market calls release notes for a versioned deploy of an application or
+agentic system, handed to the team that operates it. The document answers one
+question — **what changed in this version and what it means for whoever runs it** —
+and nothing else: no history of earlier releases (they have their own documents), no
+deploy or installation guide (link it under "Referências"). Target length: two pages.
+
+Model = `scripts/release-template.md` (content file with fixed sections) rendered by
+`scripts/build-release.js` (generic; application and version come from the content
+file). The build fails on an unknown section, a missing mandatory section or an
+unknown change category — the structure is the model, not a suggestion.
+
+```
+node scripts/build-release.js <release.md> <out.docx>
+```
+
+Deliver only the `.docx`. A PDF render (soffice) is allowed only as a throwaway visual
+check in a scratch directory; it is never written next to the deliverable.
+
+## Where the structure comes from (2024-2026 practice)
+
+- Keep a Changelog 1.1.0: for humans, not a commit dump; one entry per version, dated;
+  changes grouped by type — Added, Changed, Deprecated, Removed, Fixed, Security.
+- Semantic Versioning 2.0: the version number states the kind of change (MAJOR breaks,
+  MINOR adds, PATCH fixes); a released artefact is immutable — reference it by
+  `<version>-<commit>` tag **and** digest; if the platform pins a floating tag, say which
+  release it resolves to (Kubernetes: avoid `:latest` alone — harder to track and roll back).
+- Conventional Commits / release-please / GitHub release notes: breaking changes called
+  out first, each change linked to its commit/PR.
+- Google SRE (Release Engineering, Canarying): a release is a rollout — how it enters,
+  the few signals that prove it is healthy, and a rollback path that does not depend on
+  the new version working.
+- ITIL 4 change record: rationale, risk × impact, window/approval, rollback plan, owner —
+  a change without rollback plan or impact statement should not advance.
+- Agentic / LLM / ASR systems: pinned model id or snapshot, quantization/compute type,
+  prompt/tool/guardrail versions, the eval gate that released the build (dataset@version,
+  metric, threshold, result vs previous — FP32 golden for quantization changes),
+  telemetry deltas (OpenTelemetry GenAI: content/PII never captured), model fallback.
+
+## Fixed sections (in this order)
+
+| Section (`## ` title) | Mandatory | Content |
+|---|---|---|
+| front matter | yes | app, version, type (patch/minor/major + why), artifact (immutable tag), digest, date, status, previous, audience, risk/window, author/role/area/project |
+| Resumo | yes | 2-3 sentences: what this release delivers and why now |
+| Mudanças incompatíveis | yes | `Nenhuma.` or one bullet per break with the mandatory operator action |
+| Mudanças | yes | `### Adicionado | Alterado | Corrigido | Removido | Obsoleto | Segurança` — only the categories that apply; one bullet per change: what, why, operational impact, commit/PR |
+| Modelos, prompts e avaliação | agentic systems | table Componente / Nesta release / Evidência — model, prompt/tools/guardrails, telemetry, image/build validation; "inalterado" + evidence when nothing moved |
+| Configuração | when anything changed | table Variável / Antes / Depois / Onde-efeito — delta only; Secret keys by name, never values |
+| Rollout e rollback | yes | Entrada (single action, who executes), Em andamento (in-flight work), Rollback (immutable target and step — or why there is none and the path) |
+| Verificação | yes | 2-4 objective signals: pod/probe/digest, expected log event and what must not appear, functional result |
+| Problemas conhecidos e pendências | optional | open items with owner and closing condition |
+| Referências | optional | commits, PRs, deploy guide, previous release document, changelog |
+
+Rendering: title `<app> — Release <version>`, memo table from the front matter,
+sections as H1, categories as H3, `Nenhuma.` as a green callout, `> ` as a callout
+(info; `**Atenção/Risco/Não…**` note; `**Quebra/Incompatível…**` danger), pipe tables
+as theme tables (`<!-- cols: 30 20 50 -->` before a table fixes widths), fenced code
+as code blocks, `ELABORAÇÃO` block at the end, header `<app> — Release`, compact layout
+(1 cm left/right margins; every block spans the text width, centered).
+
+## Writing rules
+
+- Only this version. Previous releases are named once (front matter `previous`,
+  "Referências") — never re-described.
+- One sentence per change, with its operational impact; the commit id in parentheses.
+- Commands, keys, values, file names and log events in `code` — also inline; **bold**
+  only for the single thing the reader must not miss (e.g. `**não alterar**`).
+- Exact, copy-pasteable commands; placeholders only for reader-owned values.
+- No secrets, tokens, customer data or transcribed text; production identifiers only as
+  needed; every number traced to a commit, test run, manifest or measurement.
+- Formatting is the theme's (two fonts, justified 1.15 with hyphenation, headings kept
+  with text, tables and code never split, lists restart per section); do not hand-roll.
+
+## Checklist before delivering
+
+1. Immutable artefact: tag + digest; floating tag, if any, says which release it resolves to.
+2. Type and version agree (patch/minor/major); date present; previous release named.
+3. Breaking changes first, or `Nenhuma.` stated.
+4. Every change: what, why, impact, commit — grouped by category; nothing from earlier versions.
+5. Agentic systems: model/prompt/guardrail versions, eval gate result, telemetry delta.
+6. Configuration delta key by key; Secret keys by name only.
+7. Rollout: single entry action and owner; in-flight work; rollback target or its absence.
+8. Verification: objective signals, including what must not appear.
+9. Pending items with owner; references to the deploy guide and previous release.
+10. Two pages; build passed (fixed sections); `.docx` only delivered.
+
+## Sources
+
+Keep a Changelog 1.1.0; Semantic Versioning 2.0.0; Conventional Commits 1.0.0;
+release-please; GitHub automatically generated release notes; Google SRE Book —
+Release Engineering, Launch Checklist; SRE Workbook — Canarying Releases; Kubernetes
+docs — Images (tags, digests, pull policy), Deployments (rollout/undo); Bitnami charts
+"Upgrading" convention; ITIL 4 change enablement (AWS Well-Architected guide);
+OpenTelemetry GenAI semantic conventions; Hugging Face model cards; MLflow Model
+Registry (versions, aliases); Anthropic model overview / release notes (pinned
+snapshots); Microsoft Writing Style Guide and Google developer documentation style
+guide (code in text, code samples, placeholders); Butterick, Practical Typography.

package/canonical/skills/report-formatting/reference/TEMPLATES.md

@@ -0,0 +1,48 @@
+# Template catalog
+
+One theme library per format (theme-claro.js for .docx, theme_claro_pptx.py for
+.pptx) + one executable template per document type. Pick the template that
+matches the document type, copy it to build-<slug>, fill it with real content,
+and generate. Add new templates here as new types arise (one engine, many bases).
+
+## .docx (Node, theme-claro.js)
+
+| Document type | Template | When to use |
+|---|---|---|
+| Technical report | scripts/example-build.js | Technical/analytical reports: memo metadata, dense tables, evidence, code blocks, captions. The detailed, audit-oriented base. |
+| Executive report | scripts/example_build_ExecutiveReport_docx.js | Leadership readers with little time and no technical background: high-level storytelling (tension -> evidence -> resolution), stats translated to business language, decision panel (semaphore), one-page closing. |
+| Release | scripts/build-release.js + scripts/release-template.md | Release notes of a versioned deploy for the operating team: what changed in THIS version only (fixed sections: Resumo, Mudanças incompatíveis, Mudanças by Keep a Changelog category, Modelos/prompts/avaliação, Configuração, Rollout e rollback, Verificação, Pendências, Referências). Content-file driven — copy release-template.md, fill it, run `node scripts/build-release.js <release.md> <out.docx>`; the build enforces the structure. Two pages, compact layout. Guide: reference/RELEASE.md. |
+| Architecture review | scripts/example_build_ArchitectureReview_docx.js | A review that JUDGES an existing system or agentic design (phase gate, post-incident, audit, PR-level architecture review): verdict first (PASS / FAIL / CONDITIONAL + severity cards), review context (object, motivation, criteria, method, out of scope), current architecture with deviations from the blueprint, findings table ranked by severity with evidence, decision records (compact ADR), residual risks, remediation roadmap in waves, re-verification rule. Not for describing a system — that is the Architecture & System Design model below. |
+| Architecture & System Design | scripts/build-architecture.js + scripts/architecture-template.md | Architecture description of an application or agentic system (arc42 + C4 + 42010 + ADR + agentic sections): cover page + Sumário, Elaboração/Histórico, 0 Sumário executivo, 1 Visão e contexto, 2 Visão lógica, 3 Estrutura de diretório, 4 Agentes e orquestração, 5 Visão de runtime, 6 Contratos, 7 Dados, 8 Configuração, 9 Infraestrutura, 10 Observabilidade, 11 Segurança e AI Safety, 12 Qualidade/avaliação/testes, 13 Decisões (ADR), 14 Riscos, 15 Roadmap, 16 Rastreabilidade, Glossário. Content-file driven; Mermaid rendered; `node scripts/build-architecture.js <arch.md> <out.docx>`. Guide: reference/ARCHITECTURE.md. |
+
+Markdown source, faithful render (no template to fill): `node scripts/build-md-claro.js
+<input.md> <output.docx> [--diagrams DIR] [--title T] [--subtitle S] [--header H]
+[--author NAME] [--role ROLE] [--project P] [--meta "Key=Value;Key=Value"] [--skip-h1]`.
+Every Markdown block maps to one theme helper (`##` -> h1, pipe tables -> makeTable,
+fenced code -> codeBlock, ```mermaid -> pre-rendered diagram, blockquote -> callout);
+numbered lists restart per block. Use it when the source is already a finished .md and
+the job is formatting, not authoring.
+
+## .pptx (Python, theme_claro_pptx.py)
+
+| Document type | Template | When to use |
+|---|---|---|
+| Status report deck | scripts/pptx/example_build_StatusReport_pptx.py | Biweekly/monthly status report: cover, deliverables summary, Gantt, processing heatmap, ROAM risk map. Rich timeline slides are cloned from the Claro template via lxml (see PPTX.md), not rebuilt by the template. |
+| Weekly status deck | scripts/pptx/example_build_WeeklyStatus_pptx.py | Short weekly squad update (six slides): cover, week highlights in three lanes (done / in progress / blocked, with counts), processing heatmap and execution Gantt built by status_report_blocks.build_heatmap / build_gantt, ROAM risks of the week, next-week plan + decisions needed. No deliverables table, no cloned timeline slides; use the Status report deck for the biweekly/monthly view. |
+
+For the heatmap and Gantt slides of a status report, use the reusable builders in
+scripts/pptx/status_report_blocks.py (build_heatmap, build_gantt) — generic, no
+project data, clear + rebuild a slide. Preferred over rebuilding by hand; see PPTX.md.
+
+All .docx templates share the house typography (reference/HELPERS.md, "House
+typography"): two fonts, justified 1.15 text, headings kept with their text, tables and
+code blocks never cut by a page break. The release and architecture models use `layout: "compact"` (1 cm lateral margins);
+the others keep the default `report` geometry.
+
+## Adding a new template
+
+1. Reuse the theme library (do not fork the palette/helpers).
+2. Create scripts/<...>example_build_<Type>_<ext>.{js,py} from the closest
+   existing template.
+3. Register it in the table above with a clear "when to use".
+4. Keep the same authorship/footer defaults (reference/authoring.md).

package/canonical/skills/report-formatting/reference/authoring.md

@@ -0,0 +1,66 @@
+# Authoring defaults
+
+Defaults for the authorship block and footer. Override if the user names another
+author/project. These are house defaults, not hardcoded — pass different values
+to the helpers when needed.
+
+## Default author
+
+- Name: André Negrelli
+- Role: Tech Lead — AI Data Engineer
+- Area: DADOS & IA | Tech Dados & IA — Aquisição e Transformação de Dados & IA
+- Project: configurable per document (e.g. "Projeto STT — Claro")
+
+```js
+T.authorBlock({
+  name: "André Negrelli",
+  role: "Tech Lead — AI Data Engineer",
+  area: "DADOS & IA  |  Tech Dados & IA — Aquisição e Transformação de Dados & IA",
+  project: "<Project> — <Client>  ·  <DATE>",
+});
+```
+
+Footer:
+
+```js
+T.buildDocument({
+  children,
+  headerText: "<Title>  |  <Project>",
+  footerAuthor: "André Negrelli — DADOS & IA",
+});
+```
+
+## Release documents
+
+Shorter identity, measured from the reference release document
+(stt-whisperx — Release 0.4.2): header `"<app> — Release"`, footer author
+`"André Negrelli — Tech Lead AI Data Engineer | DADOS & IA"`, authorship heading
+`"ELABORAÇÃO"` with name, role and `"<Project> — Claro / <app>"`, `T.configure({ layout: "compact" })`.
+
+```js
+T.authorBlock({ heading: "ELABORAÇÃO", name: "André Negrelli", role: "Tech Lead AI Data Engineer", project: "Speech-to-text Claro / stt-whisperx" });
+T.configure({ layout: "compact" });  // first line of the build
+T.buildDocument({ children, headerText: "stt-whisperx — Release", footerAuthor: "André Negrelli — Tech Lead AI Data Engineer | DADOS & IA" });
+```
+
+## Document identity (Claro theme)
+
+- A4 page, Arial for prose + Consolas for code (no third font); geometry per layout
+  (`report`: 2 cm all round; `compact` for release documents: 1 cm left/right, tight
+  top/bottom, header/footer close to the edge). Blocks span the text width, centered.
+- Body text justified, 1.15 line spacing; headings keep with the next paragraph;
+  tables, code blocks and callouts are never cut by a page break.
+- Claro institutional palette (red anchors, gray hierarchy): red headings, red
+  table headers with white text — defined in the C token object, aligned with
+  theme_claro_pptx.py. Do not reintroduce the old blue palette.
+- Claro logo (scripts/assets/claro-logo.png): centered on the cover (via
+  coverBlock) and small in the top-right of every page header (via buildDocument).
+  Both degrade cleanly if the asset is missing. Use `T.logoRun({height})` to place
+  it elsewhere.
+- Italic grey header with a bottom rule + logo; footer with author on the left and
+  "Confidencial – Uso Interno | Página X de Y" on the right.
+- Centered "ELABORAÇÃO E ANÁLISE" authorship block at the end.
+- Output language: PT-BR by default (client-facing); change per request.
+
+The logo asset is shared by both formats at scripts/assets/claro-logo.png (pptx uses
+it via T.add_logo / add_page_header). Replace that file to rebrand both tracks.