rsc-universal 0.1.1

package/skills/replicate-images/scripts/verify.sh

@@ -0,0 +1,178 @@
+#!/usr/bin/env bash
+#
+# verify.sh — static lint for Replicate image-generation code (read-only, network-free).
+#
+# WHAT IT DOES (never edits, runs code, or calls the API)
+#   Points at a directory of emitted code (default: current dir) and statically
+#   checks the things that are mechanically wrong about a Replicate image call:
+#     1. Image model slugs -> every replicate.run("<slug>") / predictions.create
+#        model:/version: "<slug>" must be in the known image-slug allowlist
+#        (the slugs in references/models.md). An unknown slug is a HARD failure
+#        (likely a typo or a hallucinated model).
+#     2. aspect_ratio literals -> every aspect_ratio: "<v>" must be in the
+#        nano-banana allowed set (or match_input_image). HARD failure otherwise.
+#     3. output_resolution literals -> must be one of 512px,1K,2K,4K. HARD fail.
+#     4. Bare-path image inputs -> an image_input array element that is a quoted
+#        relative path ("./x.png" / "x.jpg") rather than a variable/URL/data:
+#        URI warns (clients upload files/Buffers, not path strings).
+#
+#   A dir with no matching code (nothing to check) exits 0 — never a false fail.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh                 # check current directory, recursively
+#   ./verify.sh path/to/dir     # check a specific dir
+#   ./verify.sh dir --strict    # treat warnings as failures (CI gate)
+#
+# EXIT CODES
+#   0  clean, warnings-only (without --strict), or nothing to check
+#   1  a hard failure (unknown slug / bad aspect_ratio / bad resolution),
+#      or any warning under --strict
+#   2  bad usage (target dir does not exist)
+#
+# Runs on stock macOS bash 3.2.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+warn_count=0; fail_count=0
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+usage() { sed -n '2,40p' "$0" | sed 's/^# \{0,1\}//'; }
+
+DIR="."
+STRICT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help) usage; exit 0 ;;
+    --strict) STRICT=1; shift ;;
+    -*) printf '%sunknown option: %s%s\n' "$RED" "$1" "$NC" >&2; usage; exit 2 ;;
+    *) DIR="$1"; shift ;;
+  esac
+done
+
+if [ ! -d "$DIR" ]; then
+  printf '%starget dir not found: %s%s\n' "$RED" "$DIR" "$NC" >&2; exit 2
+fi
+
+printf 'replicate-images verify — %s\n\n' "$DIR"
+
+# Known image slugs (from references/models.md). Space-padded for whole-token match.
+ALLOWED_SLUGS=" google/nano-banana-2 google/nano-banana-pro black-forest-labs/flux-1.1-pro black-forest-labs/flux-dev black-forest-labs/flux-schnell openai/gpt-image-1 bytedance/seedream-4 "
+# nano-banana aspect_ratio allowed set + match_input_image (the spec list on the model page;
+# extreme 1:4/4:1/1:8/8:1 are unconfirmed in that spec, so they are intentionally NOT allowed here).
+ALLOWED_AR=" 1:1 2:3 3:2 3:4 4:3 4:5 5:4 9:16 16:9 21:9 match_input_image "
+# output_resolution allowed set.
+ALLOWED_RES=" 512px 1K 2K 4K "
+
+# Collect candidate source files (skip references/models.md itself: it lists the allowlist as prose).
+SRC="$(find "$DIR" \( -name '*.js' -o -name '*.mjs' -o -name '*.ts' -o -name '*.py' \) 2>/dev/null || true)"
+
+checked_anything=0
+
+# --- 1. model slugs -----------------------------------------------------------
+SLUGS="$(printf '%s\n' "$SRC" | while IFS= read -r f; do
+  [ -n "$f" ] && [ -f "$f" ] || continue
+  grep -hoE '(replicate\.run|model|version)[^"'"'"']*["'"'"'][a-z0-9._-]+/[a-z0-9._-]+["'"'"']' "$f" 2>/dev/null \
+    | grep -oE '["'"'"'][a-z0-9._-]+/[a-z0-9._-]+["'"'"']' \
+    | tr -d '"'"'"''
+done | sort -u || true)"
+
+if [ -n "$SLUGS" ]; then
+  checked_anything=1
+  while IFS= read -r s; do
+    [ -n "$s" ] || continue
+    case "$ALLOWED_SLUGS" in
+      *" $s "*) ok "model slug ok: $s" ;;
+      *) fail "unknown image model slug: '$s' (not in references/models.md allowlist)" ;;
+    esac
+  done <<EOF
+$SLUGS
+EOF
+fi
+
+# --- 2. aspect_ratio literals -------------------------------------------------
+ARS="$(printf '%s\n' "$SRC" | while IFS= read -r f; do
+  [ -n "$f" ] && [ -f "$f" ] || continue
+  grep -hoE 'aspect_ratio["'"'"']?[[:space:]]*[:=][[:space:]]*["'"'"'][^"'"'"']+["'"'"']' "$f" 2>/dev/null \
+    | grep -oE '["'"'"'][^"'"'"']+["'"'"']$' | tr -d '"'"'"''
+done | sort -u || true)"
+
+if [ -n "$ARS" ]; then
+  checked_anything=1
+  while IFS= read -r a; do
+    [ -n "$a" ] || continue
+    case "$ALLOWED_AR" in
+      *" $a "*) ok "aspect_ratio ok: $a" ;;
+      *) fail "aspect_ratio '$a' not in the nano-banana allowed set" ;;
+    esac
+  done <<EOF
+$ARS
+EOF
+fi
+
+# --- 3. output_resolution literals --------------------------------------------
+RESS="$(printf '%s\n' "$SRC" | while IFS= read -r f; do
+  [ -n "$f" ] && [ -f "$f" ] || continue
+  grep -hoE 'output_resolution["'"'"']?[[:space:]]*[:=][[:space:]]*["'"'"'][^"'"'"']+["'"'"']' "$f" 2>/dev/null \
+    | grep -oE '["'"'"'][^"'"'"']+["'"'"']$' | tr -d '"'"'"''
+done | sort -u || true)"
+
+if [ -n "$RESS" ]; then
+  checked_anything=1
+  while IFS= read -r r; do
+    [ -n "$r" ] || continue
+    case "$ALLOWED_RES" in
+      *" $r "*) ok "output_resolution ok: $r" ;;
+      *) fail "output_resolution '$r' not in {512px,1K,2K,4K}" ;;
+    esac
+  done <<EOF
+$RESS
+EOF
+fi
+
+# --- 4. bare-path image_input warning -----------------------------------------
+BAREPATH="$(printf '%s\n' "$SRC" | while IFS= read -r f; do
+  [ -n "$f" ] && [ -f "$f" ] || continue
+  # image_input on the same line containing a quoted relative path with an image extension
+  grep -nE 'image_input' "$f" 2>/dev/null \
+    | grep -E '["'"'"'](\./|\.\./)?[A-Za-z0-9._/-]+\.(png|jpg|jpeg|webp|gif)["'"'"']' \
+    | grep -vE 'https?://|data:' \
+    | sed "s|^|$f:|"
+done || true)"
+
+if [ -n "$BAREPATH" ]; then
+  checked_anything=1
+  while IFS= read -r line; do
+    [ -n "$line" ] && warn "possible bare-path image input: ${line} — read the file (readFile/Buffer) or pass a URL/data: URI"
+  done <<EOF
+$BAREPATH
+EOF
+fi
+
+# --- summary ------------------------------------------------------------------
+printf '\n'
+if [ "$checked_anything" -eq 0 ] && [ "$fail_count" -eq 0 ]; then
+  ok "nothing to check in $DIR"
+  exit 0
+fi
+if [ "$fail_count" -gt 0 ]; then
+  printf '%s%d hard failure(s), %d warning(s)%s\n' "$RED" "$fail_count" "$warn_count" "$NC"
+  exit 1
+fi
+if [ "$warn_count" -gt 0 ]; then
+  if [ "$STRICT" -eq 1 ]; then
+    printf '%s%d warning(s) — failing under --strict%s\n' "$YELLOW" "$warn_count" "$NC"
+    exit 1
+  fi
+  printf '%s%d warning(s), 0 hard failures%s\n' "$YELLOW" "$warn_count" "$NC"
+  exit 0
+fi
+printf '%sall checks passed%s\n' "$GREEN" "$NC"
+exit 0

