rsc-universal 0.1.1

package/skills/webinar/references/email-cadence.md

@@ -0,0 +1,75 @@
+# Email cadence — promotion, reminders, segmented follow-up
+
+The single dated schedule the SKILL.md points to: T-28d through T+7d. Each row carries
+its purpose and the funnel metric it moves. Adjust the calendar to your event date;
+keep the relative spacing.
+
+## Phase 1 — Promotion (T-28d → T-1d)
+
+Start ~4 weeks out. Email is the dominant channel (~86% of teams); pair every email
+with organic, and turn on paid social from ~T-14d. Metric moved: **registration count**.
+
+| When | Touch | Purpose |
+|---|---|---|
+| T-28d | Announce (email + organic) | open registration; the single promise |
+| T-21d | Value teaser (email) | preview one belief-shift; turn on paid social |
+| T-14d | Social proof (email + organic) | a past result or agenda reveal |
+| T-7d | Urgency (email) | "one week left", second push |
+| T-3d | Personal note (email) | host's reason this matters now |
+| T-1d | Last call (all channels) | final registration push |
+
+## Phase 2 — Reminders (confirmation → 5-min before)
+
+The show-up lever. Day-of reminders drive ~38% of total live attendance; the 5-min
+email is the single biggest boost. SMS on the last two touches lifts
+registrant→attendee from ~56% to as high as 71%. Metric moved: **show-up rate**.
+
+| When | Touch | Purpose |
+|---|---|---|
+| On registration | Confirmation (email) | calendar invite + what to expect + add-to-calendar |
+| T-24h | Reminder (email) | the one thing live has that replay won't |
+| T-1h | Reminder (email + SMS) | join link, "starts in 1 hour" |
+| T-5min | Going live (email + SMS) | join link, "we're live now" — biggest single lever |
+
+## Phase 3 — Segmented follow-up (T+0 → T+7d)
+
+Conversion is segment-specific; open rates halve after 48h (~58% within 24h → ~31%
+after 48h). First touch in 0–24h, then 2–4 touches over 5–7 days. ~25% of sales close
+post-event. Metric moved: **conversion rate** (and recovered pipeline).
+
+### Engaged attendee (converts ~12–15%)
+
+| When | Touch | Purpose |
+|---|---|---|
+| T+0–4h | Direct ask (email) | book the call / claim the offer before deadline |
+| T+1d | Recap + proof (email) | restate the offer, one testimonial |
+| T+3d | Deadline (email) | the close window is ending |
+
+### Passive attendee (converts ~3–5%)
+
+| When | Touch | Purpose |
+|---|---|---|
+| T+0–24h | Replay + objection (email) | replay link + the likely objection, then offer |
+| T+2d | Value nudge (email) | the resource CTA they didn't claim |
+| T+5d | Soft offer (email) | lower-commitment next step |
+
+### No-show registrant (converts ~2–3%)
+
+| When | Touch | Purpose |
+|---|---|---|
+| T+0–24h | "You missed it" (email) | replay link, time-boxed access |
+| T+3d | Last chance replay (email) | replay expiring + the offer |
+
+### Replay-only viewer
+
+| When | Touch | Purpose |
+|---|---|---|
+| On watch | Offer + deadline (email) | matched lower-commitment next step |
+
+## Hand-offs
+
+- Recurring nurture for everyone who didn't convert this cycle → the newsletter program.
+- Deals the webinar generated → the sales pipeline.
+- Programmatic sends / transport → email-connector; calendar invites → calendar-scheduling.
+
+You own only the 0–72h conversion window after the event.

package/skills/webinar/references/run-of-show.md

