@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/general/webapp-testing/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: webapp-testing
+description: Browser-based testing for web applications using Playwright. Supports screenshot verification, DOM inspection, console log capture, and automated UI testing. Integrates with QA agent visual verification protocol.
+license: Apache-2.0
+compatibility: Requires Python 3.8+ and playwright package. Install with 'pip install playwright && playwright install chromium'.
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  based-on: anthropics/skills/webapp-testing
+  auto_activate: [playwright, e2e-test, browser-test, visual-test, smoke-test]
+  file_triggers:
+    ["*.spec.ts", "*.spec.js", "*.test.ts", "*.test.js", "*.e2e.ts", "*.e2e.js"]
+  tool_reminders:
+    [
+      Always wait for networkidle before inspecting dynamic pages,
+      Use reconnaissance-then-action pattern: screenshot → identify selectors → execute,
+      Browser tests require MEDIUM approval — confirm with user before running,
+      Always close browser when done — resource leak prevention,
+    ]
+---
+
+# Webapp Testing with Playwright
+
+Browser-based testing skill for verifying web application behavior through screenshots, DOM inspection, console logs, and automated UI interaction.
+
+## Decision Tree: When to Use What
+
+```
+Is the application a static HTML file?
+  YES → Open directly with Playwright, no server needed
+  NO → Is a dev server already running?
+    YES → Connect to existing server URL
+    NO → Use with_server.py to manage server lifecycle
+```
+
+## Server Lifecycle Management
+
+For applications that need a dev server, use the `with_server.py` script to manage startup/shutdown:
+
+```bash
+# Start server, run test, stop server
+python .merlin-core/skills/general/webapp-testing/scripts/with_server.py \
+  --cmd "npm run dev" \
+  --port 3000 \
+  --timeout 30 \
+  -- python test_script.py
+```
+
+The script:
+
+1. Starts the dev server in the background
+2. Waits for the port to become available
+3. Runs your test command
+4. Stops the server on completion (or error)
+
+## Reconnaissance-Then-Action Pattern
+
+NEVER interact with a page blindly. Always follow this sequence:
+
+1. **Screenshot first** — Capture the current state before any interaction
+2. **Identify selectors** — Use DOM inspection to find correct selectors
+3. **Execute action** — Click, type, navigate using verified selectors
+4. **Verify result** — Screenshot again to confirm the expected outcome
+
+```python
+from playwright.sync_api import sync_playwright
+
+with sync_playwright() as p:
+    browser = p.chromium.launch()
+    page = browser.new_page()
+    page.goto("http://localhost:3000")
+
+    # 1. Reconnaissance
+    page.wait_for_load_state("networkidle")
+    page.screenshot(path="before.png")
+
+    # 2. Identify (inspect DOM if needed)
+    button = page.locator("button:has-text('Submit')")
+
+    # 3. Execute
+    button.click()
+    page.wait_for_load_state("networkidle")
+
+    # 4. Verify
+    page.screenshot(path="after.png")
+    assert page.locator(".success-message").is_visible()
+
+    browser.close()
+```
+
+## Responsive Testing
+
+Always test at three viewport widths:
+
+| Viewport | Width  | Use Case            |
+| -------- | ------ | ------------------- |
+| Mobile   | 640px  | Phone screens       |
+| Tablet   | 1024px | Tablet/small laptop |
+| Desktop  | 1440px | Standard desktop    |
+
+```python
+for width in [640, 1024, 1440]:
+    page.set_viewport_size({"width": width, "height": 900})
+    page.screenshot(path=f"viewport-{width}.png")
+```
+
+## Console Log Capture
+
+Capture and analyze console output for errors and warnings:
+
+```python
+console_messages = []
+page.on("console", lambda msg: console_messages.append({
+    "type": msg.type,
+    "text": msg.text,
+    "location": msg.location
+}))
+
+# After interactions, check for errors
+errors = [m for m in console_messages if m["type"] == "error"]
+warnings = [m for m in console_messages if m["type"] == "warning"]
+```
+
+## Screenshot Comparison
+
+Use `screenshot_compare.py` for visual regression detection:
+
+```bash
+python .merlin-core/skills/general/webapp-testing/scripts/screenshot_compare.py \
+  --baseline before.png \
+  --current after.png \
+  --threshold 5.0
+```
+
+Returns exit code 0 if difference < threshold%, 1 otherwise.
+
+## Integration with QA Agent
+
+When the QA agent invokes visual verification:
+
+1. Capture screenshots at all responsive breakpoints
+2. Check console for errors/warnings
+3. Compare against baseline screenshots if available
+4. Report findings with screenshot paths for human review
+
+## Best Practices
+
+- **Always use `networkidle`** — Dynamic SPAs need time to settle after navigation
+- **Use text-based selectors** — `page.locator("button:has-text('Submit')")` over CSS class selectors
+- **Set reasonable timeouts** — 30s default, 60s for slow pages
+- **Clean up resources** — Always close browser in finally/cleanup block
+- **Screenshot naming** — Use descriptive names: `{page}-{viewport}-{state}.png`
+- **Headless by default** — Use `headless=True` unless debugging