package/skills/reporting/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: reporting
+description: "Use when you need a recurring report that ships to stakeholders on a cadence — a weekly team digest, monthly exec pack, quarterly board summary, or recurring client performance report — and it must go out reliably without a human in the loop. Symptoms: a standing metrics email keeps breaking or shows stale numbers, the Monday digest is hand-assembled every week, leadership asks for 'the same report but every month', or a client expects a PDF on a schedule. Triggers: 'set up a weekly automated report emailed to the exec team', 'build a monthly PDF report for our biggest client on a schedule', 'send the board a quarterly summary every quarter', 'our Monday metrics email keeps going out with last week's numbers — make it reliable', 'automatiza un informe mensual para dirección', 'munta un informe setmanal automàtic per al comitè'. NOT a live screen people open to slice metrics (that is dashboard), NOT deciding which KPIs to track (that is kpi-framework), NOT a one-off investigation (that is analytics)."
+tags: [reporting, automated-reports, recurring, stakeholder-reporting, scheduled-delivery, data-analytics]
+recommends: [dashboard, kpi-framework, analytics, automation-flows, email-connector, spreadsheet-ops, google-workspace, notion-connector, github-actions]
+origin: risco
+---
+
+# reporting — the standing artifact that ships itself
+
+A report is a **push** artifact: a fixed snapshot that lands in someone's inbox or shared drive on a
+cadence, the same shape every period, with no human assembling it. That is the whole job. If a human
+opens a live view to slice numbers themselves, that is **pull** — a dashboard, not a report. Hold that
+line; almost every failed "reporting" project is a dashboard wearing a report's name, or a report
+nobody can trust because the numbers went stale and no one noticed.
+
+Your deliverable is a **runnable pipeline**, not advice: a template, a generation script, a schedule,
+and a delivery step, with a freshness gate so it fails loud instead of shipping yesterday's numbers.
+
+## Step 0 — Write the report contract (no contract, no build)
+
+Before any code, pin six fields. An undefined audience is a report no one reads; an undefined source
+is a number no one can defend.
+
+| Field | What it fixes | Example |
+| --- | --- | --- |
+| **Audience** | Who reads it → sets depth and tone | "5-person leadership team" |
+| **Cadence** | When it ships → sets the scheduler | "every Monday 08:00 Europe/Madrid" |
+| **Sections** | The fixed skeleton, same every period | Exec summary · revenue · pipeline · risks |
+| **Metric source** | Where numbers come from + **who owns them** | `metrics.csv` from the data team |
+| **Channel** | The artifact + transport | PDF over email |
+| **Owner** | Who gets paged when it breaks | a named person, not "the team" |
+
+Rule: you **consume** an agreed metric set — you do not adjudicate which KPIs matter. If the ask is
+"which metrics should we even track?", that is kpi-framework, not this skill. The contract names the
+source and its owner so a wrong number has an address.
+
+## Decide: push report vs live dashboard (this branches — settle it first)
+
+Audiences want a consistent, citable snapshot for the period far more often than a live feed; that is
+why scheduled push beats a dashboard for exec summaries, weekly reviews, and finance close packs.
+
+| Signal in the ask | Route |
+| --- | --- |
+| "Same summary, every week/month/quarter" | **reporting** (here) |
+| "Consistent snapshot the board can cite in a meeting" | **reporting** (here) |
+| "It must arrive even if no one logs in" | **reporting** (here) |
+| "A screen people open to filter/drill live" | **dashboard** |
+| "Self-serve, slice by region/date on demand" | **dashboard** |
+
+When both are wanted, build the report; let it link to the dashboard as a "go deeper" footer. Do not
+email a dashboard link and call it a report — see the anti-patterns table.
+
+## Pick the artifact format
+
+| Format | Wins when | Notes |
+| --- | --- | --- |
+| **Email-body HTML** | Short digest, ≤1 screen, read on a phone | Inline the key numbers; no attachment to open |
+| **PDF** | Exec / client / board, fixed layout that must look identical for everyone | The default for anything formal; pinned render stack below |
+| **Spreadsheet** | Analysts who will re-filter and pivot the data themselves | Hand off the data, not a picture → [`spreadsheet-ops`](../spreadsheet-ops/SKILL.md) |
+| **Notion / living doc** | Internal team, the doc evolves and gets commented | Page over file → [`notion-connector`](../notion-connector/SKILL.md) |
+
+A board pack is a PDF; an analyst hand-off is a spreadsheet. Picking PDF for analysts who wanted to
+pivot is the most common format miss.
+
+## The four-layer pipeline: fetch → narrate → render → deliver
+
+Keep the four layers separate so each is testable and the template never knows where data came from.
+
+**Pinned stack** (Python, the most-documented 2025 PDF path — verified on PyPI 2026-06-02):
+`pandas` (data) → `Jinja2` (HTML template) → `WeasyPrint` **68.1** (HTML+CSS → PDF), `Matplotlib`
+for embedded charts. Pin WeasyPrint — major versions change CSS support, so an unpinned bump can
+silently reflow a board pack. Re-check PyPI before you freeze, then freeze what you resolve.
+
+```python
+# render.py — minimal fetch → narrate → render. Delivery + charts live in references/pipeline.md.
+import pandas as pd
+from jinja2 import Environment, FileSystemLoader
+from weasyprint import HTML  # WeasyPrint==68.1
+
+def build_report(metrics_csv: str, params: dict) -> bytes:
+    df = pd.read_csv(metrics_csv)                      # fetch
+    df = df[df["region"] == params["region"]]          # per-recipient scope, NOT a new template
+    cur, prev = df["revenue"].iloc[-1], df["revenue"].iloc[-2]
+    ctx = {
+        "title": f'{params["region"]} weekly revenue',
+        "period": params["period"],
+        "summary": narrate(cur, prev),                 # narrate (see below)
+        "rows": df.tail(8).to_dict("records"),
+    }
+    env = Environment(loader=FileSystemLoader("templates"))
+    html = env.get_template("report.html.j2").render(**ctx)   # render
+    return HTML(string=html).write_pdf()
+```
+
+Rule: **one template, per-recipient params** — regional managers each get their region from the same
+`report.html.j2`, scoped by `params`, never a forked template per recipient. A template-per-recipient
+codebase rots the first time the layout changes. The full worked template, the Matplotlib base64 chart
+embed, the per-recipient loop, the GitHub Actions workflow, and the freshness gate are in
+[`references/pipeline.md`](references/pipeline.md).
+
+## The narrative layer (the part that gets read)
+
+Executives read the **executive summary and stop**. Lead every report with: the report's purpose in
+one line, **3 key takeaways**, and **what changed versus last period**. Then per section, one
+period-over-period delta sentence and one "so what". An annotated chart callout is retained; a bare
+chart is not.
+
+```python
+def narrate(cur: float, prev: float) -> str:
+    delta = (cur - prev) / prev * 100
+    arrow = "up" if delta >= 0 else "down"
+    flag = " — investigate" if abs(delta) >= 20 else ""    # anomaly callout
+    return (f"Revenue {arrow} {abs(delta):.1f}% vs last week "
+            f"(€{cur:,.0f} from €{prev:,.0f}){flag}.")
+```
+
+Bad → Good, the difference that decides whether the report is useful:
+
+- **Bad:** a table row `Revenue | 248,300 | 201,400`. The reader must do the math and guess if it matters.
+- **Good:** "Revenue up 23.3% WoW (€248,300 from €201,400) — investigate: driven by the enterprise renewal that won't recur next week."
+
+Never ship a raw metric dump with no narrative. The numbers are the evidence; the sentence is the report.
+
+## Schedule + reliability gate (where reports actually die)
+
+Reports die two ways: **stale data** ships silently, and **a silent break** means no one notices for
+weeks. Treat the schedule as managed infrastructure.
+
+**Where to run it:**
+
+| Situation | Scheduler |
+| --- | --- |
+| You already run a server / cron host | **cron** (`0 8 * * 1` = Mondays 08:00) |
+| No server, want zero infra | **GitHub Actions** `on: schedule: - cron:` — the recommended cloud option |
+| Multi-app event wiring beyond a timer | route the plumbing to [`automation-flows`](../automation-flows/SKILL.md) |
+
+This skill owns the report-shaped concern (contract, narrative, artifact) and *uses* a scheduler — it
+does not teach scheduling in general. The actual transport (SMTP/Gmail send) belongs to
+[`email-connector`](../email-connector/SKILL.md); for a Drive/Workspace destination see
+[`google-workspace`](../google-workspace/SKILL.md). The GH Actions `schedule:` YAML is in
+[`references/pipeline.md`](references/pipeline.md).
+
+**Reliability checklist — every recurring report:**
+
+- [ ] **Freshness gate before send** — assert the source is newer than the last period; if stale, do
+      NOT send, raise instead. A report that consumes dirty data is not this skill's job to clean —
+      that is data-cleaning; this gate only refuses to ship known-stale numbers.
+- [ ] **Fail loud** — on any error, alert the owner (the report not arriving is itself a silent failure).
+- [ ] **Idempotent run** — re-running for the same period produces the same artifact, no duplicate send.
+- [ ] **Dead-report cleanup** — if no one opened the last N editions, kill the schedule. Unread reports
+      are pure cost and noise.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| Email a live dashboard link, call it "the report" | Recipient must log in and slice; most won't, the snapshot is lost | Ship the fixed artifact; link the dashboard as a footer |
+| No freshness gate | Stale numbers ship silently; trust dies on the first wrong figure | Assert source newer than last period; refuse to send if stale |
+| One mega-report for every audience | Execs drown in analyst detail; analysts can't refilter a PDF | Contract per audience; one template, per-recipient params |
+| Raw metric dump, no narrative | Reader does the math, misses what changed, stops opening it | Exec summary + 3 takeaways + a "so what" per section |
+| Schedule with no failure alert | A broken job is invisible for weeks; the report just stops | Fail loud to the named owner on any error |
+| A template forked per recipient | Layout change must be made N times; they drift | Single template scoped by `params` |
+| Redefining KPIs inside the report | The report quietly becomes the metric authority, numbers diverge | Consume an agreed set; defer definition to kpi-framework |
+| Unpinned WeasyPrint / render lib | A minor bump reflows the board pack with no warning | Pin (WeasyPrint 68.1) and re-check PyPI before changing |
+| Hand-assembling the digest weekly | It breaks the week the owner is on leave | Automate the pipeline end to end; a human only reads it |
+
+## Verify
+
+Run `scripts/verify.sh` (read-only; pass a path to a generated pipeline directory, or run in it). It
+confirms a Jinja2 template exists and renders against a sample context without error, that the
+generation script produces a non-empty PDF/HTML artifact, that a schedule definition exists (a crontab
+line or a `.github/workflows/*.yml` with a `schedule:` block), and that a delivery step is wired. It
+soft-warns if no freshness/failure gate is detected. On an empty/clean target it exits 0 — nothing to
+check is not a failure.
+
+References: [`pipeline.md`](references/pipeline.md) — full template, chart embed, per-recipient loop,
+GitHub Actions `schedule:` YAML, freshness gate, and failure alert.