@@ -0,0 +1,83 @@
+# Run-of-show — annotated timed template
+
+The full template the SKILL.md skeleton points to. Timings assume a ~60-minute live
+webinar selling a single offer. Scale blocks proportionally for shorter/longer slots.
+The stack changes by offer type — notes at the end.
+
+## The principle
+
+The opening story plus the teaching should do ~80% of the selling. By the time you
+reach the offer, the audience should already believe they need it; the ask is then a
+small step, not a leap. Reverse-build every block from the offer line you wrote first.
+
+## Timed blocks
+
+```text
+00:00–05:00  HOOK
+  - The big promise, stated once, plainly. "By the end of this hour you'll know X."
+  - The story: a specific before→after (yours or a student's). Concrete numbers.
+  - First poll inside minute 5 — sets the norm that this room participates.
+  - Name the agenda in one line so they know the pitch is coming (no ambush).
+
+05:00–40:00  TEACHING — one block per false belief (2–3 blocks)
+  Block 1: false belief → why it's wrong → the true mechanism → proof.
+  Block 2: same shape, the next belief in the chain.
+  Block 3 (optional): the belief that makes "do it yourself" feel hard.
+  - One poll between blocks (~every 10–12 min).
+  - One live resource CTA mid-teaching — a downloadable the offer builds on.
+    This download is ALSO your engagement flag for follow-up segmentation.
+
+40:00–42:00  PERMISSION TRANSITION  (the make-or-break moment)
+  - Acknowledge the slides are enough to DIY.
+  - Ask permission to show the done-with-you path. Name the mode switch.
+  - Promise Q&A after, so nobody feels trapped.
+
+42:00–52:00  STACK + OFFER
+  - Each component framed against the cost of staying stuck, not as a feature list.
+  - Price revealed AFTER the stacked value, once.
+  - The single next step + a clean, real deadline (no fake countdowns).
+
+52:00–60:00  Q&A / CLOSE
+  - Handle live objections. Restate the next step + deadline as you answer.
+  - Do NOT re-open the teaching — questions only.
+```
+
+## The permission-transition script pattern
+
+The bridge from teaching to offer is where most webinars die. The pattern:
+
+1. **Validate the DIY path.** "These slides are enough to do this on your own."
+2. **Offer the faster path as a choice.** "For those who'd rather do it with us..."
+3. **Ask permission + time-box.** "Can I take two minutes to show you how?"
+4. **Promise the exit.** "Then we'll open it up for questions."
+
+```text
+"That's the entire method — and honestly, the slides I just shared are enough to
+ run it yourself. Some of you will, and that's great. For the rest of you who'd
+ rather not spend six months figuring out the edge cases alone — can I take two
+ minutes to show you exactly how we do this with you? Then I'll stay on for every
+ question you've got."
+```
+
+This lowers resistance because it hands the room a choice instead of a sales lurch,
+and it earns the pitch rather than springing it.
+
+## Poll placement
+
+- Minute 5: an easy opinion poll. Goal is participation habit, not data.
+- Between teaching blocks: a poll that surfaces the belief the next block breaks
+  ("What's your biggest blocker with X?") — it pre-sells the teaching.
+- Just before the transition: a readiness poll ("Want the DIY path or done-with-you?")
+  — it segments the room and warms the offer.
+
+## How the stack changes by offer type
+
+| Offer | Stack emphasis | Next step asked for |
+|---|---|---|
+| High-ticket cohort/coaching | transformation + access + accountability | book a call |
+| Course / self-serve product | outcome + speed + bonuses | buy now, deadline pricing |
+| Free trial / SaaS | activation + time-to-value | start trial, guided onboarding |
+| Lead-gen / consultation | the diagnosis they'll get | book the consult |
+
+Keep the offer to ONE primary next step. A second option splits the room's attention
+and lowers conversion on both.

