opencode-skills-collection 3.0.28 → 3.0.29

package/bundled-skills/mathguard/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: mathguard
+description: "Math-heavy escalation for n >= 10^6 — Bloom, HyperLogLog, Count-Min, MinHash/LSH, FFT, JL projection, sweep line. Use when classical O(n log n) is the floor and approximate or math wins."
+risk: safe
+source: community
+source_repo: morsechimwai/lemmaly
+source_type: community
+date_added: "2026-05-26"
+author: morsechimwai
+tags: [algorithms, probabilistic-data-structures, approximate-algorithms, bloom-filter, hyperloglog, fft, performance]
+tools: [claude-code, antigravity, cursor, gemini-cli, codex-cli]
+license: "Apache-2.0"
+license_source: "https://github.com/morsechimwai/lemmaly/blob/main/LICENSE"
+---
+
+# mathguard — Math-Heavy Optimization for AI Code
+
+`lemmaly` makes you pick the right classical algorithm. `mathguard` kicks in when the classical algorithm is already optimal but **mathematics gives a better bound** — usually by accepting bounded approximation, exploiting structure, or moving to a smarter algebraic space.
+
+The model knows these techniques. It almost never proposes them spontaneously. mathguard fixes that.
+
+**Violating the letter of these rules is violating the spirit of the skill.** A Bloom filter where the caller assumed exact answers is a production incident, not an optimization.
+
+## When to Use This Skill
+
+Use **mathguard** when:
+
+- Working with large-scale data (`n ≥ 10⁶`): similarity search, deduplication, top-K / heavy-hitters, streaming analytics, cardinality estimation, embeddings, recommender systems.
+- Doing signal/image processing, polynomial or big-integer arithmetic, convolution, graph distance, computational geometry, randomized algorithms.
+- The classical O(n log n) is already the floor and you need an asymptotic win (Bloom filter, HyperLogLog, Count-Min Sketch, MinHash/LSH, FFT/NTT, Johnson-Lindenstrauss projection, sweep line, kd-tree/BVH, fast exponentiation, monoid parallel reduction, amortized potential method).
+- Loaded *after* `lemmaly` has confirmed the classical answer is not enough.
+
+Do **not** use mathguard when:
+- The caller needs exact answers (auth, billing, dedup-for-correctness, primary keys).
+- `n` is small (n < 10⁴) and the path is not hot.
+- The bottleneck is I/O, not CPU/memory.
+
+## The Iron Law
+
+```text
+NO APPROXIMATE STRUCTURE WITHOUT WRITTEN ε/δ AND EXPLICIT CALLER ACCEPTANCE
+```
+
+Probabilistic data structures (Bloom, HyperLogLog, Count-Min, MinHash/LSH, t-digest), randomized projections (JL), and lossy transforms (floating FFT) all change the answer's meaning. Before proposing one:
+
+1. Write the error parameter the caller will see (false-positive rate, relative error, distortion bound).
+2. Identify the caller and state, in one sentence, that they tolerate this kind of wrong answer.
+3. If you cannot identify the caller, or they need exact (auth checks, billing, dedup keys, deduplication for correctness, anything that flows into a primary key), DO NOT propose the approximate structure. Keep classical, or escalate to a sharded/streaming exact design.
+
+This rule has saved more incidents than any other in this skill. Do not soften it.
+
+## Non-negotiable rules
+
+1. **Declare exact vs approximate up front.** Before suggesting a math-level technique, state:
+   - `mode: exact` or `mode: approximate`
+   - If approximate: the error parameter (ε, δ, false-positive rate) and a sentence on whether the caller can tolerate it.
+   - If the caller needs exact and there is no exact win, say so and stop — do not silently degrade to approximate.
+
+2. **Cite the technique by name.** Never describe a probabilistic or numerical trick in vague terms. Name it: `Bloom filter`, `HyperLogLog`, `Count-Min Sketch`, `MinHash + LSH`, `Johnson–Lindenstrauss projection`, `FFT`, `NTT`, `fast exponentiation`, `Karatsuba`, `Strassen`, `sweep line`, `kd-tree`, `BVH`, `union-find with path compression`, `Floyd's cycle detection`, `Boyer-Moore majority`, `reservoir sampling`, `Knuth shuffle`, `Aho-Corasick`, `suffix automaton`, `segment tree with lazy propagation`, `Fenwick tree`, `monoid scan / parallel prefix`. A named technique is auditable; "a smart approximation" is not.
+
+3. **State the trade you are making.** Every math-level optimization buys something at a cost. In one line:
+   - Buys: `space`, `time`, `wall-clock`, `parallelism`.
+   - Costs: `accuracy ε=?`, `code complexity`, `dependency`, `non-determinism`, `numerical stability`.
+   - If the cost is invisible to the caller, write "callers see no change".
+
+4. **Justify the asymptotic win.** Do not propose a math technique without a one-line bound argument:
+   - "HyperLogLog: count uniques in O(log log n) bits at standard error 1.04/√m."
+   - "FFT: polynomial multiplication O(n log n) vs schoolbook O(n²)."
+   - "JL projection: preserves pairwise distances within (1±ε) using O(log n / ε²) dimensions."
+   - "Sweep line: rectangle overlap from O(n²) pair checks to O(n log n) events."
+   No bound, no proposal.
+
+5. **Forbid math cargo-culting.** Do not introduce these techniques when:
+   - n is small enough that a linear scan finishes in microseconds (n < ~10⁴ unless it is a hot path).
+   - The problem is I/O-bound — the math win disappears behind network/disk.
+   - Exact answers are required and no exact technique exists.
+   - The team will not maintain it (write that down: "team familiarity: ?").
+
+## The pre-proposal protocol
+
+Before suggesting a math-level technique, your message must contain — in this order:
+
+1. **The classical floor** — what is the best non-mathy algorithm and its Big-O? ("Hash join is O(n+m); we're already there.")
+2. **Why classical is not enough** — n too large, space blows up, real-time deadline, etc.
+3. **The math technique** — named (rule 2).
+4. **Exact or approximate** — with ε if approximate (rule 1).
+5. **The new bound** — with one-line derivation (rule 4).
+6. **The trade** — buys/costs (rule 3).
+7. **When NOT to use this** — at least one disqualifier.
+8. **The code or pseudocode.**
+
+If any of 1–7 is missing, do not propose the technique.
+
+## Playbook — math technique → problem → win → caveat
+
+### Sketches and probabilistic structures (massive data, approximate)
+
+| Problem | Classical | Math technique | Win | Caveat |
+|---|---|---|---|---|
+| Membership: "have I seen this key?" at scale | `Set<id>`, O(n) space | **Bloom filter** | O(n) bits at chosen ε false-positive | False positives only; cannot remove (use Cuckoo if needed) |
+| Count distinct values in a stream | `Set` to count, O(unique) space | **HyperLogLog** | O(log log n) bits, ~1% relative error | Approximate; cannot list elements |
+| Top-K / heavy hitters in a stream | full counter, O(unique) space | **Count-Min Sketch** + heap | O(log(1/δ)·1/ε) space | Overestimates; choose ε,δ deliberately |
+| Document / set similarity at scale | full Jaccard, O(n·m) | **MinHash + LSH** | Sub-linear ANN query | Tunes recall vs precision; param search |
+| k-NN in high-dim vectors | brute O(n·d) | **JL projection → HNSW / IVF** | O(log n) per query, (1±ε) distortion | Index build cost; recall < 1 |
+| Reservoir of size k from a stream of unknown length | buffer all, O(n) space | **Reservoir sampling** | O(k) space, uniform sample | Single-pass only |
+| Find majority element | counter map | **Boyer-Moore majority vote** | O(1) space, O(n) time | Requires majority exists; verify pass |
+| Quantiles in a stream | sort, O(n log n) | **t-digest / GK** | O(1/ε) space, ε-accurate quantiles | Approximate |
+
+### Fast arithmetic / transforms (numeric and combinatorial)
+
+| Problem | Classical | Math technique | Win | Caveat |
+|---|---|---|---|---|
+| Multiply two polynomials / big integers | O(n²) | **FFT / NTT / Karatsuba** | O(n log n) | Floating FFT loses precision — use NTT for integers |
+| Convolution of two signals | O(n·m) | **FFT-based convolution** | O((n+m) log(n+m)) | Numerical noise at very small magnitudes |
+| `pow(a, b) mod p`, b large | O(b) multiplications | **Fast exponentiation (square-and-multiply)** | O(log b) | Watch for overflow inside; use modular arithmetic |
+| GCD of large integers | repeated subtraction | **Euclidean algorithm** | O(log min) | Standard; AI sometimes still writes the subtraction loop |
+| Matrix multiplication, n large | O(n³) | **Strassen** (then Coppersmith-Winograd family) | O(n^2.81) | High constant; only wins for very large dense |
+| Solving Ax=b for sparse A | O(n³) dense | **Conjugate gradient / sparse LU** | O(nnz · iterations) | Numerical conditioning matters |
+| Modular inverse | brute force | **Extended Euclidean** or **Fermat** when p prime | O(log p) | p must be prime for Fermat |
+
+### Dimensionality reduction and linear algebra
+
+| Problem | Classical | Math technique | Win | Caveat |
+|---|---|---|---|---|
+| Similarity in d-dim, d large | O(n·d) brute | **JL projection** to k = O(log n / ε²) | O(n·k) at (1±ε) distortion | Random; verify on validation set |
+| Recommender from rating matrix | iterate full matrix | **Truncated SVD / matrix factorization** | O(k·(n+m)) for rank-k | Choose k; refresh strategy |
+| Document-term similarity | TF-IDF O(n·m) | **LSA via SVD** | rank-k approximation | Latent dims are not interpretable |
+| PCA on n samples in d dims | O(n·d²) | **Randomized SVD** | O(n·d·k) for rank-k | Randomized; set oversampling |
+
+### Geometry (spatial queries)
+
+| Problem | Classical | Math technique | Win | Caveat |
+|---|---|---|---|---|
+| Range / nearest-neighbor in 2D-3D | O(n) per query | **kd-tree / R-tree / BVH** | O(log n) per query | Degrades in high d; use ANN instead |
+| Rectangle / interval overlap pairs | O(n²) pair check | **Sweep line + active set (BBST)** | O((n+k) log n) | k = output size; segment tree variant exists |
+| Polygon point-in-polygon at scale | O(n·v) | **BSP / monotone decomposition / R-tree** | O(log v) per query after build | Build cost |
+| Convex hull of n points | O(n²) gift wrap | **Graham scan / Andrew's monotone chain** | O(n log n) | Numerical robustness for collinear |
+| Closest pair of points | O(n²) | **Divide and conquer** | O(n log n) | Carefully merge across the strip |
+
+### Graph and algebraic tricks
+
+| Problem | Classical | Math technique | Win | Caveat |
+|---|---|---|---|---|
+| Connected components under merges | recompute BFS each merge | **Union-Find with path compression + rank** | α(n) ≈ O(1) per op amortized | Inverse Ackermann is effectively constant |
+| Range sum / update on array | O(n) per query | **Fenwick tree** | O(log n) per op | Inclusive ranges; off-by-one risk |
+| Range query with monoid (sum/min/max/gcd) | O(n) per query | **Segment tree (with lazy if range updates)** | O(log n) | More code than Fenwick; more general |
+| LCA in a tree, many queries | O(n) per query | **Binary lifting** or **Euler tour + RMQ** | O(log n) or O(1) per query | Preprocessing cost |
+| Shortest path on DAG | Dijkstra | **Topo sort + relax** | O(V+E) | Only works on DAG |
+| Detect cycle in linked list | hash visited | **Floyd's tortoise and hare** | O(1) space | Same big-O time, dramatic space win |
+| Parallel reduction over n items | sequential fold | **Monoid + parallel scan** | O(n/p + log p) on p cores | Operation must be associative; verify it |
+
+### Amortized and online algorithms
+
+| Problem | Classical | Math technique | Win | Caveat |
+|---|---|---|---|---|
+| "Dynamic array push is expensive" | per-op O(n) on resize | **Amortized analysis (doubling)** | O(1) amortized | This is what `ArrayList` / `vec` already do; just defend it |
+| Streaming median | re-sort | **Two heaps (max-heap + min-heap)** | O(log n) per insert | Maintain size invariant |
+| Online interval scheduling | re-sort by deadline | **Greedy with priority queue** | O(log n) per arrival | Specific objective; check problem fit |
+| Sliding-window max | O(n·k) | **Monotonic deque** | O(n) total | Window invariant subtle to maintain |
+
+## Canonical example — counting distinct users
+
+**Problem.** Count unique users seen across a 24-hour event stream. ~2B events/day, ~50M unique users. Reported on a dashboard, ±2% is acceptable.
+
+### Without the protocol — silent OOM, or worse, silent billing error
+
+```ts
+// "Just use a Set" — silently OOMs the box at ~50M strings
+const seen = new Set<string>();
+for await (const event of stream) {
+  seen.add(event.userId);
+}
+return seen.size; // exact, but the process died at row 41M
+```
+
+Or worse — proposed *with* a HyperLogLog "for performance" but plugged into the billing pipeline, which keys off the result. Billing then sees 49.7M instead of 50.0M users and a fraction never get charged.
+
+### With the protocol — auditable HLL
+
+```ts
+// Classical floor: O(unique) memory for an exact Set. At 50M strings × ~50B each, ~2.5GB.
+// Why classical is not enough: dashboard box has 512MB and refreshes every minute.
+// Technique: HyperLogLog (HLL).
+// Mode: approximate. ε ≈ 1.04/√m. With m=2^14 registers → ~0.8% relative error.
+// Trade: buys O(log log n)-bit space (~12KB); costs ±0.8% on the displayed count.
+// When NOT to use: anything that flows into billing, primary keys, or per-user actions.
+// Caller acceptance: confirmed — dashboard product owner accepts ±2%, written in PR.
+
+import { createHLL } from 'hyperloglog-lite';
+const hll = createHLL({ precision: 14 });
+for await (const event of stream) {
+  hll.add(event.userId);
+}
+return hll.estimate(); // 49.6M ± 0.4M; dashboard reads ~50M
+```
+
+The first version is not "no HLL" — it is "HLL without writing down ε and who tolerates it." The second is identical in technique but auditable: ε is in the comment, the caller is named, the disqualifier (billing) is explicit.
+
+## Output discipline
+
+Code that uses a math-level technique must include:
+
+- One comment naming the technique with a doc link or one-line citation.
+- The exact error parameters chosen (ε, δ, bits, dimensions, etc.) and why those values.
+- A measured or asymptotic justification next to the chosen parameters.
+- An exact-mode fallback path, if the caller might need it.
+
+## When to escalate or redirect
+
+- The bottleneck is I/O, not CPU/memory → go back to `lemmaly` rule 4; math will not help.
+- You need bit-exact reproducibility → avoid floating FFT, randomized projections, and probabilistic structures.
+- The result is consumed by a downstream system that assumes exact → keep classical or wrap with a validation pass.
+- You need a correctness proof (not just a bound) → load **invariant-guard** after picking the technique.
+
+## Rationalizations to watch for
+
+| Excuse | Reality |
+| --- | --- |
+| "A `set` works — I'll flag the memory issue in a comment." | Noticing the problem is not solving it. If memory is the budget, ship the structure that respects it. |
+| "Probabilistic structures sound fancy / academic." | Cloudflare runs Bloom filters in the request path. Redis ships HyperLogLog. These are production-tested, not academic. |
+| "Approximate is risky — I'll do exact and let it OOM later." | Silent OOM at 3am is riskier than a stated 0.81% error. State the ε, pick parameters, ship. |
+| "I'll just shard the set across machines." | Sharding multiplies your infra cost; HLL solves it in 12KB on one box. Ask whether you actually need exact. |
+| "FFT is overkill for this." | True 99% of the time. But state the n. At n ≥ ~64 for polynomial mult, schoolbook is already losing. |
+| "JL projection feels too lossy for embeddings." | At ε = 0.1, JL preserves pairwise distances within 10%. For ANN this is almost always fine — measure recall, do not eyeball. |
+
+## Red flags — STOP
+
+- Proposing a probabilistic structure without stating ε and δ.
+- Saying "we can use FFT here" without writing the n at which FFT actually beats schoolbook.
+- Using `JSON.parse(JSON.stringify(...))` to deep-clone when `structuredClone` exists, then claiming it as an optimization.
+- Recommending Strassen on a 100×100 matrix.
+- Switching to approximate output without the caller having agreed to it.
+- Naming a technique you cannot derive the bound for.
+- Math optimization where n is small and not on a hot path.
+- "Should be O(log n) on average" with no average-case argument.
+
+## Verification checklist
+
+Before shipping code that uses a math-level technique:
+
+- [ ] The technique is named (no "a smart approximation").
+- [ ] If approximate: ε and δ (or the equivalent error parameter) are written in code or in the PR description.
+- [ ] The caller has been identified and their tolerance for that error is stated.
+- [ ] A one-line bound derivation is present (asymptotic or measured).
+- [ ] At least one disqualifier ("when NOT to use this") is documented.
+- [ ] An exact-mode fallback exists, OR a one-line note explains why exact is impossible.
+- [ ] If randomized: the seed strategy is documented (fixed for reproducibility, or stated as non-deterministic).
+- [ ] Downstream consumers that assume exactness (joins on this value, billing, auth, primary keys) have been audited.
+
+Cannot check every box? The technique is not ready to ship. Keep classical, or stop and ask.
+
+## Limitations
+
+- **Not for exact-required pipelines.** Any system where the result is a primary key, dedup key, billing input, or auth decision is out of scope — keep classical.
+- **Assumes representative inputs.** ε/δ bounds are average-case or high-probability; adversarial inputs can blow past them. State the threat model.
+- **Library quality varies.** Bloom / HLL / MinHash implementations differ in seed strategy, hash function, and memory layout — pick a maintained library and pin the version.
+- **Numerical stability.** Floating FFT, randomized SVD, and JL projection accumulate float error; for combinatorial exactness use NTT or exact integer variants.
+- **Team-familiarity risk.** A technique nobody can debug at 3 a.m. is a liability — write the maintainer note next to the trade-off.
+- **Not a profiler.** mathguard tells you which asymptotic ceiling you can break; it does not measure constant factors. Benchmark before claiming a wall-clock win.
+
+## The thesis, in one line
+
+> **When classical algorithms hit their floor, mathematics still has another floor below. mathguard makes the model reach for it instead of accepting the first answer.**
+
+## Related Skills
+
+- `lemmaly` — gateway; pick the classical algorithm first before reaching for math.
+- `invariant-guard` — for stating ε-bounds as part of the postcondition of an approximate algorithm.
+- `complexity-cuts` — when baseline code already exists and the bottleneck is CPU/memory, not approximation.

