opencode-skills-collection 3.0.27 → 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/mesh-memory/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: mesh-memory
+description: "Self-hosted semantic memory for AI agents via MCP. Save worklogs, decisions, and notes, then recall them across sessions by meaning, not keyword. Postgres + pgvector with auto-tagging."
+risk: safe
+source: dklymentiev/mesh-memory (MIT)
+date_added: "2026-05-23"
+---
+
+# Mesh Memory
+
+Mesh Memory is a self-hosted semantic memory service with a built-in MCP server. It stores documents (worklogs, decisions, notes, research) in PostgreSQL with pgvector and retrieves them by meaning, so a query like "what database did we pick?" surfaces a saved note that says "chose Redis for caching" even with zero keyword overlap. Embeddings are generated locally with `multilingual-e5-base` (768 dimensions); the core flow requires no external API keys.
+
+Use this skill when an agent needs persistent memory across sessions: saving its own work, recalling prior decisions, or building a project knowledge base shared between multiple agents.
+
+## When to Use This Skill
+
+- Saving a session worklog, decision, or research note so a later session can find it.
+- Recalling past work by topic when you do not remember the exact words you used.
+- Sharing a long-lived knowledge base across multiple agents, terminals, or teammates.
+- Organizing context by role or project through workspaces (one workspace per role/project).
+- Looking up structured tags (e.g. all `type:decision` entries from one project).
+
+## Prerequisites
+
+- A running Mesh Memory instance reachable from the MCP server. Local Docker is the common path -- `docker compose up -d` in the upstream repo brings it up; see https://github.com/dklymentiev/mesh-memory for the full Quick Start.
+- The MCP server (`mcp_server.py`) registered with your client (Claude Code, Cursor, Claude Desktop, or any other MCP-aware agent).
+- `MESH_API_URL` pointing at the running instance (default: `http://localhost:8000`).
+
+## Setup
+
+Register the MCP server in your client configuration:
+
+```json
+{
+  "mcpServers": {
+    "mesh": {
+      "command": "python3",
+      "args": ["/path/to/mesh-memory/mcp_server.py"],
+      "env": {
+        "MESH_API_URL": "http://localhost:8000"
+      }
+    }
+  }
+}
+```
+
+When the server is reachable, the 13 tools listed below become available.
+
+## MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `mesh_focus` | Switch the active workspace (optionally prefetch recent docs). |
+| `mesh_add` | Save a document with optional tags. Auto-adds `date:YYYY-MM-DD` and `source:`. |
+| `mesh_update` | Update content, tags, or pinned status of an existing document. |
+| `mesh_delete` | Delete a document by GUID. |
+| `mesh_get` | Fetch a single document by GUID. |
+| `mesh_search` | Semantic search by query, optionally across multiple workspaces with weights. |
+| `mesh_bytag` | List documents that match one or more tags (AND logic). |
+| `mesh_recent` | List most recently created documents, optionally filtered by `type:` tag. |
+| `mesh_projects` | List per-project document counts (uses `guid:` tag as project marker). |
+| `mesh_tags` | List existing tags with counts; optional prefix filter. |
+| `mesh_versions` | Show the version chain of a document (similarity-linked revisions). |
+| `mesh_stats` | Memory statistics for the active workspace. |
+| `mesh_schema` | Show the tag schema (recognized prefixes and types). |
+
+## Workflows
+
+### Save a session worklog
+
+After completing work, persist it for future sessions:
+
+```
+mesh_add(
+  content="Investigated 502s on the checkout flow. Root cause: missing CORS header on the cart API. Fix shipped in commit abc123.",
+  tags="type:worklog,topic:checkout,date:2026-05-23",
+  workspace="developer"
+)
+```
+
+`date:` and `source:` are added automatically when omitted. Type and topic tags are inferred from nearest neighbors after the embedding completes (5-10 seed documents required before inference kicks in).
+
+### Recall past work by meaning
+
+Search across sessions for related context, even with different vocabulary:
+
+```
+mesh_search(query="checkout was failing for some users", limit=5, workspace="developer")
+```
+
+The query shares no keywords with the original note ("502s", "CORS"), but the embedding-based search surfaces it.
+
+### Switch role / context
+
+For a multi-role agent, switch the active workspace at the start of a session:
+
+```
+mesh_focus(workspace="sysadmin", prefetch=true, limit=5)
+```
+
+Subsequent calls default to that workspace. Pin a role-prompt document at the top of each workspace so the agent re-orients on every prefetch.
+
+### Cross-workspace search with weights
+
+To pull context from related domains without diluting the primary signal:
+
+```
+mesh_search(
+  query="nginx rate limit recipe",
+  workspaces={"sysadmin": 0.7, "security": 0.2, "developer": 0.1},
+  limit=10
+)
+```
+
+Results are merged across workspaces and re-scored by workspace weight.
+
+### Structured lookups by tag
+
+When you need an exact filter rather than semantic similarity:
+
+```
+mesh_bytag(tags="type:decision,status:active,guid:my-project", limit=20)
+```
+
+## Tag Conventions
+
+Mesh accepts arbitrary tags. The recommended prefixes (used by auto-inference and surfaced by `mesh_schema`):
+
+| Prefix | Meaning |
+|--------|---------|
+| `type:worklog` | Completed work; the most common type. |
+| `type:note` | Quick notes, observations. |
+| `type:decision` | Architecture or product decisions. |
+| `type:research` | Investigation results, findings. |
+| `type:task` | Action items. |
+| `type:rfc` | Proposals for review. |
+| `status:active` / `status:completed` / `status:archived` | Lifecycle. |
+| `date:YYYY-MM-DD` | When the document was created (auto-added). |
+| `source:` | How the document arrived (auto-added: `mcp`, `api`, etc.). |
+| `guid:<project-id>` | Project marker -- use a consistent slug across all docs of a project. |
+
+With fewer than ~5-10 documents in a workspace, neighbor inference is skipped; manually tag seed documents until the corpus self-organizes.
+
+## Troubleshooting
+
+**Tool calls fail with connection errors.** The MCP server cannot reach `MESH_API_URL`. Verify the instance is up (`curl $MESH_API_URL/health` returns `{"status":"healthy"}`) and the env var is set in the MCP config.
+
+**A saved document does not appear in semantic search yet.** Embedding generation runs in the background. After a save, expect a 1-2 second delay before semantic search hits the new document. `mesh_get(guid=...)` confirms the document exists immediately.
+
+**Search returns results from the wrong domain.** The active workspace is not what you expected. Call `mesh_focus(workspace="<name>")` explicitly, or pass `workspace=` on every call. With no focus and no explicit param, calls land in the `default` workspace.
+
+**Auto-tagging never adds anything.** The workspace has too few documents for neighbor inference (~5-10 minimum). Manually tag a handful of seed documents, then auto-inference takes over.
+
+**A deleted document still appears in a search result.** Embedding indices are eventually consistent; rerun the search after a few seconds, or use `mesh_get(guid=...)` to confirm deletion.
+
+## Limitations
+
+- Mesh is a knowledge store, not a chat memory. Long conversation transcripts should be summarized before being saved.
+- Vector similarity is robust but not perfect; for high-precision structured lookups, prefer `mesh_bytag` over `mesh_search`.
+- Embeddings run on CPU by default; very large corpora (hundreds of thousands of documents) benefit from a dedicated instance and pgvector tuning, not covered here.
+- The optional AI categorizer requires an OpenAI-compatible LLM endpoint and is disabled by default.

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.