package/.merlin-core/skills/general/webapp-testing/scripts/screenshot_compare.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""
+Screenshot comparison for visual regression testing.
+
+Compares two screenshots and reports the pixel difference percentage.
+Returns exit code 0 if difference is below threshold, 1 otherwise.
+
+Usage:
+    python screenshot_compare.py --baseline before.png --current after.png --threshold 5.0
+
+Merlin Framework v2.10.0
+"""
+
+import argparse
+import sys
+
+try:
+    from PIL import Image, ImageChops
+    HAS_PIL = True
+except ImportError:
+    HAS_PIL = False
+
+
+def compare_images(baseline_path, current_path):
+    """Compare two images and return difference percentage."""
+    if not HAS_PIL:
+        print("Error: Pillow not installed. Run: pip install Pillow", file=sys.stderr)
+        sys.exit(2)
+
+    baseline = Image.open(baseline_path).convert("RGB")
+    current = Image.open(current_path).convert("RGB")
+
+    # Resize to match if dimensions differ
+    if baseline.size != current.size:
+        current = current.resize(baseline.size, Image.Resampling.LANCZOS)
+
+    diff = ImageChops.difference(baseline, current)
+    pixels = list(diff.getdata())
+    total_pixels = len(pixels)
+
+    if total_pixels == 0:
+        return 0.0
+
+    # Count pixels with any difference above noise threshold (5/255)
+    changed = sum(1 for p in pixels if max(p) > 5)
+    return (changed / total_pixels) * 100
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Compare two screenshots for visual differences.")
+    parser.add_argument("--baseline", required=True, help="Path to baseline screenshot")
+    parser.add_argument("--current", required=True, help="Path to current screenshot")
+    parser.add_argument("--threshold", type=float, default=5.0, help="Max acceptable difference percentage (default: 5.0)")
+    parser.add_argument("--output", help="Path to save diff image (optional)")
+
+    args = parser.parse_args()
+
+    diff_pct = compare_images(args.baseline, args.current)
+
+    print(f"Difference: {diff_pct:.2f}%")
+    print(f"Threshold:  {args.threshold:.2f}%")
+
+    if diff_pct <= args.threshold:
+        print("Result: PASS")
+        sys.exit(0)
+    else:
+        print("Result: FAIL — visual regression detected")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/.merlin-core/skills/general/webapp-testing/scripts/with_server.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""
+Server lifecycle manager for webapp testing.
+
+Starts a development server, waits for it to be ready,
+runs a test command, then stops the server.
+
+Usage:
+    python with_server.py --cmd "npm run dev" --port 3000 -- python test.py
+    python with_server.py --cmd "python -m http.server 8080" --port 8080 -- pytest tests/
+
+Based on Anthropic's webapp-testing skill pattern.
+Merlin Framework v2.10.0
+"""
+
+import argparse
+import subprocess
+import sys
+import time
+import socket
+import signal
+import os
+
+
+def wait_for_port(port, host="localhost", timeout=30):
+    """Wait for a port to become available."""
+    start = time.time()
+    while time.time() - start < timeout:
+        try:
+            with socket.create_connection((host, port), timeout=1):
+                return True
+        except (ConnectionRefusedError, OSError):
+            time.sleep(0.5)
+    return False
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Start a server, run a command, then stop the server."
+    )
+    parser.add_argument("--cmd", required=True, help="Server start command")
+    parser.add_argument("--port", type=int, required=True, help="Port to wait for")
+    parser.add_argument("--host", default="localhost", help="Host to check (default: localhost)")
+    parser.add_argument("--timeout", type=int, default=30, help="Startup timeout in seconds")
+    parser.add_argument("test_cmd", nargs=argparse.REMAINDER, help="Test command to run after server starts")
+
+    args = parser.parse_args()
+
+    # Remove leading '--' separator if present
+    test_cmd = args.test_cmd
+    if test_cmd and test_cmd[0] == "--":
+        test_cmd = test_cmd[1:]
+
+    if not test_cmd:
+        print("Error: No test command provided after '--'", file=sys.stderr)
+        sys.exit(1)
+
+    server_process = None
+
+    try:
+        # Start server
+        print(f"Starting server: {args.cmd}")
+        server_process = subprocess.Popen(
+            args.cmd,
+            shell=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            preexec_fn=os.setsid if hasattr(os, "setsid") else None,
+        )
+
+        # Wait for port
+        print(f"Waiting for port {args.port} (timeout: {args.timeout}s)...")
+        if not wait_for_port(args.port, args.host, args.timeout):
+            print(f"Error: Server did not start on port {args.port} within {args.timeout}s", file=sys.stderr)
+            sys.exit(1)
+
+        print(f"Server ready on port {args.port}")
+
+        # Run test command
+        print(f"Running: {' '.join(test_cmd)}")
+        result = subprocess.run(test_cmd)
+        sys.exit(result.returncode)
+
+    finally:
+        # Stop server
+        if server_process and server_process.poll() is None:
+            print("Stopping server...")
+            try:
+                if hasattr(os, "killpg"):
+                    os.killpg(os.getpgid(server_process.pid), signal.SIGTERM)
+                else:
+                    server_process.terminate()
+                server_process.wait(timeout=5)
+            except (ProcessLookupError, subprocess.TimeoutExpired):
+                if hasattr(os, "killpg"):
+                    os.killpg(os.getpgid(server_process.pid), signal.SIGKILL)
+                else:
+                    server_process.kill()
+            print("Server stopped.")
+
+
+if __name__ == "__main__":
+    main()