package/skills/reporting/evals/README.md

@@ -0,0 +1,12 @@
+# reporting — evals
+
+These cases are run by the skill-eval harness, not by a bundled scorer here. `should_trigger` and
+`should_not_trigger` check routing: each `should_trigger` prompt should select this skill (read the
+`why` to see what makes it reporting, including the non-obvious "stale Monday email" case and the
+Spanish/Catalan phrasings), and each `should_not_trigger` prompt should route to the named real
+sibling (`route_to`) instead of being absorbed here — the boundaries against dashboard, kpi-framework,
+analytics, forecasting, data-cleaning, and automation-flows are the whole point. The single
+`capability` case is rubric-scored by a judge: a passing answer must hit every item in `must_include`
+(report contract, template/params separation, pinned render stack, narrative layer, schedule,
+freshness + failure gate, and correct routing of out-of-scope asks). There is no automated pass/fail
+script — read each `why`/`route_to` and the rubric to grade by hand or feed them to the harness.

package/skills/reporting/evals/cases.yaml

@@ -0,0 +1,46 @@
+skill: reporting
+
+should_trigger:
+  - prompt: "Set up a weekly automated performance report emailed to our exec team."
+    why: "Core push report — recurring cadence, fixed audience, delivered without a human. The center of this skill."
+  - prompt: "Build a monthly PDF report for our biggest client, on a schedule."
+    why: "Recurring client-facing report + artifact format (PDF) + cadence — fetch→narrate→render→deliver pipeline."
+  - prompt: "Send the board a quarterly summary PDF every quarter, automatically."
+    why: "Cadence + formal artifact + push delivery; the quarterly board pack is a canonical reporting case."
+  - prompt: "Automatiza un informe mensual para dirección."
+    why: "Spanish for 'automate a monthly report for leadership' — recurring stakeholder report, must route here."
+  - prompt: "Munta un informe setmanal automàtic per al comitè."
+    why: "Catalan for 'build an automatic weekly report for the committee' — recurring push report."
+  - prompt: "Our Monday metrics email keeps going out with last week's numbers — make it reliable."
+    why: "Non-obvious: framed as a bug, but it is report-pipeline reliability (freshness gate, fail-loud) — squarely reporting, not a generic email fix."
+
+should_not_trigger:
+  - prompt: "Build an interactive dashboard the team can open to slice sales by region."
+    route_to: dashboard
+    why: "Pull/live surface the user opens and filters — not a push artifact on a cadence."
+  - prompt: "Which KPIs should we even be tracking for the growth team?"
+    route_to: kpi-framework
+    why: "Deciding which metrics matter / defining the metric tree — reporting consumes an agreed set, it does not adjudicate it."
+  - prompt: "Dig into why signups dropped last Tuesday."
+    route_to: analytics
+    why: "One-off investigation to answer a question, not a recurring standing artifact."
+  - prompt: "Forecast next quarter's revenue from this history."
+    route_to: forecasting
+    why: "Predicting future values / projections — reporting reports what happened, it does not predict."
+  - prompt: "Our source CSV has duplicate and malformed rows — clean it."
+    route_to: data-cleaning
+    why: "Fixing dirty source data — reporting assumes a trustworthy source and only gates on freshness, it does not clean."
+  - prompt: "Just wire up a generic cron job that runs this script nightly."
+    route_to: automation-flows
+    why: "Generic scheduling/plumbing for any job with no report shape — reporting uses a scheduler but does not teach scheduling-in-general."
+
+capability:
+  - scenario: "Set up a recurring weekly revenue report, delivered as a PDF emailed to the leadership team every Monday at 08:00, sourced from a metrics CSV."
+    must_include:
+      - "Defines a report contract: audience, cadence, sections, metric source (and who owns the numbers), channel, owner."
+      - "Separates the template from per-recipient params (one Jinja2 template scoped by params, not a forked template per recipient)."
+      - "Uses a pinned render stack (pandas → Jinja2 → WeasyPrint 68.1, Matplotlib for charts) and states the pin."
+      - "Writes a narrative/executive-summary layer (purpose + 3 takeaways + what changed vs last period), not just a raw metric table."
+      - "Schedules it via cron or GitHub Actions schedule:, and notes GH Actions cron is UTC."
+      - "Includes a freshness gate before send and a fail-loud failure alert to the named owner."
+      - "Routes KPI-definition to kpi-framework and any live-view/slice request to dashboard rather than absorbing them; defers transport to email-connector."