package/skills/whatsapp-telegram/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: whatsapp-telegram
+description: "Use when wiring an app or agent to send messages to customers over the WhatsApp Cloud API or a Telegram bot — order updates, OTP codes, reminders, alerts, broadcasts — or when debugging not-delivered messages, 24-hour-window errors, rejected templates, or 429 rate limits. Triggers: 'send a WhatsApp template message', 'error 131047 re-engage outside the 24h window', 'verify X-Hub-Signature-256 on the WhatsApp webhook', 'setWebhook vs getUpdates for my Telegram bot', 'honor retry_after on a Telegram 429', 'enviar plantilla de WhatsApp d'avis al client', 'bot de Telegram para avisos'. NOT the reply content you send (that is customer-support)."
+tags: [whatsapp, telegram, messaging, cloud-api, bot-api]
+recommends: [customer-support, webhooks, automation-flows, chatbot, nodejs]
+origin: risco
+---
+
+# WhatsApp & Telegram messaging
+
+You are wiring code that pushes messages to real customers. Both platforms have sharp, silent rules: code that passes in testing 403s or drops in production. This skill is the transport pipe — endpoints, auth, windows, rate limits, webhooks. The *words* you send are out of scope (that is `../customer-support/SKILL.md`).
+
+## Pick your platform
+
+| If the customer is... | Use | Why |
+| --- | --- | --- |
+| already on WhatsApp, identity-verified, you have their phone number | WhatsApp Cloud API | Highest reach + trust; but **template-gated** and **billed per message**. |
+| an opt-in bot subscriber (clicked "Start") | Telegram Bot API | Free, instant, dev-friendly, no template gate, but reach = people who joined your bot. |
+
+You can ship both — but the rules do not transfer. WhatsApp's 24-hour window and template gate have no Telegram equivalent; Telegram's 30 msg/s ceiling has no WhatsApp equivalent.
+
+---
+
+## WhatsApp Cloud API
+
+### Env + endpoint
+
+Never hardcode credentials. Four values come from the Meta App + WhatsApp Business Account (WABA):
+
+```bash
+WA_TOKEN=...            # Bearer access token (System User token in prod, not a temp one)
+WA_PHONE_NUMBER_ID=...  # the sending number's ID, not the phone number itself
+WA_WABA_ID=...          # WhatsApp Business Account ID (for template management)
+WA_APP_SECRET=...       # app secret, used to verify inbound webhook signatures
+```
+
+Send endpoint, **with the version pinned in the path**:
+
+```
+POST https://graph.facebook.com/v25.0/{WA_PHONE_NUMBER_ID}/messages
+Authorization: Bearer ${WA_TOKEN}
+Content-Type: application/json
+```
+
+Pin the version (`v25.0` is current, announced 2026-02-18; `v24.0` is the lowest still supported). Why: a versionless URL drifts onto whatever Meta defaults to and breaks payload shape without warning. Never call `graph.facebook.com/{id}/messages` bare.
+
+### The 24-hour customer-service window (the load-bearing rule)
+
+A **free-form** message can ONLY be sent inside a 24-hour window that the *user* opened by messaging you. Outside that window you MUST send a pre-approved **template** to re-engage — a free-form send out-of-window fails with **error #131047** (re-engagement message required).
+
+| Window state | What you may send | Cost |
+| --- | --- | --- |
+| Open (user messaged < 24h ago) | Any free-form text / media / interactive | Free |
+| Open | Utility template | Free (in-window) |
+| Closed (no recent user message) | **Approved template only** | Billed per message (marketing/auth rates) |
+| Closed + you send free-form | nothing — **#131047** | n/a |
+
+So branch on window state before every send: in-window → free-form is fine; otherwise → reach for a template.
+
+### Send free-form text (in-window)
+
+```bash
+curl -sS -X POST "https://graph.facebook.com/v25.0/${WA_PHONE_NUMBER_ID}/messages" \
+  -H "Authorization: Bearer ${WA_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"messaging_product":"whatsapp","to":"34699999999","type":"text","text":{"body":"Your order #1234 shipped."}}'
+```
+
+```ts
+const res = await fetch(
+  `https://graph.facebook.com/v25.0/${process.env.WA_PHONE_NUMBER_ID}/messages`,
+  {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${process.env.WA_TOKEN}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      messaging_product: "whatsapp",
+      to: "34699999999",
+      type: "text",
+      text: { body: "Your order #1234 shipped." },
+    }),
+  },
+);
+const data = await res.json();
+const messageId = data.messages?.[0]?.id; // capture it — your only handle for delivery tracing
+```
+
+Always log `messages[0].id` from the response. It is the only key that ties a send to the later delivery/read webhook.
+
+### Send a template (out-of-window or any business-initiated message)
+
+```ts
+const body = {
+  messaging_product: "whatsapp",
+  to: "34699999999",
+  type: "template",
+  template: {
+    name: "appointment_reminder",      // must be APPROVED in WhatsApp Manager first
+    language: { code: "ca" },
+    components: [
+      {
+        type: "body",
+        parameters: [
+          { type: "text", text: "Maria" },
+          { type: "text", text: "dimarts a les 10:00" },
+        ],
+      },
+    ],
+  },
+};
+```
+
+Templates are created and approved via WhatsApp Business Manager or the `POST /{WA_WABA_ID}/message_templates` API before they can be sent. Variable order in `parameters` must match the `{{1}} {{2}}` placeholders in the approved template body.
+
+### Template categories + cost
+
+Four categories: **marketing**, **utility**, **authentication**, **service**. Category drives both policy and price.
+
+Billing changed on **2025-07-01**: conversation-based pricing is **deprecated**, replaced by **per-message** pricing — you are billed per delivered *template* message, rate by category + recipient country. Free-form messages inside an open window are free; utility templates inside an open window are free. Do not reason about old "per-conversation" pricing — it is gone. Full category/price table → `references/whatsapp-cloud-api.md`.
+
+Policy note: since **2026-01-15** Meta prohibits general-purpose AI assistants (open ChatGPT-wrapper bots) on WhatsApp. Business automation is fine; a generic chatbot is not. For conversational design see `../customer-support/SKILL.md`.
+
+### Inbound webhook
+
+1. **GET verify** — Meta calls your callback URL once with `hub.mode`, `hub.verify_token`, `hub.challenge`. If `hub.verify_token` matches your configured token, echo back `hub.challenge` (plain, 200).
+2. **POST events** — every event POST carries `X-Hub-Signature-256: sha256=<hmac>`. Compute `HMAC-SHA256(rawBody, WA_APP_SECRET)` and compare. **Reject unsigned/mismatched bodies** — without this anyone can forge inbound events.
+
+```ts
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+function verifyMeta(rawBody: string, header = ""): boolean {
+  const expected =
+    "sha256=" + createHmac("sha256", process.env.WA_APP_SECRET!).update(rawBody).digest("hex");
+  const a = Buffer.from(expected);
+  const b = Buffer.from(header);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+```
+
+For retry/idempotency/dedupe patterns of the receiver itself, this is the WhatsApp-specific setup only — generic receiver design → `webhooks`.
+
+---
+
+## Telegram Bot API
+
+### Token + base URL
+
+Get a token from **@BotFather**. Every method is an HTTP call:
+
+```
+https://api.telegram.org/bot${TG_TOKEN}/<METHOD>
+```
+
+Token from env (`TG_TOKEN`), never inline — it embeds in the URL and leaks in logs. Current Bot API is **10.0** (released 2026-05-08).
+
+### sendMessage
+
+```bash
+curl -sS "https://api.telegram.org/bot${TG_TOKEN}/sendMessage" \
+  -d chat_id=123456789 \
+  --data-urlencode "text=Build *passed* ✅" \
+  -d parse_mode=MarkdownV2
+```
+
+```ts
+await fetch(`https://api.telegram.org/bot${process.env.TG_TOKEN}/sendMessage`, {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ chat_id: 123456789, text: "Build passed", parse_mode: "HTML" }),
+});
+```
+
+`parse_mode` is `HTML` | `MarkdownV2` | `Markdown` (legacy). **MarkdownV2 requires escaping** the reserved set `_*[]()~\`>#+-=|{}.!` with a backslash, or the call 400s. HTML is safer for dynamic text. Text cap is **4096 chars** per message — split longer payloads into chunks. Escape table + chunking → `references/telegram-bot-api.md`.
+
+### Rate limits (the silent killer)
+
+- Broadcast ceiling: **~30 messages/second** across all chats.
+- Same chat: **~1 message/second**.
+- Exceed either → **HTTP 429** with a JSON `parameters.retry_after` (seconds). **Honor it**: sleep `retry_after` seconds, then retry. Do not blast-retry — you will be throttled harder.
+- Need more than 30/s? Enable **Paid Broadcasts** via @BotFather (up to 1000 msg/s, 0.1 Telegram Stars per excess message).
+
+```ts
+async function tgSend(payload: object, tries = 5): Promise<Response> {
+  for (let i = 0; i < tries; i++) {
+    const res = await fetch(`https://api.telegram.org/bot${process.env.TG_TOKEN}/sendMessage`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    });
+    if (res.status !== 429) return res;
+    const { parameters } = await res.json();
+    await new Promise((r) => setTimeout(r, (parameters?.retry_after ?? 1) * 1000));
+  }
+  throw new Error("Telegram: rate-limited after retries");
+}
+```
+
+### Inbound: setWebhook XOR getUpdates
+
+Pick exactly **one** — never run both, they conflict.
+
+- **setWebhook(url, ...)** — Telegram POSTs updates to your URL. Set a `secret_token`; Telegram echoes it back in the `X-Telegram-Bot-Api-Secret-Token` header — verify it. Optional `allowed_updates` (filter types) and `max_connections` (1–100, default 40).
+- **getUpdates** — long-poll loop, good for local dev / single-instance bots. Calling `getUpdates` while a webhook is set returns an error; call `deleteWebhook` first.
+
+Generic receiver design (retries, idempotency) → `webhooks`.
+
+---
+
+## Cross-cutting rules
+
+1. **Tokens from env only.** A leaked `WA_TOKEN` or `TG_TOKEN` is an account takeover. No inline secrets, ever.
+2. **Pin the Graph API version.** Versionless URLs drift and break payloads silently.
+3. **Respect windows and rate limits.** WhatsApp: branch on the 24h window. Telegram: honor `retry_after`.
+4. **Idempotency on retries.** A network retry can double-send; key sends on your own order/event id and dedupe.
+5. **Capture the response message id** (WhatsApp `messages[0].id`, Telegram `result.message_id`) — your only handle for delivery tracing.
+
+## Anti-patterns
+
+| Bad | Good | Why |
+| --- | --- | --- |
+| Free-form WhatsApp send to a customer who hasn't messaged in days | Send an approved template to re-engage | Out-of-window free-form fails with **#131047**. |
+| `POST graph.facebook.com/{id}/messages` (no version) | `POST .../v25.0/{id}/messages` | Versionless drifts onto Meta's default and breaks payload shape. |
+| `Authorization: Bearer EAAxxx...` hardcoded | `Bearer ${process.env.WA_TOKEN}` | Hardcoded tokens leak in git/logs = account takeover. |
+| Retry immediately after a Telegram 429 | Sleep `retry_after` seconds, then retry | Blast-retrying gets you throttled harder, not faster. |
+| `setWebhook` AND a `getUpdates` loop | Pick exactly one | They conflict; `getUpdates` errors while a webhook is set. |
+| Process inbound WhatsApp POST without checking `X-Hub-Signature-256` | Verify HMAC-SHA256 with app secret | Unsigned events are forgeable; you'd act on spoofed messages. |
+| Reasoning about WhatsApp "per-conversation" cost | Per-**message** since 2025-07-01 | Conversation pricing is deprecated; estimates will be wrong. |
+| Sending raw user text as `MarkdownV2` | Escape reserved chars, or use `HTML` | Unescaped `.` `-` `!` etc. 400 the call. |
+
+## References
+
+- `references/whatsapp-cloud-api.md` — full payload shapes (text/template/media/interactive), template component JSON, error codes (#131047, #131026, #100, template errors), webhook payload + signature verify, pricing category table, 2026 policy.
+- `references/telegram-bot-api.md` — messaging method catalog, MarkdownV2 escape table, setWebhook + getUpdates examples, 429 backoff, Paid Broadcasts.

package/skills/whatsapp-telegram/evals/README.md

@@ -0,0 +1,11 @@
+# Evals — whatsapp-telegram
+
+These cases are LLM-graded. `should_trigger` / `should_not_trigger` check that the skill's
+description and body route correctly: each `should_trigger` prompt (including a Catalan and a
+non-obvious error-code phrasing) must select this skill, while each `should_not_trigger` prompt
+must defer to the named sibling (`route_to`). The `capability` case is scored against its
+`must_include` rubric — a grader reads the skill body + references and confirms each bullet is
+satisfiable (pinned `v25.0` endpoint, env-sourced token, `messaging_product` body, 24h-window
+branch with #131047, captured message id). Run them with the repo's eval runner pointed at this
+skill directory; there is no live API call — grading is on the produced guidance, not on sending a
+real message.

package/skills/whatsapp-telegram/evals/cases.yaml

@@ -0,0 +1,44 @@
+skill: whatsapp-telegram
+
+should_trigger:
+  - prompt: "Send an order-confirmation WhatsApp message to a customer via the Cloud API"
+    why: Core WhatsApp Cloud API send — the central job of this skill.
+  - prompt: "My WhatsApp sends return error 131047, how do I re-engage the user?"
+    why: Non-obvious — #131047 is the closed-24h-window error; the fix is sending an approved template.
+  - prompt: "Build a Telegram bot that broadcasts alerts to subscribers and handle 429 retry_after"
+    why: Telegram send plus the rate-limit/backoff rule this skill owns.
+  - prompt: "Vull enviar una plantilla de WhatsApp d'avis de cita als clients"
+    why: Catalan phrasing for a WhatsApp template send (appointment-reminder template).
+  - prompt: "Set up the WhatsApp inbound webhook and verify the X-Hub-Signature-256 header"
+    why: Non-obvious WhatsApp-specific webhook setup (verify token + HMAC signature).
+  - prompt: "Should I use setWebhook or getUpdates for my Telegram bot?"
+    why: Telegram inbound decision — the two modes are mutually exclusive, a known footgun.
+  - prompt: "Why are my WhatsApp template blasts being billed per message now instead of per conversation?"
+    why: Non-obvious — pricing changed to per-message on 2025-07-01; agent must know the current model.
+
+should_not_trigger:
+  - prompt: "Write the actual support reply text and triage this angry customer"
+    route_to: customer-support
+    why: Content/tone and triage of the reply, not the transport pipe.
+  - prompt: "Plan our week's posts across LinkedIn, Instagram and TikTok"
+    route_to: social-publisher
+    why: Social content calendar and multi-platform posting, not 1:1 messaging APIs.
+  - prompt: "Write a cold first-touch DM sequence to prospects who never replied"
+    route_to: cold-outreach
+    why: First-touch outreach copy and cadence, not message delivery plumbing.
+  - prompt: "Design a generic webhook receiver with retries and idempotency for any provider"
+    route_to: webhooks
+    why: Abstract receiver design; this skill covers only WhatsApp/Telegram-specific setup.
+  - prompt: "When a Stripe payment succeeds, message the customer on WhatsApp — orchestrate the whole flow"
+    route_to: automation-flows
+    why: Cross-tool multi-step orchestration, not a single send implementation.
+
+capability:
+  - scenario: "Implement a function that messages a WhatsApp customer: send a free-form text if they messaged within the last 2 hours, otherwise send an approved template. Use the Cloud API."
+    must_include:
+      - "Endpoint pins the Graph version, e.g. https://graph.facebook.com/v25.0/{PHONE_NUMBER_ID}/messages"
+      - "Bearer token read from env (e.g. process.env.WA_TOKEN), never hardcoded"
+      - 'Body includes messaging_product: "whatsapp", to, and type'
+      - "Branches on the 24-hour window: in-window -> free-form text, out-of-window -> template"
+      - "Explains that out-of-window free-form fails with error #131047"
+      - "Captures the response message id (messages[0].id) for delivery tracing"

package/skills/whatsapp-telegram/references/telegram-bot-api.md

@@ -0,0 +1,91 @@
+# Telegram Bot API reference
+
+Base: `https://api.telegram.org/bot${TG_TOKEN}/<METHOD>`. Token from @BotFather, kept in env. Bot API 10.0 (2026-05-08). Facts accessed 2026-06-02.
+
+## Messaging method catalog
+
+| Method | Use |
+| --- | --- |
+| `sendMessage` | Text (≤4096 chars), `parse_mode`, `reply_markup`. |
+| `sendPhoto` | Photo by `photo` URL/file_id, `caption` ≤1024. |
+| `sendDocument` | Arbitrary file. |
+| `sendMediaGroup` | 2–10 items as an album. |
+| `editMessageText` | Edit a previously sent message (good for live status). |
+| `deleteMessage` | Remove a message. |
+| `answerCallbackQuery` | Acknowledge an inline-button tap (call within seconds or the client shows a spinner). |
+| `setMyCommands` | Register the `/` command menu. |
+
+Successful responses are `{ "ok": true, "result": {...} }`. Capture `result.message_id`.
+
+## MarkdownV2 escaping
+
+In `parse_mode=MarkdownV2`, escape these reserved chars with `\` everywhere they are literal text:
+
+```
+_ * [ ] ( ) ~ ` > # + - = | { } . !
+```
+
+```ts
+const escapeMdV2 = (s: string) => s.replace(/[_*[\]()~`>#+\-=|{}.!]/g, "\\$&");
+```
+Inside `pre`/`code` entities only `` ` `` and `\` need escaping. When in doubt for dynamic text, use `parse_mode=HTML` (escape only `< > &`).
+
+## 4096-char chunking
+```ts
+function chunk(text: string, max = 4096): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < text.length; i += max) out.push(text.slice(i, i + max));
+  return out;
+}
+```
+
+## Rate limits + 429 backoff
+
+- ~30 msg/s broadcast across chats; ~1 msg/s to the same chat.
+- 429 body: `{ "ok": false, "error_code": 429, "parameters": { "retry_after": 5 } }`. Sleep `retry_after` seconds, retry.
+- Paid Broadcasts (enable via @BotFather): up to 1000 msg/s, 0.1 Telegram Stars per message above the free tier.
+
+```ts
+async function call(method: string, payload: object, tries = 5): Promise<any> {
+  for (let i = 0; i < tries; i++) {
+    const res = await fetch(`https://api.telegram.org/bot${process.env.TG_TOKEN}/${method}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    });
+    const json = await res.json();
+    if (json.ok) return json.result;
+    if (json.error_code === 429) {
+      await new Promise((r) => setTimeout(r, (json.parameters?.retry_after ?? 1) * 1000));
+      continue;
+    }
+    throw new Error(`Telegram ${method}: ${json.error_code} ${json.description}`);
+  }
+  throw new Error(`Telegram ${method}: rate-limited after ${tries} tries`);
+}
+```
+
+## Inbound: setWebhook XOR getUpdates (never both)
+
+### setWebhook
+```bash
+curl -sS "https://api.telegram.org/bot${TG_TOKEN}/setWebhook" \
+  -d url=https://example.com/tg \
+  -d secret_token=$(openssl rand -hex 16) \
+  --data-urlencode 'allowed_updates=["message","callback_query"]' \
+  -d max_connections=40
+```
+Telegram echoes the `secret_token` in the `X-Telegram-Bot-Api-Secret-Token` request header on each update — compare it and reject mismatches. `max_connections` range 1–100, default 40. `allowed_updates` filters update types.
+
+### getUpdates (long-poll, dev / single instance)
+```ts
+let offset = 0;
+for (;;) {
+  const updates = await call("getUpdates", { offset, timeout: 30 });
+  for (const u of updates) {
+    offset = u.update_id + 1; // ack: advance past processed updates
+    // handle u.message / u.callback_query
+  }
+}
+```
+Calling `getUpdates` while a webhook is set returns an error — `deleteWebhook` first. Run exactly one delivery mode.

package/skills/whatsapp-telegram/references/whatsapp-cloud-api.md

@@ -0,0 +1,103 @@
+# WhatsApp Cloud API reference
+
+Endpoint base: `https://graph.facebook.com/v25.0/{WA_PHONE_NUMBER_ID}/messages` (POST, `Authorization: Bearer ${WA_TOKEN}`). v25.0 current (2026-02-18); v24.0 is the floor. Facts accessed 2026-06-02.
+
+## Message payload shapes
+
+Every body starts with `messaging_product: "whatsapp"`, `to`, `type`.
+
+### text
+```json
+{ "messaging_product": "whatsapp", "to": "34699999999", "type": "text",
+  "text": { "preview_url": false, "body": "Your order shipped." } }
+```
+
+### template
+```json
+{ "messaging_product": "whatsapp", "to": "34699999999", "type": "template",
+  "template": {
+    "name": "order_update",
+    "language": { "code": "es" },
+    "components": [
+      { "type": "header", "parameters": [ { "type": "text", "text": "1234" } ] },
+      { "type": "body",   "parameters": [ { "type": "text", "text": "Maria" }, { "type": "currency", "currency": { "fallback_value": "€19.90", "code": "EUR", "amount_1000": 19900 } } ] },
+      { "type": "button", "sub_type": "url", "index": 0, "parameters": [ { "type": "text", "text": "track/1234" } ] }
+    ]
+  } }
+```
+Parameter order MUST match the `{{1}} {{2}}` placeholders in the approved template.
+
+### image / document (media)
+```json
+{ "messaging_product": "whatsapp", "to": "34699999999", "type": "image",
+  "image": { "link": "https://example.com/receipt.png", "caption": "Receipt" } }
+```
+Use `link` (public URL) or a pre-uploaded `id` from the media endpoint.
+
+### interactive (buttons / list)
+```json
+{ "messaging_product": "whatsapp", "to": "34699999999", "type": "interactive",
+  "interactive": {
+    "type": "button",
+    "body": { "text": "Confirm your slot?" },
+    "action": { "buttons": [
+      { "type": "reply", "reply": { "id": "yes", "title": "Yes" } },
+      { "type": "reply", "reply": { "id": "no",  "title": "No" } }
+    ] } } }
+```
+Interactive messages are free-form → only deliver inside the open 24h window.
+
+## Common error codes
+
+| Code | Meaning | Fix |
+| --- | --- | --- |
+| 131047 | Re-engagement required (24h window closed) | Send an approved template, not free-form. |
+| 131026 | Message undeliverable | Recipient not on WhatsApp / number invalid / not opted in. |
+| 131051 | Unsupported message type | Check `type` + matching object key. |
+| 100 | Invalid parameter | Bad `to` format, missing `messaging_product`, malformed component. |
+| 132000–132xxx | Template errors | Param count mismatch, template paused/disabled, language mismatch. |
+| 80007 / 130429 | Rate limit hit | Back off; throttle send rate. |
+
+## Inbound webhook
+
+### GET verification (one-time, on subscribe)
+Meta calls `GET /your-callback?hub.mode=subscribe&hub.verify_token=...&hub.challenge=...`. If `hub.verify_token` equals your configured value, respond `200` with the raw `hub.challenge` as the body.
+
+### POST event signature verify
+```ts
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+export function verifyMeta(rawBody: Buffer, header = ""): boolean {
+  const expected = "sha256=" + createHmac("sha256", process.env.WA_APP_SECRET!).update(rawBody).digest("hex");
+  const a = Buffer.from(expected, "utf8");
+  const b = Buffer.from(header, "utf8");
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+```
+Verify against the **raw** request body (not re-serialized JSON) or the HMAC will not match.
+
+### Event payload (inbound message)
+```json
+{ "object": "whatsapp_business_account",
+  "entry": [ { "id": "WABA_ID", "changes": [ { "field": "messages", "value": {
+    "messaging_product": "whatsapp",
+    "metadata": { "phone_number_id": "PHONE_NUMBER_ID" },
+    "contacts": [ { "wa_id": "34699999999" } ],
+    "messages": [ { "from": "34699999999", "id": "wamid.XXX", "timestamp": "1733400000", "type": "text", "text": { "body": "hi" } } ]
+  } } ] } ] }
+```
+An inbound `messages[]` entry opens (or refreshes) the 24h window for that `from`.
+
+## Pricing categories (per-message since 2025-07-01)
+
+| Category | When | Cost |
+| --- | --- | --- |
+| marketing | promos, offers, re-engagement | Paid per message, country rate. |
+| utility | order/account updates tied to a transaction | Free inside open window; paid out-of-window. |
+| authentication | OTP / login codes | Paid per message, country rate. |
+| service | free-form replies inside the window | Free. |
+
+Free-entry-point conversations (user taps an ad/CTA) are free for 72h. Rates vary by recipient country code; check the current Meta rate card.
+
+## Policy (2026)
+Since 2026-01-15, Meta prohibits general-purpose AI assistants (open ChatGPT-wrapper bots with no clear business purpose) on WhatsApp. Scoped business automation is allowed.