package/bundled-skills/sendblue/sendblue-api/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: sendblue-api
+description: "Send and receive iMessage, SMS, and RCS from application code via the Sendblue HTTP API — text, media, group messages, send styles, reactions, typing indicators, status callbacks, and inbound webhooks."
+category: api-integration
+risk: safe
+source: community
+source_type: official
+date_added: "2026-05-22"
+author: AnthonyFirth
+tags: [sendblue, imessage, sms, rcs, messaging, api, webhooks]
+tools: [claude, cursor, gemini]
+---
+
+# Sendblue API
+
+## Overview
+
+Sendblue is a REST API that sends iMessage (blue bubbles), SMS, and RCS from a provisioned phone number. Everything is plain JSON over HTTPS — no SDK is required. The API covers outbound 1:1 and group sends, iMessage effects, reactions, typing indicators, status callbacks, and inbound webhooks.
+
+## When to Use This Skill
+
+- Use when writing application code (server, worker, function) that sends Sendblue messages as part of a long-running service.
+- Use when receiving inbound messages via webhooks.
+- Use when you need features the CLI does not expose: send styles, reactions, group messages, typing indicators, status callbacks, media uploads, or the contacts API beyond basic CRUD.
+- Reach for [[sendblue-cli]] instead for shell-context outbound: one-shot scripts, cron jobs, agent hooks, "ping me when X" workflows.
+
+## How It Works
+
+### Step 1: Authenticate
+
+```
+https://api.sendblue.com
+```
+
+Every request needs two headers:
+
+```
+sb-api-key-id: <YOUR_API_KEY_ID>
+sb-api-secret-key: <YOUR_API_SECRET>
+Content-Type: application/json
+```
+
+Keep both values server-side — never ship them to a browser or mobile client.
+
+### Step 2: Send a message
+
+```bash
+curl -X POST https://api.sendblue.com/api/send-message \
+  -H "sb-api-key-id: $KEY_ID" \
+  -H "sb-api-secret-key: $SECRET" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "number": "+15551234567",
+    "from_number": "+1YOUR_SENDBLUE_NUMBER",
+    "content": "Hello from the API!"
+  }'
+```
+
+Phone numbers must be E.164. `from_number` must be a line you own — list yours with `GET /api/lines`.
+
+### Step 3: Track delivery
+
+The synchronous response includes a `message_handle` (Apple GUID — persist this; you need it for reactions and replies) and a `status` from `REGISTERED`, `PENDING`, `QUEUED`, `ACCEPTED`, `SENT`, `DELIVERED`, `DECLINED`, `ERROR`. Only `DELIVERED` means it landed. Use `status_callback` instead of polling `/api/status`.
+
+### Step 4: Receive inbound
+
+Configure webhook URLs in the dashboard or via `POST /api/account/webhooks`. Sendblue POSTs JSON to your endpoint. Respond with 2xx promptly — non-2xx triggers retries and duplicate deliveries. Event types: `receive`, `outbound`, `typing_indicator`, `call_log`, `line_blocked`, `line_assigned`, `contact_created`.
+
+## Core Endpoints
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| POST | `/api/send-message` | Send a 1:1 message (text and/or media) |
+| POST | `/api/send-group-message` | Send to multiple recipients |
+| POST | `/api/create-group` | Create a named group thread |
+| POST | `/api/send-reaction` | Send a tapback (love/like/dislike/laugh/emphasize/question) |
+| POST | `/api/send-typing-indicator` | Show "typing…" in the recipient's thread |
+| POST | `/api/mark-read` | Send a read receipt |
+| POST | `/api/upload-file` / `/api/upload-media-object` | Upload media (direct or from URL) |
+| GET | `/api/status` | Poll a message's delivery status |
+| GET | `/api/evaluate-service` | Check whether a number is on iMessage |
+| GET | `/api/v2/messages` / `/api/v2/messages/:id` | Read message history |
+| GET / POST / PUT / DELETE | `/api/v2/contacts[...]` | Manage contacts |
+| GET | `/api/lines` | List your Sendblue phone numbers |
+| POST | `/api/account/webhooks` | CRUD webhook subscriptions |
+
+## Examples
+
+### Example 1: Send with media, effects, and a status callback
+
+```json
+POST /api/send-message
+{
+  "number": "+15551234567",
+  "from_number": "+1YOUR_SENDBLUE_NUMBER",
+  "content": "Optional text",
+  "media_url": "https://example.com/img.jpg",
+  "send_style": "celebration",
+  "status_callback": "https://yourapp.com/sendblue/status"
+}
+```
+
+`content` and/or `media_url` is required. `send_style` is iMessage-only — valid values: `celebration`, `shooting_star`, `fireworks`, `lasers`, `love`, `confetti`, `balloons`, `spotlight`, `echo`, `invisible`, `gentle`, `loud`, `slam`. Ignored on SMS. Text up to 18,996 chars; media up to 100 MB on iMessage, 5 MB on SMS.
+
+### Example 2: Group message
+
+```json
+POST /api/send-group-message
+{
+  "numbers": ["+15551234567", "+15557654321"],
+  "from_number": "+1YOUR_SENDBLUE_NUMBER",
+  "content": "Hey team"
+}
+```
+
+The response returns a `group_id` — persist it to send follow-ups into the same thread instead of creating a new one each time.
+
+### Example 3: React to a message
+
+```json
+POST /api/send-reaction
+{
+  "from_number": "+1YOUR_SENDBLUE_NUMBER",
+  "message_handle": "<message_handle from prior send>",
+  "reaction": "love"
+}
+```
+
+Reactions only work on iMessage and need the original message's `message_handle`. Valid values: `love`, `like`, `dislike`, `laugh`, `emphasize`, `question`.
+
+### Example 4: Inbound webhook payload (`receive`)
+
+```json
+{
+  "accountEmail": "you@example.com",
+  "content": "Reply text",
+  "media_url": "https://...",
+  "is_outbound": false,
+  "number": "+15551234567",
+  "from_number": "+1YOUR_SENDBLUE_NUMBER",
+  "service": "iMessage",
+  "group_id": "...",
+  "date_sent": "2024-01-01T12:00:00Z"
+}
+```
+
+Status callback payloads (`outbound`) mirror the send-message response and update as the message moves through `SENT` → `DELIVERED` (or `ERROR`).
+
+## Best Practices
+
+- ✅ **Persist `message_handle` on every send.** You need it for reactions, replies, and correlating status callbacks.
+- ✅ **Use `status_callback` over polling.** It's lower-cost and more accurate than `GET /api/status`.
+- ✅ **Return 2xx fast from your webhook**, then process async. Non-2xx triggers duplicate deliveries.
+- ✅ **Check service with `/api/evaluate-service`** before relying on iMessage-only features for a recipient.
+- ✅ **Rehost inbound media on receipt** — media URLs expire in ~30 days.
+- ❌ **Don't ship `sb-api-key-id` / `sb-api-secret-key` to a client.** They are server-side credentials.
+- ❌ **Don't treat a 200 on `/api/send-message` as delivery.** It only means "accepted".
+
+## Limitations
+
+- Synchronous send responses only report acceptance, not delivery. Final state arrives via `status_callback` or `GET /api/status`.
+- `send_style` silently no-ops on SMS (green-bubble recipients).
+- Inbound media URLs expire in ~30 days.
+- Per-line rate limits apply; bursting many sends from one number can trip Apple's spam heuristics — pace them or split across lines.
+- Reactions and effects are iMessage-only.
+
+## Security & Safety Notes
+
+- Keep `sb-api-key-id` and `sb-api-secret-key` server-side. They are not safe in browser, mobile, or CI logs.
+- Webhook endpoints should be on HTTPS and idempotent — same `message_handle` may arrive more than once.
+- Sensitive data in message content is visible in lock-screen previews on the recipient's device. Don't embed secrets, tokens, or full PII — link to an authenticated dashboard or shortened payload instead.
+- Rotate API keys from the Sendblue dashboard if either value is exposed; the old pair is invalidated on rotation.
+
+## Common Pitfalls
+
+- **E.164 only.** `5551234567` or `(555) 123-4567` will fail — always send `+15551234567`.
+- **`from_number` must be one of your lines.** A spoofed or unprovisioned number returns an error.
+- **`send_style` silently no-ops on SMS.** If the recipient is green-bubble, effects don't render — check service first with `/api/evaluate-service` if it matters.
+- **Store `message_handle`.** You need it for reactions, replies, and correlating status callbacks back to your records.
+- **Media URLs expire in ~30 days.** If you need durable media from inbound webhooks, download and re-host on receipt.
+- **Status is async.** A 200 on `/api/send-message` means accepted, not delivered. Use `status_callback` rather than blocking on the synchronous response.
+- **Webhook retries on non-2xx.** Return 200 even when you've decided to ignore the event; otherwise expect duplicate deliveries.
+- **Rate limits apply per line.** Bursting many sends from one number trips Apple's spam heuristics — pace them or split across lines.
+
+## Related Skills
+
+- `@sendblue-cli` — Shell wrapper for shell-context outbound (scripts, cron, agent hooks). Use it when you don't need a full HTTP integration.
+- `@sendblue-notify` — Patterns and copy rules for outbound "text me when X is done" notifications layered on top of the API or CLI.
+
+## Links
+
+- Full reference: <https://docs.sendblue.com/>
+- Sendblue: <https://sendblue.com>
+- Useful undocumented-here features: carousels (`/api/send-carousel`), FaceTime/contact-card sharing, advanced webhook filtering, contacts API beyond basic CRUD — see the docs site.