package/skills/reporting/references/pipeline.md

@@ -0,0 +1,213 @@
+# reporting — full worked pipeline
+
+The four layers end to end: **fetch → narrate → render → deliver**, plus schedule and reliability
+gate. Pinned stack as of 2026-06-02: `pandas`, `Jinja2`, `WeasyPrint==68.1`, `Matplotlib`. Re-check
+PyPI and pin what you resolve.
+
+```text
+report/
+  templates/report.html.j2     # one template, scoped by params
+  metrics.csv                  # the agreed source (owned by the data team)
+  render.py                    # fetch → narrate → render
+  deliver.py                   # render → deliver (calls email-connector / google-workspace)
+  recipients.yaml              # per-recipient params, NOT forked templates
+  requirements.txt             # pandas, jinja2, weasyprint==68.1, matplotlib, pyyaml
+  .github/workflows/report.yml # the schedule (zero-infra option)
+```
+
+## 1. The Jinja2 template skeleton
+
+```html
+<!-- templates/report.html.j2 -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<style>
+  @page { size: A4; margin: 18mm; }
+  body { font: 11pt/1.45 "Helvetica Neue", Arial, sans-serif; color: #1a1a1a; }
+  h1 { font-size: 20pt; margin: 0 0 2mm; }
+  .summary { background: #f4f6f8; border-left: 4px solid #2563eb; padding: 4mm 5mm; }
+  table { width: 100%; border-collapse: collapse; margin-top: 6mm; font-size: 10pt; }
+  th, td { text-align: left; padding: 2mm 3mm; border-bottom: 1px solid #e2e8f0; }
+  .delta-up { color: #15803d; } .delta-down { color: #b91c1c; }
+</style>
+</head>
+<body>
+  <h1>{{ title }}</h1>
+  <p><strong>Period:</strong> {{ period }}</p>
+
+  <section class="summary">
+    <h2>Executive summary</h2>
+    <p>{{ summary }}</p>
+    <ul>{% for t in takeaways %}<li>{{ t }}</li>{% endfor %}</ul>
+  </section>
+
+  {% if chart_b64 %}<img src="data:image/png;base64,{{ chart_b64 }}" style="width:100%">{% endif %}
+
+  <table>
+    <thead><tr><th>Week</th><th>Revenue</th><th>WoW</th></tr></thead>
+    <tbody>
+      {% for r in rows %}
+      <tr>
+        <td>{{ r.week }}</td><td>€{{ "{:,.0f}".format(r.revenue) }}</td>
+        <td class="{{ 'delta-up' if r.wow >= 0 else 'delta-down' }}">{{ "%+.1f"|format(r.wow) }}%</td>
+      </tr>
+      {% endfor %}
+    </tbody>
+  </table>
+</body>
+</html>
+```
+
+## 2. Render: fetch → narrate → render (WeasyPrint pinned)
+
+```python
+# render.py
+import base64, io
+import pandas as pd
+import matplotlib
+matplotlib.use("Agg")                      # headless: no display needed in CI
+import matplotlib.pyplot as plt
+from jinja2 import Environment, FileSystemLoader
+from weasyprint import HTML                 # WeasyPrint==68.1
+
+def chart_png_b64(df: pd.DataFrame) -> str:
+    fig, ax = plt.subplots(figsize=(8, 2.6))
+    ax.plot(df["week"], df["revenue"], marker="o")
+    ax.set_title("Revenue by week"); ax.grid(True, alpha=0.3)
+    peak = df["revenue"].idxmax()           # annotate the anomaly, don't ship a bare chart
+    ax.annotate("peak", (df["week"][peak], df["revenue"][peak]),
+                textcoords="offset points", xytext=(0, 8))
+    buf = io.BytesIO(); fig.savefig(buf, format="png", bbox_inches="tight", dpi=130)
+    plt.close(fig)
+    return base64.b64encode(buf.getvalue()).decode()
+
+def narrate(cur: float, prev: float) -> tuple[str, list[str]]:
+    delta = (cur - prev) / prev * 100
+    flag = " — investigate" if abs(delta) >= 20 else ""
+    summary = (f"Revenue {'up' if delta >= 0 else 'down'} {abs(delta):.1f}% WoW "
+               f"(€{cur:,.0f} from €{prev:,.0f}){flag}.")
+    takeaways = [summary, "Pipeline coverage holding at 3.1x.", "No SLA breaches this period."]
+    return summary, takeaways
+
+def build_pdf(df: pd.DataFrame, params: dict) -> bytes:
+    df = df[df["region"] == params["region"]].reset_index(drop=True)
+    df["wow"] = df["revenue"].pct_change() * 100
+    cur, prev = df["revenue"].iloc[-1], df["revenue"].iloc[-2]
+    summary, takeaways = narrate(cur, prev)
+    env = Environment(loader=FileSystemLoader("templates"), autoescape=True)
+    html = env.get_template("report.html.j2").render(
+        title=f'{params["region"]} weekly revenue', period=params["period"],
+        summary=summary, takeaways=takeaways, chart_b64=chart_png_b64(df),
+        rows=df.tail(8).to_dict("records"),
+    )
+    return HTML(string=html).write_pdf()     # 68.1: stable A4/@page CSS
+```
+
+## 3. Per-recipient parameterization (one template, many scopes)
+
+```yaml
+# recipients.yaml — same template, audience-scoped params
+- email: emea-lead@acme.com
+  region: EMEA
+  period: "2026-W22"
+- email: amer-lead@acme.com
+  region: AMER
+  period: "2026-W22"
+```
+
+```python
+# deliver.py — render once per recipient, hand the bytes to email-connector
+import yaml, pandas as pd
+from render import build_pdf
+# from email_connector import send  # transport is email-connector's job, not this skill's
+
+def main():
+    df = pd.read_csv("metrics.csv", parse_dates=["updated_at"])
+    freshness_gate(df, period="2026-W22")            # see §5 — refuse stale before any send
+    for r in yaml.safe_load(open("recipients.yaml")):
+        pdf = build_pdf(df, r)
+        assert pdf and len(pdf) > 1024, "empty PDF — refusing to send"
+        # send(to=r["email"], subject=f'Weekly revenue — {r["region"]}',
+        #      body="Your weekly report is attached.", attachments=[("report.pdf", pdf)])
+
+if __name__ == "__main__":
+    main()
+```
+
+## 4. Schedule
+
+**cron** (you already run a host):
+
+```cron
+# /etc/cron.d/weekly-revenue — Mondays 08:00, log everything, owner gets stderr by mail
+0 8 * * 1 reportbot cd /opt/report && python deliver.py >> /var/log/report.log 2>&1
+```
+
+**GitHub Actions** (zero infra — the recommended cloud option):
+
+```yaml
+# .github/workflows/report.yml
+name: weekly-revenue-report
+on:
+  schedule:
+    - cron: "0 6 * * 1"        # 06:00 UTC ≈ 08:00 Europe/Madrid; cron here is always UTC
+  workflow_dispatch: {}        # manual re-run for testing
+jobs:
+  report:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install -r requirements.txt   # weasyprint==68.1 pinned here
+      - run: sudo apt-get update && sudo apt-get install -y libpango-1.0-0 libpangoft2-1.0-0
+      - run: python deliver.py
+        env:
+          SMTP_TOKEN: ${{ secrets.SMTP_TOKEN }}   # transport secret, owned by email-connector
+```
+
+Note: GitHub Actions `schedule:` cron is **UTC only** and may lag a few minutes under load — never
+schedule a report to the exact minute it is "due"; give it slack.
+
+## 5. Reliability gate
+
+```python
+# freshness + fail-loud. A report that ships stale numbers is worse than one that doesn't ship.
+from datetime import datetime, timedelta, timezone
+
+def freshness_gate(df, period: str, max_age_hours: int = 26):
+    latest = df["updated_at"].max()
+    if latest.tzinfo is None:
+        latest = latest.tz_localize("UTC")
+    age = datetime.now(timezone.utc) - latest.to_pydatetime()
+    if age > timedelta(hours=max_age_hours):
+        raise RuntimeError(
+            f"STALE SOURCE: newest row is {age} old (> {max_age_hours}h) for {period}. "
+            f"Refusing to send. Page the source owner — do NOT clean the data here (data-cleaning)."
+        )
+```
+
+```python
+# Wrap the whole run so a failure pages the owner instead of failing silently.
+import sys, traceback
+def run_guarded(fn, owner_alert):
+    try:
+        fn()
+    except Exception as exc:           # noqa: BLE001 — we want everything
+        owner_alert(f"REPORT FAILED: {exc}\n{traceback.format_exc()}")
+        sys.exit(1)                    # non-zero so the scheduler also flags it
+```
+
+**Dead-report cleanup:** if delivery telemetry shows the last N editions went unopened, stop the
+schedule and notify the owner. An unread recurring report is pure cost and inbox noise — killing it is
+part of owning the report, not a failure.
+
+## Boundary reminders
+
+- The **transport** (SMTP/Gmail/Drive upload) is [`email-connector`](../../email-connector/SKILL.md)
+  / [`google-workspace`](../../google-workspace/SKILL.md) — this pipeline calls it, never reimplements it.
+- **Spreadsheet output** for analysts → [`spreadsheet-ops`](../../spreadsheet-ops/SKILL.md).
+- **Notion / living-doc destination** → [`notion-connector`](../../notion-connector/SKILL.md).
+- **Generic multi-step job wiring** beyond the report → [`automation-flows`](../../automation-flows/SKILL.md).