package/.merlin-core/skills/general/xlsx/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: xlsx
+description: "Use this skill any time a spreadsheet file is the primary input or output. This includes opening, reading, editing, or fixing .xlsx/.xlsm/.csv/.tsv files; creating new spreadsheets from scratch or from other data; converting between tabular formats; cleaning messy tabular data; AND generating colored, multi-sheet operational reports from a Node/JS script (Firestore/backend exports) via SheetJS/xlsx-js-style."
+license: MIT (Anthropic)
+compatibility: claude-code
+metadata:
+  source: anthropic/skills
+  imported: 2026-03-15
+  version: "3.1.0"
+  windows-setup: See references/windows-setup.md for Windows dependency installation
+  auto_activate: [xlsx, spreadsheet, excel, xlsx-js-style, sheetjs, planilha]
+  file_triggers: [*.xlsx, *.xlsm, *.csv]
+  references:
+    - references/nodejs-sheetjs-styled-reports.md (Node/SheetJS colored reports — colors, CSV BOM, sorting, reconciliation sheets, gotchas)
+---
+
+# Excel Spreadsheet Guide
+
+## CRITICAL: Use Formulas, Not Hardcoded Values
+
+Always use Excel formulas instead of calculating values in Python and hardcoding them. The spreadsheet must remain dynamic and updateable.
+
+```python
+# WRONG - hardcoded
+sheet['B10'] = total
+
+# CORRECT - Excel formula
+sheet['B10'] = '=SUM(B2:B9)'
+```
+
+**Assumptions placement:** All growth rates, margins, and multiples must be in separate assumption cells referenced in formulas, not hardcoded values.
+
+**Documentation:** Hardcoded values require comments with source, date, specific reference, and URL where applicable.
+
+## Professional Standards
+
+### Font
+
+Use a consistent, professional font (Arial, Times New Roman) for all deliverables.
+
+### Template Preservation
+
+When updating existing files, study and EXACTLY match existing format, style, and conventions rather than imposing standardized formatting.
+
+### Zero Formula Errors
+
+Every Excel model MUST be delivered with ZERO formula errors (#REF!, #DIV/0!, #VALUE!, #N/A, #NAME?).
+
+### Financial Color Coding (Industry Standard)
+
+- **Blue text** (0,0,255): Hardcoded inputs
+- **Black text** (0,0,0): ALL formulas and calculations
+- **Green text** (0,128,0): Links from other worksheets
+- **Red text** (255,0,0): External links to other files
+- **Yellow background** (255,255,0): Key assumptions
+
+### Number Formatting
+
+- **Years**: Format as text ("2024" not "2,024")
+- **Currency**: Use $#,##0; specify units in headers ("Revenue ($mm)")
+- **Zeros**: Format as "-"
+- **Percentages**: 0.0% format
+- **Negatives**: Use parentheses (123) not -123
+
+## Workflows
+
+### Reading and Analyzing
+
+```python
+import pandas as pd
+
+df = pd.read_excel('file.xlsx')
+all_sheets = pd.read_excel('file.xlsx', sheet_name=None)
+```
+
+### Creating New Files
+
+```python
+from openpyxl import Workbook
+from openpyxl.styles import Font, PatternFill, Alignment
+
+wb = Workbook()
+sheet = wb.active
+sheet['A1'] = 'Hello'
+sheet['B2'] = '=SUM(A1:A10)'
+sheet['A1'].font = Font(bold=True)
+wb.save('output.xlsx')
+```
+
+### Editing Existing Files
+
+```python
+from openpyxl import load_workbook
+
+wb = load_workbook('existing.xlsx')
+sheet = wb.active
+sheet['A1'] = 'New Value'
+wb.save('modified.xlsx')
+```
+
+### Formula Recalculation (MANDATORY)
+
+After creating or modifying files with formulas, recalculate to update formula values and verify zero errors:
+
+```bash
+python scripts/recalc.py output.xlsx
+```
+
+Alternative using LibreOffice CLI:
+
+```bash
+soffice --headless --calc --convert-to xlsx output.xlsx
+```
+
+## Node.js / SheetJS — Styled Operational Reports
+
+When the spreadsheet is generated by a **Node/JS** script (Firestore/backend exports, admin CLIs)
+and you need **colored, human-scannable operational reports** (not formula models), use SheetJS.
+Full guide + copy-paste patterns: **`references/nodejs-sheetjs-styled-reports.md`**. Reusable
+helpers: **`scripts/styled-report.js`**. The load-bearing rules:
+
+- **The community `xlsx` package cannot write cell colors — it silently drops `cell.s`.** Use the
+  drop-in fork **`xlsx-js-style`** (`npm i xlsx-js-style`; `require('xlsx-js-style')`). Same API.
+- `aoa_to_sheet` takes values only; apply styles **after** via `ws[ref].s` (the "paints" pattern).
+  Create the cell if missing so the fill renders: `if(!ws[ref]) ws[ref]={t:'s',v:''}`.
+- **Reading styles back needs `XLSX.readFile(path, { cellStyles: true })`**, and the read shape is
+  flattened (`cell.s.fgColor.rgb`, not `cell.s.fill.fgColor.rgb`) — dump `JSON.stringify(cell.s)`.
+- **CSV for Excel:** prepend a UTF-8 BOM (`'' + csv`) and quote/escape every cell.
+- **Readability:** IDs in the LAST column, lead with `#1,#2…`; sort completed-by-date, open-by-due-date.
+- **Reconciliation workbook:** detail sheet + correlation MATRIX (rows=A × cols=B = count) + a
+  per-entity X-vs-Y-vs-Δ sheet — the human's tool to see "where the numbers went."
+- **Gotchas:** `EBUSY` = the .xlsx is open in Excel/preview (close it); `new Date(y,m,d)` uses the
+  machine TZ (set `TZ` or use `Intl.DateTimeFormat(...,{timeZone})` for TZ-correct bucketing).
+
+> Color convention: 🟢 green = done/paid · 🔵 blue = open/pending · ⚪ gray = cancelled · slate = sub-headers.
+
+## Library Selection
+
+- **pandas** (Python): Data analysis, bulk operations, simple export
+- **openpyxl** (Python): Complex formatting, formulas, Excel-specific features
+- **xlsx-js-style** (Node): Colored multi-sheet operational reports from JS/Firestore scripts
+- **exceljs** (Node): Advanced Node needs (streaming huge files, charts, conditional formats)
+
+## Formula Verification Checklist
+
+- Test 2-3 sample references before building full model
+- Verify Excel columns match (column 64 = BL, not BK)
+- Remember Excel rows are 1-indexed (DataFrame row 5 = Excel row 6)
+- Handle NaN values with `pd.notna()`
+- Check denominators before division
+- Use correct cross-sheet format (Sheet1!A1)
+
+## Bundled Scripts
+
+| Script                     | Purpose                                                               |
+| -------------------------- | --------------------------------------------------------------------- |
+| `scripts/recalc.py`        | Recalculate formulas and verify zero errors                           |
+| `scripts/styled-report.js` | (Node) Helpers for colored SheetJS reports: PALETTE, painter, CSV+BOM |
+
+**Note:** The shared office toolkit (`unpack.py`, `pack.py`, `validate.py`, `soffice.py`) for XML-level operations lives in `../docx/scripts/office/`.
+
+## Dependencies
+
+- **pandas**: `pip install pandas`
+- **openpyxl**: `pip install openpyxl`
+- **LibreOffice**: Formula recalculation fallback
+- **xlsx-js-style** (Node): `npm install xlsx-js-style` — required for colored cells (the community `xlsx` build silently drops styles)

package/.merlin-core/skills/general/xlsx/references/nodejs-sheetjs-styled-reports.md

@@ -0,0 +1,141 @@
+# Node.js / SheetJS — Styled Operational Reports (data → XLSX + CSV)
+
+> Companion to the Python/openpyxl guidance in `SKILL.md`. Use **this** path when the
+> spreadsheet is generated by a **Node/JS** script (e.g. exporting from Firebase/Firestore,
+> a backend job, or an admin CLI) and you need **colored, human-readable operational reports**
+> — not formula-driven financial models. Values are computed in code; no live formulas.
+
+## Choosing the toolchain
+
+| Need                                                              | Use                                |
+| ----------------------------------------------------------------- | ---------------------------------- |
+| Financial model, live formulas, recalc                            | Python + `openpyxl` (see SKILL.md) |
+| Data dump / operational report from a Node script                 | `xlsx-js-style` (this guide)       |
+| Advanced (streaming huge files, rich charts, conditional formats) | `exceljs`                          |
+
+## ⚠️ The #1 gotcha: community `xlsx` cannot write colors
+
+The community **`xlsx`** (SheetJS) package **silently ignores `cell.s` (styles) on write** — you
+get a file with zero formatting and no error. To produce colored headers/fills you MUST use a
+style-capable build:
+
+```bash
+npm install xlsx-js-style       # drop-in fork: same XLSX.utils API + style support
+```
+
+```js
+const XLSX = require("xlsx-js-style"); // instead of require('xlsx')
+```
+
+Everything else (`aoa_to_sheet`, `book_append_sheet`, `writeFile`, `encode_cell`) is identical.
+
+## The "paints" pattern — coloring `aoa_to_sheet` output
+
+`aoa_to_sheet` builds cells from **values only**; it does not accept pre-styled cell objects.
+Apply styles **after**, by setting `ws[ref].s`. Track which cells to paint while you build the
+array (record `data.length - 1` for each header/title row), then paint in one pass:
+
+```js
+const mkStyle = (rgb, sz = 11) => ({
+  fill: { patternType: "solid", fgColor: { rgb } }, // rgb = 'RRGGBB' (no '#')
+  font: { bold: true, color: { rgb: "FFFFFF" }, sz },
+  alignment: { vertical: "center" },
+});
+
+const data = [];
+const paints = []; // { r, c, style }
+const paintRow = (r, n, style) => {
+  for (let c = 0; c < n; c++) paints.push({ r, c, style });
+};
+
+data.push(["CONCLUÍDAS (12)"]);
+paints.push({ r: data.length - 1, c: 0, style: mkStyle("1B5E20", 12) });
+data.push(["#", "Título", "Data"]);
+paintRow(data.length - 1, 3, mkStyle("2E7D32"));
+// ...push data rows...
+
+const ws = XLSX.utils.aoa_to_sheet(data);
+for (const p of paints) {
+  const ref = XLSX.utils.encode_cell({ r: p.r, c: p.c });
+  if (!ws[ref]) ws[ref] = { t: "s", v: "" }; // create empty cell so the fill renders
+  ws[ref].s = p.style;
+}
+```
+
+### Color convention that reads at a glance
+
+- 🟢 **green** (`2E7D32` / title `1B5E20`) — done / completed / paid
+- 🔵 **blue** (`1565C0` / title `0D47A1`) — open / in-progress / pending
+- ⚪ **gray** (`78909C` / title `455A64`) — cancelled / neutral
+- **slate** (`37474F`) — sub-headers, breakdowns, totals
+
+Distinct section colors are the cheapest way to make a multi-section sheet scannable.
+
+## ⚠️ Verifying styles on READ
+
+`XLSX.readFile(path)` does **not** parse styles by default → `cell.s` is `undefined` even when the
+file is fully styled. Pass `{ cellStyles: true }`. And note the **read shape differs from the write
+shape**: a fill written as `cell.s.fill.fgColor.rgb` comes back flattened as `cell.s.fgColor.rgb`.
+When verifying, dump the whole object instead of trusting your write-path:
+
+```js
+const wb = XLSX.readFile(path, { cellStyles: true });
+console.log(JSON.stringify(wb.Sheets["Sheet1"]["A1"].s)); // don't assume .s.fill.*
+```
+
+## CSV that opens cleanly in Excel
+
+- Prepend a **UTF-8 BOM** so Excel renders accents: `fs.writeFileSync(p, '' + csv, 'utf8')`.
+- Quote every cell and escape inner quotes: `'"' + String(c).replace(/"/g, '""') + '"'`.
+- Join cells with `,` and rows with `\n`.
+
+## Readability patterns for operational reports
+
+- **IDs last, friendly index first.** Put opaque IDs (Firestore doc ids, UUIDs) in the _last_
+  column; lead with a `#1, #2…` sequence (`` `#${i+1}` ``) so humans scan rows, not hashes.
+- **Sort each section by its meaningful date.** Completed → by completion date (chronological,
+  ascending). Open/backlog → by due date ascending (earliest/overdue first; push null dates last
+  with `?? Infinity`).
+- **Multi-sheet reconciliation workbook** — a powerful, reusable shape when two views of the same
+  data must be cross-checked by a human:
+  1. `DETAIL` — one row per item, flat, with all attributes (and a price-/value-ready column).
+  2. `MATRIX` — correlation grid: rows = entity A, cols = entity B, cell = count (+ totals row/col).
+     This is _the_ tool to answer "where did the numbers go" (e.g. which B handled each A).
+  3. `RECONCILIATION` — per entity: metric under model X vs model Y vs Δ, with a one-line note
+     explaining what Δ means. Recompute both models in the same script over the same source rows
+     so the sheet is self-consistent.
+- **Column widths:** `ws['!cols'] = [{ wch: N }, …]` per column index. When you stack tables with
+  _different_ column counts in one sheet, a single `!cols` can't be perfect for all — size for the
+  widest/most-used section and accept the compromise.
+
+## Operational gotchas
+
+- **`EBUSY: resource busy or locked`** on write — Excel (or the Explorer preview pane) holds an
+  exclusive lock on the target `.xlsx`. Close the file before re-running. If you must overwrite a
+  possibly-open file, write to a temp name then `fs.renameSync`.
+- **Timezone** — `new Date(y, m, d)` uses the **machine's local** timezone. If your date-window
+  query must match a dashboard/TV, ensure the machine TZ matches (e.g. `America/Sao_Paulo`) or set
+  the `TZ` env var. For TZ-correct day/month bucketing regardless of the host, derive parts with
+  `Intl.DateTimeFormat('en-CA', { timeZone: 'America/Sao_Paulo' }).formatToParts(date)`.
+- **Date formatting** — `date.toLocaleDateString('pt-BR')` for BR dates; pass
+  `{ timeZone: 'America/Sao_Paulo' }` to keep it deterministic across machines.
+- **Firestore Timestamp → Date** — admin SDK timestamps expose `.toDate()`; serialized ones carry
+  `_seconds`. A safe coercion: `f?.toDate?.() ?? (f?._seconds != null ? new Date(f._seconds*1000) : null)`.
+
+## Bundled helper
+
+`scripts/styled-report.js` (in this skill) exports ready-to-use helpers: `PALETTE`, `mkStyle`,
+`makePainter()`, `applyPaints()`, `toCsvWithBom()`, `toDate()`, `spParts()`. Import it from a Node
+report script to avoid re-deriving the patterns above.
+
+## Real-world example
+
+An example SaaS monthly team-closing report (Firestore → XLSX/CSV):
+
+- `scripts/audit-<month>.js` — dual-credit audit, per-employee sheets, **green CONCLUÍDAS /
+  blue EM ABERTO** section headers, `#n` index, Task ID last, date-sorted sections.
+- `scripts/fechamento-<month>.js` — single-payee "folha" + `FO_BO_MATRIZ` correlation sheet +
+  `RECONCILIACAO` (dual vs single vs Δ).
+  Deps: `firebase-admin`, `xlsx-js-style`. These are concrete, working implementations of every
+  pattern in this guide.
+  </content>

package/.merlin-core/skills/general/xlsx/references/windows-setup.md

@@ -0,0 +1,17 @@
+# Windows Setup for XLSX Tools
+
+## Python
+
+```bash
+pip install pandas openpyxl
+```
+
+## System Dependencies
+
+### LibreOffice (formula recalculation)
+
+1. Download from: https://www.libreoffice.org/download/
+2. Install to default location
+3. Verify: `soffice --version`
+
+LibreOffice is required for the `scripts/recalc.py` formula recalculation step.