package/bundled-skills/sendblue/sendblue-cli/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: sendblue-cli
+description: "Send iMessage and SMS from the shell via the @sendblue/cli npm package — outbound sends, contact management, and account setup with no API client or webhook server required."
+category: api-integration
+risk: safe
+source: community
+source_repo: sendblue-api/sendblue-cli
+source_type: official
+date_added: "2026-05-22"
+author: AnthonyFirth
+tags: [sendblue, imessage, sms, cli, messaging, notifications]
+tools: [claude, cursor, gemini]
+license: "MIT"
+license_source: "https://github.com/sendblue-api/sendblue-cli/blob/main/LICENSE"
+---
+
+# Sendblue CLI
+
+## Overview
+
+`@sendblue/cli` is a Node CLI that creates a Sendblue account, provisions an iMessage-enabled number, and sends messages. It is the fastest way to text from a shell, script, or Claude Code hook — no API client, no webhook server, no credentials in env vars. Credentials live at `~/.sendblue/credentials.json` (mode `600`) and Node.js 18+ is required.
+
+## When to Use This Skill
+
+- Use when the user wants to text a phone number from a script, shell, hook, or agent turn (e.g. "text me when X finishes", "ping my phone", "notify on completion").
+- Use when the user mentions `sendblue` as a CLI/binary or asks to set up the `@sendblue/cli` package.
+- Prefer this skill over [[sendblue-api]] when the work happens in a shell context, one-shot script, cron job, or agent hook.
+- Reach for [[sendblue-api]] instead when writing application code that integrates Sendblue, receiving inbound webhooks, or needing features the CLI does not expose (send styles, reactions, group messages, status callbacks, media uploads).
+
+## How It Works
+
+### Step 1: Install
+
+```bash
+npm install -g @sendblue/cli       # global, exposes `sendblue`
+# or one-shot:
+npx @sendblue/cli <command>
+```
+
+### Step 2: Set up an account
+
+`sendblue setup` runs interactively by default. For CI/scripts, run it in two phases — the first call sends an 8-digit verification code by email, the second consumes it.
+
+```bash
+sendblue setup --email you@example.com                                       # sends code
+sendblue setup --email you@example.com --code 12345678 \
+               --company my-co --contact +15551234567                        # completes setup
+```
+
+| Flag | Notes |
+|---|---|
+| `--email` | Email address |
+| `--code` | 8-digit verification code (from the email) |
+| `--company` | Lowercase, hyphens/underscores, 3–64 chars |
+| `--contact` | First contact, E.164 |
+
+### Step 3: Send messages
+
+```bash
+sendblue send +15551234567 'Hello from Sendblue!'
+sendblue messages --inbound --limit 20
+```
+
+Phone numbers must be E.164 (`+` + country code + digits, no spaces or dashes).
+
+### Step 4: Manage contacts and plan
+
+On the free plan, **a contact must text your Sendblue number once before outbound sends to that contact will work**. After `sendblue setup ... --contact +15551234567`, have that contact send any text to the printed Sendblue number, then run `sendblue contacts` to confirm verification.
+
+## Command Reference
+
+| Command | Purpose |
+|---|---|
+| `sendblue setup` | Create account, verify email, set company name, add first contact |
+| `sendblue login` | Log in to an existing account |
+| `sendblue send <number> <message>` | Send an iMessage |
+| `sendblue messages [--inbound\|--outbound] [-n <number>] [-l <count>]` | List recent messages |
+| `sendblue add-contact <number>` | Register a contact |
+| `sendblue contacts` | List contacts and their verification status |
+| `sendblue status` | Account/plan info |
+| `sendblue whoami` | Show current credentials and verify validity |
+
+## Examples
+
+### Example 1: Notify when a long task finishes
+
+```bash
+long_running_thing && sendblue send +15551234567 "✅ done: $(date)"
+```
+
+### Example 2: Read recent inbound for a specific contact
+
+```bash
+sendblue messages -n +15551234567 --inbound --limit 50
+```
+
+### Example 3: Verify creds are good before a batch send
+
+```bash
+sendblue whoami || sendblue login
+```
+
+### Example 4: Wire to a Claude Code `Stop` hook
+
+To text yourself at the end of every agent turn, register a `Stop` hook in `settings.json` that shells out to `sendblue send`. Defer the actual hook wiring to [[update-config]] and the trigger logic to [[sendblue-notify]] — this skill only owns the CLI invocation.
+
+## Best Practices
+
+- ✅ **Use E.164 numbers everywhere.** `+15551234567`, never `5551234567` or `(555) 123-4567`.
+- ✅ **Run `sendblue whoami` before unattended batches** to fail fast on stale or missing creds.
+- ✅ **Re-run `setup` as the same OS user** that owns `~/.sendblue/credentials.json`.
+- ❌ **Don't `sudo`** — it writes creds to root's home and the next non-sudo run won't see them.
+- ❌ **Don't embed creds in env vars** when the CLI already reads them from the per-user credentials file.
+
+## Limitations
+
+- Outbound-first: there is no built-in webhook server for inbound. Use [[sendblue-api]] webhooks for full inbound handling.
+- The CLI does not expose send styles/effects, reactions, group messages, status callbacks, media uploads, or the contacts API beyond basic CRUD. Reach for the HTTP API for those.
+- Free-plan accounts require recipient verification before outbound sends succeed.
+
+## Security & Safety Notes
+
+- Credentials are written to `~/.sendblue/credentials.json` with mode `600`. Treat that file like an API key — do not commit it, do not copy it across machines without the same posture.
+- Run the CLI as the OS user that owns the credentials file. `sudo` writes a separate copy under root's home and silently desyncs.
+- Outbound messages to phone numbers are not free of consequence — wire `sendblue send` into hooks or loops only after gating on duration or success conditions to avoid spamming the recipient.
+- Verification codes arrive by email; treat the address you registered with as a recovery factor for the account.
+
+## Common Pitfalls
+
+- **E.164 only.** `5551234567` or `(555) 123-4567` will fail — always `+15551234567`.
+- **Free-plan unverified contacts.** Outbound to a contact that hasn't texted in first returns an error — have them text your Sendblue number once, then confirm with `sendblue contacts`.
+- **Two-step setup in non-interactive mode.** `--email` alone only sends the code; you must run a second invocation with `--code` and the rest of the flags to finish.
+- **Credentials are per-user.** `~/.sendblue/credentials.json` is owner-only (`600`). Don't `sudo` and pollute root's home — re-running as the same user that ran `setup` is what works.
+
+## Related Skills
+
+- `@sendblue-api` — HTTP/JSON alternative for application code, webhooks, and features the CLI does not expose.
+- `@sendblue-notify` — Patterns and copy rules for "text me when X is done" workflows that sit on top of this CLI.
+- `@update-config` — Wires `sendblue send` into Claude Code hooks (`Stop`, `Notification`) without owning the message logic.
+
+## Links
+
+- README & full flag reference: <https://github.com/sendblue-api/sendblue-cli>
+- Sendblue: <https://sendblue.com>
+- API docs (deeper protocol details): <https://docs.sendblue.com>