@ericrisco/rsc 0.1.47 → 0.1.49

package/skills/elixir/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: elixir
-description: "Use when writing or refactoring Elixir/OTP code — GenServers, supervision trees, processes, pattern matching, mix projects and releases — or when BEAM behaviour misbehaves (restart loops, mailbox growth, timeouts). Triggers: 'write a GenServer', 'design a supervision tree', 'restart strategy one_for_one', 'let it crash instead of try/rescue', 'mix release for production', non-obvious 'my process mailbox keeps growing', 'GenServer call timeout / restart loop', Catalan 'arbre de supervisio en Elixir / processos que peten', Spanish 'arbol de supervision / procesos en Elixir / que es let it crash'. NOT building a Phoenix web app, LiveView, Ecto schemas, controllers or channels (that is phoenix)."
+description: "Use when writing or refactoring Elixir/OTP on the BEAM — GenServers, supervision trees and restart strategies, pattern matching, mix projects and releases — or when processes misbehave (restart loops, mailbox growth, call timeouts). NOT a Phoenix web app, LiveView, Ecto or channels (that is `phoenix`)."
 tags: [elixir, otp, genserver, supervision, beam, mix, concurrency, functional]
 recommends: [phoenix, postgresdb, docker]
 origin: risco
@@ -14,7 +14,7 @@ Default to **pure functions**. Most of your code is data transformation and need
 
 ## Decision: do you even need a process?
 
-A process is not "an object". Spawning one to hold a value you could pass as an argument is the most common beginner mistake — it adds a serialization bottleneck and a failure mode for nothing.
+A process is not "an object": spawning one to hold a value you could pass as an argument is the most common beginner mistake, and it adds a serialization bottleneck and a failure mode for nothing.
 
 | Situation | Use | Why |
 |---|---|---|
@@ -28,8 +28,6 @@ Rule: if two pieces of code never run at the same time and share no mutable stat
 
 ## The functional core
 
-Each rule below earns its place; the why is one line.
-
 **Match in function heads, not with `if`** — branches become exhaustive and self-documenting, and a non-match crashes loudly instead of silently falling through.
 
 ```elixir
@@ -80,13 +78,11 @@ end
 
 ## Processes and message passing
 
-Raw `spawn`/`send`/`receive` exists, but in production you almost always want an OTP behaviour (GenServer/Task/Agent) so you get `child_spec`, supervision, and shutdown handling for free.
+Raw `spawn`/`send`/`receive` exists and is fine for a throwaway fire-and-forget where supervision genuinely does not matter, but in production you almost always want an OTP behaviour (GenServer/Task/Agent) so you get `child_spec`, supervision, and shutdown handling for free.
 
 - **Link** (`spawn_link`) couples lifetimes: if one dies abnormally, the other gets an exit signal. This is how supervision works.
 - **Monitor** (`Process.monitor/1`) is one-directional and non-fatal: you get a `{:DOWN, ...}` message but you do not die. Use it when you care *that* something died but should survive it.
 
-Drop to raw processes only for a throwaway fire-and-forget where supervision genuinely does not matter; otherwise reach for OTP.
-
 ## GenServer
 
 Split the **client API** (runs in the caller) from the **server callbacks** (run in the GenServer process). Callers never touch state directly.
@@ -124,11 +120,9 @@ defmodule Counter do
 end
 ```
 
-Rules, each with its why:
-
 - **Never block in `init/1`.** `start_link` blocks until `init` returns, so a slow `init` stalls the whole supervision tree boot. Return `{:ok, state, {:continue, term}}` and do the work in `handle_continue/2`.
 - **`use GenServer` auto-defines `child_spec/1`** — you rarely write one by hand; override only to change `:restart` or `:shutdown`.
-- **`call` is synchronous (with a 5s default timeout), `cast` is fire-and-forget.** Use `call` when the caller needs the result or backpressure; `cast` when it does not. A flood of `cast`s with no backpressure is the classic mailbox-growth bug — see references/otp-patterns.md.
+- **`call` is synchronous (with a 5s default timeout), `cast` is fire-and-forget.** Use `call` when the caller needs the result or backpressure; `cast` when it does not. A flood of `cast`s with no backpressure is the classic mailbox-growth bug — timeouts and backpressure recipes in `references/otp-patterns.md`.
 - **Name via `Registry`, not a global atom**, when you have many dynamic instances — atoms are never garbage-collected (see anti-patterns).
 
 ## Supervision trees
@@ -164,7 +158,7 @@ end
 
 **Let it crash**: do not wrap business logic in `try/rescue` to keep a process alive. Validate inputs at the boundary, then trust the happy path; if an invariant breaks, crashing and restarting from a known-good `init` state is the recovery mechanism. Reserve `rescue` for boundaries where you must convert an exception into a tagged tuple for a caller.
 
-For runtime-spawned children (a worker per connection/job) use `DynamicSupervisor` + `Registry` for lookup. Full recipe in references/otp-patterns.md.
+For runtime-spawned children (a worker per connection/job) use `DynamicSupervisor` + `Registry` for lookup. Full recipe — plus `Task`, `Agent`, `:ets` and how to choose an OTP behaviour — in `references/otp-patterns.md`.
 
 ## mix project
 
@@ -189,7 +183,7 @@ MIX_ENV=prod mix release
 _build/prod/rel/my_app/bin/my_app start
 ```
 
-Deps anatomy, environments, env vars, and the umbrella decision live in references/mix-and-releases.md.
+`mix.exs` anatomy, deps, environments, env vars, releases and the umbrella decision live in `references/mix-and-releases.md`.
 
 ## Types and modern stdlib
 
@@ -213,5 +207,3 @@ Deps anatomy, environments, env vars, and the umbrella decision live in referenc
 ## Verify
 
 Run `scripts/verify.sh` from your mix project root (the directory containing `mix.exs`). It checks `mix format --check-formatted` and `mix compile --warnings-as-errors`, and skips cleanly with exit 0 when Elixir/mix is not installed so it never blocks a toolchain-free CI.
-
-See references/otp-patterns.md (DynamicSupervisor+Registry, Task, Agent, ETS, timeouts/backpressure, choosing an OTP behaviour) and references/mix-and-releases.md (mix.exs anatomy, config vs runtime, releases, umbrellas).

package/skills/email-connector/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: email-connector
-description: "Use when wiring an app to send transactional or bulk email through an HTTP provider (Resend, Twilio SendGrid, Postmark) from server code: welcome/reset/receipt sends, a provider-agnostic sendEmail() seam, React Email or dynamic templates, idempotent retries, 100-cap batch with partial-failure handling, transactional-vs-broadcast stream split, and the bounce/complaint webhook feeding a suppression list. Triggers: 'send a password-reset email with Resend', 'emails double-send when the queue retries', 'switch us off SendGrid onto Postmark without rewriting every call site', 'send a digest to 4000 users and handle the ones that fail', 'el webhook de bounces no actualiza la lista de supresión', 'montar el envío de correos con Resend'. NOT writing the subject line or the open/click growth system (that is newsletter)."
+description: "Use when wiring server code to send transactional or bulk email via Resend, SendGrid, or Postmark: a provider-agnostic sendEmail() seam, idempotent retries, 100-cap batches with partial failures, transactional-vs-broadcast streams, bounce webhooks feeding a suppression list. NOT SPF/DKIM/DMARC inbox reputation (that is `email-deliverability`)."
 tags: [email, transactional-email, resend, sendgrid, postmark, webhooks, idempotency]
 recommends: [email-deliverability, newsletter, webhooks, secure-coding, api-connector-builder, automation-flows]
 origin: risco
@@ -13,30 +13,16 @@ digest — your job is the server code that hands it to a provider, makes it saf
 to retry, and keeps the suppression list honest. You do **not** own the inbox
 (SPF/DKIM/DMARC/reputation is `../email-deliverability/SKILL.md`) and you do
 **not** own the words (subject lines and growth are `../newsletter/SKILL.md`,
-launch copy is `../marketing/SKILL.md`). The deliverable is idempotent,
-secret-safe, stream-correct server code — not subject lines, DNS records, or
-audience strategy.
+launch copy is `../marketing/SKILL.md`). Generic typed clients for *any* REST API
+are `../api-connector-builder/SKILL.md`; deciding *when* a multi-step sequence
+fires is `../automation-flows/SKILL.md`.
 
 Stack as of June 2026: `resend` 6.12.4, `@sendgrid/mail` 8.1.6, Postmark via its
 HTTP API, React Email 5.0 (React 19.2 / Next.js 16, Tailwind 4), Node 20+ / TS.
 
-## The four non-negotiables
-
-Every email integration you produce must satisfy these. `scripts/verify.sh`
-greps for the first three; the fourth is the design constraint behind them.
-
-1. **API key from env, never a literal.** `process.env.RESEND_API_KEY`, not
-   `re_xxx` / `SG.xxx` / a server token in source. *Why:* a committed key is a
-   send-as-you credential — instant abuse and reputation burn.
-2. **Idempotency key on every transactional send.** *Why:* queues retry,
-   serverless functions re-fire, users double-click. Without a stable key one
-   password reset becomes three.
-3. **Send on the correct stream.** Transactional and broadcast traffic go on
-   distinct From + subdomain + stream. *Why:* a marketing reputation hit must
-   never push password resets to spam.
-4. **Verify the inbound webhook signature against the raw body.** *Why:* the
-   bounce/complaint hook mutates your suppression list; an unverified hook lets
-   anyone suppress (or un-suppress) your users.
+`scripts/verify.sh` is read-only and greps a target for the four invariants this
+skill exists to hold: env-sourced key, idempotency, a single `sendEmail()` seam,
+and a webhook signature checked on the raw body.
 
 ## Step 1 — pick a provider
 
@@ -47,14 +33,18 @@ greps for the first three; the fourth is the design constraint behind them.
 | **Postmark** | Pure transactional, deliverability-first | No — self-dedupe via your key + webhooks | Postmark server templates | per-stream | Receipts/resets must never queue behind marketing |
 
 Idempotency support changes your strategy, not just your config — see Step 4.
-Full per-provider matrix (auth headers, exact signatures, webhook event names,
-rate limits) is in `references/providers.md`.
+Full per-provider matrix (auth header, SDK + version, single/batch signatures,
+idempotency model, stream/subdomain model, dynamic-template syntax, webhook event
+names, rate limits, when to pick each) plus a suppression-webhook handler skeleton
+per provider is in `references/providers.md`.
 
 ## Step 2 — the `sendEmail()` seam
 
 One provider-agnostic function. The rest of the app calls `sendEmail(...)` and
 never imports a provider SDK. *Why:* swapping SendGrid→Postmark is then one file,
-not a grep across every call site.
+not a grep across every call site. That one file reads the key from
+`process.env` — never a `re_…` / `SG.…` / server-token literal, because a
+committed key is a send-as-you credential and burns your reputation with it.
 
 ```ts
 // lib/email/index.ts — the only place a provider SDK is imported
@@ -174,7 +164,9 @@ const html = '<h1>Hi ' + req.body.name + '</h1>'; // XSS + broken layout risk
 
 ## Step 4 — idempotency & retries
 
-Derive a deterministic key from the *event*, not the clock. Same event → same
+Every transactional send carries a key, because queues retry, serverless
+functions re-fire, and users double-click — without a stable key one password
+reset becomes three. Derive it from the *event*, not the clock. Same event → same
 key → provider (or your table) collapses the duplicate.
 
 ```ts
@@ -245,7 +237,9 @@ down with it. The DNS/auth setup for those subdomains is
 
 The provider POSTs bounce and complaint events. Verify the signature on the
 **raw** body (parse after verifying), then write the address to a suppression
-list and check that list before every future send.
+list and check that list before every future send. The verification is absolute
+because this hook mutates the suppression list: unverified, anyone can suppress
+— or un-suppress — your users.
 
 ```ts
 // app/api/email/webhook/route.ts (Next.js 16) — verify BEFORE parsing
@@ -281,14 +275,3 @@ before I ever send) is `../lead-gen/SKILL.md` / `../email-deliverability/SKILL.m
 | Trusting the webhook without signature check | Anyone can poison your suppression list | Verify signature on raw body, then parse |
 | Sending to a bounced/complained address | Reputation damage, ISP penalties | Filter against suppression list before send |
 | Calling the provider SDK at scattered call sites | Provider swap = grep across the app | One `sendEmail()` seam (Step 2) |
-
-## Reference
-
-`references/providers.md` — full side-by-side matrix (auth header, SDK +
-version, single/batch signatures, idempotency model, stream/subdomain model,
-dynamic-template syntax, webhook event names, rate limits, when to pick each)
-plus a suppression-webhook handler skeleton per provider.
-
-Generic typed HTTP-client wrappers for *any* REST API →
-`../api-connector-builder/SKILL.md`. The orchestration that decides *when* to
-fire a multi-step sequence → `../automation-flows/SKILL.md`.

package/skills/email-deliverability/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: email-deliverability
-description: "Use when mail you send lands in spam, gets rejected, or fails the Gmail/Yahoo bulk-sender checks, and you must fix authentication and reputation rather than the sending code — setting SPF/DKIM/DMARC DNS records so they align, raising a cold domain through warmup, keeping the spam-complaint rate under threshold, adding one-click unsubscribe, getting the brand logo and verified checkmark to show via BIMI, and reading why 'soft' rejections and Postmaster Tools say you are throttled. Triggers: 'our emails go to spam since the Gmail update', 'DMARC fails even though SPF passes', 'how do I warm up a new sending domain', 'do I need one-click unsubscribe to send to gmail', '550 5.7.26 unauthenticated', 'how do I get our logo and the blue checkmark to show in Gmail with BIMI', 'los correos caen en spam y el SPF está bien', 'configurar BIMI i el logo verificat al correu'. NOT putting transactional/bulk email on the wire through a provider API (that is email-connector)."
+description: "Use when mail already sent lands in spam, is rejected, or fails the Gmail/Yahoo bulk-sender checks and the fix is authentication and reputation, not the sending code: SPF/DKIM/DMARC alignment, domain warmup, spam-complaint rate, one-click unsubscribe, BIMI. NOT putting mail on the wire through a provider API (that is `email-connector`)."
 tags: [email, deliverability, spf, dkim, dmarc, bimi, sender-reputation, bulk-sender]
 recommends: [email-connector, newsletter, cold-outreach, gdpr-privacy, data-policy]
 origin: risco
@@ -9,34 +9,26 @@ origin: risco
 # email-deliverability — make mail authenticate and land in the inbox
 
 This skill owns one layer: **why mail you already send gets filtered, deferred,
-or rejected, and the DNS + reputation work that fixes it.** It does not put mail
-on the wire — that is `email-connector`. It starts where the send technically
-succeeds but the message never reaches the inbox.
+or rejected, and the DNS + reputation work that fixes it.** It starts where the
+send technically succeeds but the message never reaches the inbox.
 
 The lever is almost never the sending code. It is three DNS records that must
 *align*, a complaint rate you must hold down, and a reputation you build slowly
 and lose fast. Treat this as ops on a domain, not a code change.
 
-## When to use / When NOT to use
-
-**Use when:** mail lands in spam or Promotions and you suspect auth/reputation,
-not copy; a receiver returns `550 5.7.26` (unauthenticated), `421`/`451`
-deferrals, or `dmarc=fail`; you must meet the Gmail/Yahoo bulk-sender rules
-before a launch; you are standing up a brand-new sending domain and need a
-warmup plan; Google Postmaster Tools shows a rising spam rate or "Bad" domain
-reputation; you want the brand logo and a verified checkmark to show in Gmail
-(BIMI + VMC/CMC).
-
-**Do NOT use for:**
+## Not this skill
 
 - **Sending the mail at all** — provider SDK, `sendEmail()` seam, templates,
-  retries, batch caps, bounce/complaint webhooks → `email-connector`. That skill
-  feeds the suppression list; this one explains the reputation it protects.
+  retries, batch caps, bounce/complaint webhooks → `../email-connector/SKILL.md`.
+  That skill feeds the suppression list; this one explains the reputation it
+  protects.
 - **Subject lines, open/click optimization, list growth** → `newsletter`.
 - **Outbound prospecting sequences, lead lists** → `cold-outreach` (deliverability
   is a *constraint* on it, not the same job).
 - **Consent, lawful basis, retention of the address list** → `gdpr-privacy` and
   `data-policy`. Unsubscribe *mechanics* live here; consent *law* does not.
+- **Handling the DKIM private key and provider API secrets** →
+  `../secure-coding/SKILL.md`.
 
 ## The three records that must align
 
@@ -154,15 +146,3 @@ low-complaint sending.
 | Faking transactional headers to dodge Promotions | Violates bulk rules; risks rejection, not just foldering | Accept Promotions placement; earn Primary via engagement |
 | Routing the unsubscribe to a form that takes a week | Breaks the 2-day one-click honor rule; raises complaints | Honor `List-Unsubscribe-Post` one-click within 2 days, automatically |
 | Adding BIMI to fix spam-foldering | BIMI needs DMARC enforcement you do not have yet, and it changes logo display, not placement | Fix auth + reputation first; add BIMI last as a branding layer |
-
-## See also
-
-- `../email-connector/SKILL.md` — the provider/SDK send path, suppression list,
-  and bounce/complaint webhook that this skill's reputation rules sit on top of.
-- `../secure-coding/SKILL.md` — handling the DKIM private key and provider API
-  secrets without leaking them.
-
-Recommended companions (siblings): `email-connector` for the actual send,
-`newsletter` for the copy/engagement side that drives complaint rate down,
-`cold-outreach` (deliverability gates it), and `gdpr-privacy` / `data-policy`
-for the consent and retention behind a clean list.

package/skills/embeddings-search/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: embeddings-search
-description: "Use when results from a semantic search feel irrelevant, when you don't know which embedding model or chunk size to use, when you need to add a reranker or hybrid scoring, or when you have no way to tell whether a retrieval change actually helped. Symptoms: search returns garbage, exact-match queries miss, paraphrases work but keywords don't, recall looks fine but the top result is wrong, every chunking idea is a guess. Triggers: 'which embedding model and chunk size should I use', 'my semantic search returns irrelevant results', 'how do I measure if retrieval is good — recall@k, nDCG', 'add a reranker and hybrid BM25+vector', 'exact product codes return nothing but paraphrases work fine', 'recall@k is fine but the top answer is wrong', 'quin model d'embeddings i quina mida de chunk faig servir per a aquests documents', 'la cerca semàntica retorna resultats irrellevants'. NOT operating the vector store (that is vector-db)."
+description: "Use when choosing an embedding model, chunk size, or query form, when semantic search returns irrelevant results, when adding hybrid BM25+vector or a reranker, or when a retrieval change needs a number (recall@k, nDCG, MRR). NOT operating the store — index tuning, quantization (that is `vector-db`) — nor the retrieve-to-answer loop (that is `rag`)."
 tags: [embeddings, semantic-search, chunking, hybrid-search, reranking, rrf, retrieval-eval, mteb, matryoshka]
 recommends: [vector-db, rag, structured-extraction, prompt-engineering, postgresdb]
 origin: risco
@@ -9,10 +9,9 @@ origin: risco
 # embeddings-search — make and judge the vectors
 
 You own the **embedding technique layer**: turn a corpus into searchable vectors, turn a
-question into a good retrieval, and **measure whether that retrieval is any good**. When the
-symptom is "results are irrelevant," "I don't know which model or chunk size," or "how do I
-even tell if search improved," this is the skill. You stop the moment the right chunks come
-back, measured by a number. You do not assemble a prompt or generate an answer.
+question into a good retrieval, and **measure whether that retrieval is any good**. You stop the
+moment the right chunks come back, measured by a number. You do not assemble a prompt or
+generate an answer.
 
 Route the adjacent surfaces away:
 
@@ -41,7 +40,9 @@ cost — where cost is set by **dimensions**, because dims set storage and memor
 
 Quality anchor (mid-2026 MTEB English retrieval): Gemini ~68.3, Cohere `embed-v4` ~65.2,
 OpenAI `3-large` ~64.6, `BGE-M3` ~63.0. MTEB is the standard comparison, not a verdict on
-*your* domain (see `references/models.md` for the over-trust caveat).
+*your* domain — [`references/models.md`](references/models.md) carries the full model matrix
+(dims, max tokens, price, `input_type` convention, Matryoshka support) and how to read MTEB
+without over-trusting it.
 
 Two hard rules — each is a **silent** failure, no error, just worse results:
 
@@ -153,7 +154,9 @@ This is the rigor of the skill. "Search is bad" is not actionable; "recall@10 is
 
 1. **Build a golden query set** — 30–50+ labeled `query → relevant doc ids` pairs drawn from
    real questions. This is the asset; everything else is reproducible from it.
-2. **Pick metrics** (definitions + runnable skeleton in `references/evaluation.md`):
+2. **Pick metrics** — definitions, a runnable Python eval skeleton, golden-set construction and
+   the A/B-one-change methodology are in
+   [`references/evaluation.md`](references/evaluation.md):
    - **recall@k** — of the truly relevant docs, how many landed in the top-k. Catches "the
      right chunk never came back."
    - **nDCG@k** — rewards relevant docs ranked higher. Catches "right docs, wrong order."
@@ -179,15 +182,3 @@ flags hybrid/rerank artifacts that mention no recall/nDCG/MRR for exactly this r
 | Over-large dims "for safety" | Doubles storage/RAM, little recall gain | Right-size; truncate via Matryoshka |
 | Re-embedding the corpus to change dims | Wasteful when the model is Matryoshka-trained | Truncate dims, don't re-embed |
 | Embedding raw HTML/boilerplate | Match signal drowns in markup | Embed clean text; keep the rest as metadata |
-
-## References & siblings
-
-- `references/models.md` — current model matrix (dims, max tokens, price, `input_type`
-  convention, Matryoshka support) and how to read MTEB without over-trusting it.
-- `references/evaluation.md` — golden-set construction, recall@k / nDCG@k / MRR definitions, a
-  runnable Python eval skeleton, and the A/B-one-change methodology.
-
-Siblings: store ops → [`../vector-db/SKILL.md`](../vector-db/SKILL.md) · full answer loop →
-[`../rag/SKILL.md`](../rag/SKILL.md) · typed extraction →
-[`../structured-extraction/SKILL.md`](../structured-extraction/SKILL.md) · prompt design →
-[`../prompt-engineering/SKILL.md`](../prompt-engineering/SKILL.md).

package/skills/error-handling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: error-handling
-description: "Use when designing how code recognizes, recovers from, and reports failure — typed error taxonomies, retry/backoff/timeout policy, circuit breakers, React/Next error boundaries, and the user message + operator log line. Triggers: 'add retries with backoff', 'set up an error boundary', 'standardize our error types', 'stop swallowing exceptions', 'this catch block hides the real error', 'degrade gracefully when the payment provider is down', 'why does our retry storm take the database down', 'maneja los errores sin tragarte la excepción', 'afegeix reintents amb backoff i tallacircuits'. NOT finding why one specific thing broke (that is debug), NOT wiring logs/metrics/traces (that is observability), NOT the on-the-wire error envelope contract (that is api-design)."
+description: "Use when designing the reaction to a class of failures — typed error taxonomies, retry/backoff/timeout policy, circuit breakers, React/Next error boundaries, and the user-message vs operator-log split. NOT diagnosing one specific crash (that is debug), NOT logs/metrics/traces (that is observability), NOT the wire error envelope (that is api-design)."
 tags: [error-handling, resilience, retry, circuit-breaker, error-boundary, typed-errors, fault-tolerance]
 recommends: [debug, observability, monitoring, api-design, secure-coding, testing-web, nextjs]
 origin: risco
@@ -9,23 +9,11 @@ origin: risco
 # Error handling — classify, contain, surface
 
 You are designing what happens *whenever anything in a class breaks*, not chasing
-one crash (that is [`debug`](../debug/SKILL.md)). The deliverable is a typed error
-taxonomy, a retry policy with caps and jitter, boundary placement, and a
+one crash (that is [`debug`](../debug/SKILL.md)). Every failure gets classified,
+contained, and surfaced — never swallowed. The deliverable, in that order: a typed
+error taxonomy, a retry policy with caps and jitter, boundary placement, and a
 two-audience message contract — never a pile of `try { … } catch {}`.
 
-## The one rule
-
-**Every failure gets classified, contained, and surfaced — never swallowed.**
-
-- **Classify** — give the failure a type so the right code can react to the right
-  kind. An untyped `catch (e)` cannot decide anything.
-- **Contain** — stop one failing dependency from taking the process (or the DB)
-  with it. No timeout, no cap = unbounded blast radius.
-- **Surface** — emit two things: a human message that never leaks internals, and
-  an operator log with the full cause chain.
-
-The five steps below are those three jobs in order. Do them in order.
-
 ## Step 1 — Model failure as a taxonomy
 
 Bucket every failure into one of three kinds. The bucket dictates the reaction;
@@ -257,19 +245,6 @@ GOOD → 503 { "code": "upstream_unavailable", "correlationId": "a1b2c3" }
 More before/after rewrites and the copy contract are in
 [`references/boundaries-and-messaging.md`](references/boundaries-and-messaging.md).
 
-## Decision table
-
-| Situation | Reaction |
-|---|---|
-| Expected domain outcome the caller must handle | `Result<T,E>` |
-| Programmer bug / invariant violation | `throw` → nearest boundary |
-| Transient failure on an idempotent call | retry (capped + full jitter) |
-| Transient failure on a mutation without a key | do **not** retry; require idempotency key first |
-| Dependency failing repeatedly | circuit-break + fallback |
-| Failure during React render | `error.tsx` boundary |
-| Failure in an event handler / async callback | explicit `try/catch` + state |
-| Unhandled at the top of the process | process handler → log + exit |
-
 ## Anti-patterns
 
 | Anti-pattern | Why it bites | Fix |
@@ -289,19 +264,10 @@ More before/after rewrites and the copy contract are in
 | One giant `try` around 200 lines | you cannot tell which call failed | scope `try` to the fallible call |
 | Treat every error as a retryable transient | masks real bugs as "flaky" | classify first (Step 1), then react |
 
-## Verification checklist
-
-Before claiming the failure path is handled:
-
-- [ ] Every failure maps to one of the three buckets (Step 1).
-- [ ] No empty `catch {}` / `except: pass` / bare `except:`.
-- [ ] Retries are capped, jittered, transient-only, and idempotent-only.
-- [ ] Every outbound call has a per-attempt timeout.
-- [ ] Repeatedly-failing dependencies have a circuit breaker + fallback.
-- [ ] `error.tsx` / `global-error.tsx` placed correctly; render-only limits known.
-- [ ] User message has no internals + carries a correlation id; the log has the cause chain.
-- [ ] Cause is preserved on every wrap (no lost root error).
+## The gate
 
-Run `scripts/verify.sh <path>` to scan the working tree for the highest-signal
-anti-patterns above. It is **advisory** (exit 0 with warnings); pass `--strict` to
-make any hit fail. It is heuristic — it flags, you judge.
+Before claiming the failure path is handled, read your diff against the table
+above — those rows *are* the checklist. `scripts/verify.sh <path>` scans the
+working tree for the highest-signal ones. It is **advisory** (exit 0 with
+warnings); pass `--strict` to make any hit fail. It is heuristic — it flags,
+you judge.

package/skills/expo/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: expo
-description: "Use when building, shipping, or hot-patching a React Native app with Expo — EAS Build/Submit/Update, eas.json build profiles, config plugins, prebuild/CNG, the managed workflow, confirming you are on the New Architecture (mandatory since SDK 55). Triggers: 'eas build', 'eas.json', 'config plugin', 'expo prebuild', 'my OTA update isn't showing up on devices', 'runtime version mismatch', 'how do I add a permission without editing Xcode/Gradle', 'newArchEnabled is gone from app.json', 'com publico una actualització OTA sense passar per la store', 'subir la app a la Play Store con EAS'. NOT generic React Native components/navigation/native-module authoring (that is react-native), NOT a Dart mobile app (that is flutter)."
+description: "Use when shipping a React Native app with Expo — EAS Build/Submit/Update, eas.json profiles and channels, config plugins, prebuild/CNG, runtime-version policy, OTA updates that never land, SDK upgrades, the New Architecture. NOT RN UI, navigation or native-module authoring (that is `react-native`), NOT a Dart app (that is `flutter`)."
 tags: [expo, eas, react-native, mobile, ota-updates, app-store]
 recommends: [react-native, github-actions, ship, deployment, secure-coding]
 origin: risco
@@ -13,29 +13,19 @@ origin: risco
 Expo is the toolchain and **EAS cloud platform** layered on React Native: cloud
 builds, store submission, over-the-air JS updates, and **native configuration
 declared in JavaScript** instead of hand-edited Xcode/Gradle projects. This skill
-owns the *shipping pipeline* and *native-config-via-JS*. It does **not** own RN UI,
-navigation, animation, or native-module authoring — that is `react-native`.
+owns the *shipping pipeline* and *native-config-via-JS*.
 
 The verb rule of thumb: if the verb is **build / submit / update / prebuild /
 plugin / EAS / channel / runtime-version**, you are in `expo`. If it is **render /
-navigate / animate / bridge / write a native module**, route to react-native.
-(Current stable as of 2026-06-02: **Expo SDK 55** — React Native 0.83.1, React
+navigate / animate / bridge / write a native module**, route to `react-native`.
+Other exits: web React/hooks/state → `react`, a Dart app → `flutter`, native-only
+Swift/Kotlin → `swift-ios`/`kotlin-android`, a desktop wrapper → `tauri`/`electron`,
+CI unrelated to EAS → `github-actions`.
+
+Current stable as of 2026-06-02: **Expo SDK 55** — React Native 0.83.1, React
 19.2.0, shipped 2026-02-25. **SDK 56 is in beta** (beta opened 2026-05-06, ~2-week
 window; RN 0.85.2, React 19.2.3) — upcoming, not yet shipped stable. Both run
-exclusively on the New Architecture; the Legacy Architecture was removed in SDK 55.)
-
-## When to use / when NOT to use
-
-**Use when:** wiring `eas.json` profiles or channels; cloud-building `.ipa`/`.aab`/
-`.apk` and debugging EAS Build/credentials/queues; shipping EAS Update OTA JS
-(runtime policy, branches, channels, rollouts/rollbacks); submitting with EAS
-Submit; writing/debugging config plugins or `app.config.{js,ts}`/prebuild; building
-a dev client; EAS Workflows YAML; migrating to the New Architecture or upgrading SDK.
-
-**Do NOT use when** the work is pure RN code with no Expo/EAS angle (route to
-react-native), web React/hooks/state (`react`), a Dart app (`flutter`), native-only
-Swift/Kotlin (`swift-ios`/`kotlin-android`), a desktop wrapper (`tauri`/`electron`),
-or generic CI unrelated to EAS (`github-actions`).
+exclusively on the New Architecture; the Legacy Architecture was removed in SDK 55.
 
 ## Decision rules
 
@@ -91,6 +81,9 @@ stamped with a `channel`; a channel maps to a same-named EAS Update branch by de
 }
 ```
 
+Run `scripts/verify.sh` inside an Expo project to gate `eas.json`, the runtime
+policy, committed secrets, and New-Arch readiness.
+
 ## EAS Update mental model
 
 Runtime version is the **compatibility gate**. An update applies to a build only
@@ -220,34 +213,26 @@ $50/concurrency/month, up to 5 extra. If a user complains about build queue wait
 the fix is usually the plan, not the config. (Pricing per expo.dev/pricing, verified
 2026-06-02; re-check before quoting — Expo adjusts tiers and dollar figures.)
 
-## Anti-patterns → STOP
+## Anti-patterns
 
-| Rationalization | Reality |
+| Anti-pattern | Do instead |
 |---|---|
-| "I'll just edit `ios/Info.plist` directly" | `prebuild --clean` overwrites it; write a config plugin / `withInfoPlist`. |
-| "Hardcode `runtimeVersion: '1.0.0'`, simpler" | it drifts from the binary; updates silently stop matching. Use the `fingerprint` policy. |
-| "I bumped a native dep, the OTA update will deliver it" | EAS Update is JS-only; native changes need a new `eas build`. |
-| "Published the update, devices just need to refresh" | check the channel→branch and exact runtime match first — wrong channel = no delivery. |
-| "Test this custom native module in Expo Go" | Expo Go can't load arbitrary native code; build a dev client. |
-| "Upgrade the SDK, then build straight to production" | run `expo-doctor` + a preview build first; there is no Legacy-Arch fallback to catch a New-Arch-incompatible dep. |
-| "Set `newArchEnabled: false` to dodge the broken native dep" | the flag was removed in SDK 55 and the Legacy Architecture is gone; fix or replace the dep. |
-| "Commit the keystore so CI can sign" | never; let EAS manage credentials or use EAS secrets. |
-| "Put the API key in `app.config` extra" | app config ships in the public bundle; use EAS env vars / a backend. |
-| "Use GitHub Actions to call `eas build`" | EAS Workflows is the native CI; only reach for github-actions if explicitly required. |
+| Editing `ios/Info.plist` directly | `prebuild --clean` overwrites it; write a config plugin / `withInfoPlist`. |
+| Hardcoding `runtimeVersion: '1.0.0'` because it is simpler | it drifts from the binary; updates silently stop matching. Use the `fingerprint` policy. |
+| Expecting an OTA update to deliver a bumped native dep | EAS Update is JS-only; native changes need a new `eas build`. |
+| Telling users to "just refresh" when a published update does not land | check the channel→branch and exact runtime match first — wrong channel = no delivery. |
+| Testing a custom native module in Expo Go | Expo Go can't load arbitrary native code; build a dev client. |
+| Upgrading the SDK and building straight to production | run `expo-doctor` + a preview build first; there is no Legacy-Arch fallback to catch a New-Arch-incompatible dep. |
+| Setting `newArchEnabled: false` to dodge a broken native dep | the flag was removed in SDK 55 and the Legacy Architecture is gone; fix or replace the dep. |
+| Committing the keystore so CI can sign | never; let EAS manage credentials or use EAS secrets. |
+| Putting the API key in `app.config` extra | app config ships in the public bundle; use EAS env vars / a backend. |
+| Reaching for GitHub Actions to call `eas build` | EAS Workflows is the native CI; only reach for github-actions if explicitly required. |
 
 ## Project grounding (02-DOCS + CLAUDE.md)
 
-When this skill runs in a project with a `02-DOCS/` layer (the
-[`harness`](../harness/SKILL.md) wiki), record this app's shipping decisions —
-managed-vs-bare, the runtime-version policy, channel/branch map, and the SDK/New-Arch
-status — in `02-DOCS/wiki/stack/expo.md` and link it from the root `CLAUDE.md`
-`## Knowledge map`. Read it first on every use; bump its `Updated` date when a
-convention changes. No `02-DOCS/`? Skip silently. Conventions are *recorded, not
-gated* — never block the task on this.
-
-## See also
-
-- `references/eas-update.md` — runtime version policies, channel↔branch ops, rollouts/rollbacks, republish, "update not applying" debug flow.
-- `references/config-plugins.md` — plugin anatomy, mods/dangerous-mods/ordering, common community plugins, prebuild troubleshooting, dynamic `app.config.ts`.
-- `scripts/verify.sh` — run in your Expo project to gate `eas.json`, runtime policy, committed-secret, and New-Arch readiness.
-- Sibling skills: `react-native` (RN UI/navigation/native modules — the other half of every Expo app), `secure-coding` (credential & secret handling), `ship`/`deployment` (release process), `github-actions` (only if you want non-Expo CI).
+In a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md) wiki),
+read `02-DOCS/wiki/stack/expo.md` first and record this app's shipping decisions
+there — managed-vs-bare, runtime-version policy, channel/branch map, SDK/New-Arch
+status — linked from the root `CLAUDE.md` `## Knowledge map`, bumping its `Updated`
+date when a convention changes. No `02-DOCS/`? Skip silently. Conventions are
+*recorded, not gated* — never block the task on this.

package/skills/fal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fal
-description: "Use when calling a fal.ai model endpoint by id to generate an image, audio, or video from JS/Python/curl, wiring the queue (subscribe vs submit), receiving results by webhook and verifying the ED25519 signature, estimating per-call cost, or migrating off the deprecated @fal-ai/serverless-client. Use when a fal request is stuck IN_QUEUE, a webhook never arrives or its signature won't verify, or a long video gen drops mid-call. Triggers: 'generate an image with fal-ai/flux/dev', 'subscribe vs submit on fal', 'my fal webhook signature won't verify', 'fal request stuck IN_QUEUE', 'how much will 500 Seedream images cost on fal', 'migrate off @fal-ai/serverless-client', 'genera esta imagen con fal y guarda la URL', 'munta el webhook de fal i verifica la firma'. NOT picking the model or art direction (that is ai-media)."
+description: "Use when calling a fal.ai endpoint by id to generate image, audio, or video from JS/Python/curl: subscribe vs submit, queue states, ED25519 webhook signature verification, per-call cost, or migrating off @fal-ai/serverless-client. NOT which model or art direction (that is ai-media); NOT the same models on another platform (that is replicate)."
 tags: [fal, fal-ai, inference, image-generation, video-generation, queue, webhooks, serverless]
 recommends: [ai-media, replicate, replicate-images, modal, webhooks]
 origin: risco
@@ -10,16 +10,7 @@ origin: risco
 
 The wire to fal.ai's fast, pre-warmed media endpoints: call a model by id, control the queue, get the file back. fal is the **fast-media path** — latency-optimized image (FLUX, Seedream, SD), audio (TTS, music), and video (Veo, Wan, Kling, Hailuo) endpoints you invoke by id with `FAL_KEY`.
 
-You own the *mechanics*: auth, call mode, queue states, webhook signatures, file I/O, per-call cost. You do not decide *what* to generate or which model is artistically right — that is the strategy layer above you.
-
-## When to use
-
-- Generating media by calling a fal endpoint (`fal-ai/flux/dev`, `fal-ai/veo3`, `fal-ai/wan-2.5`) from JS, Python, or curl.
-- Choosing the call mode: `subscribe` (block + auto-poll) vs `submit` (instant `request_id`) + queue polling or webhook.
-- Receiving a result by webhook and verifying its ED25519 signature; handling retries and idempotency.
-- Uploading local inputs (image-to-image, image-to-video, ref audio) and reading output URLs.
-- Estimating and capping cost: per-image / per-second / per-megapixel / GPU-hour, plus the 50%-off batch path.
-- Migrating off the deprecated `@fal-ai/serverless-client`.
+You own the *mechanics*: auth, call mode, queue states, webhook signatures, file I/O, per-call cost.
 
 ## When NOT to use
 
@@ -203,8 +194,3 @@ The full model-family map and per-modality knob list live in [`references/models
 | Ignoring the model's pricing unit | "$0.05" is per-second, not per-video — surprise bill | Read the pricing tab; pick the right knob |
 | Tight `while` loop on `queue.status` | Hammers the API, gains nothing | Back off, or use a webhook |
 | `@fal-ai/serverless-client` | Deprecated; missing fixes and APIs | `@fal-ai/client` (v1.10.1) |
-
-## References
-
-- [`references/queue-and-webhooks.md`](references/queue-and-webhooks.md) — full async lifecycle, complete ED25519 verification (Node + Python), JWKS caching, IP allowlist, idempotent handler, retry/timeout handling.
-- [`references/models-and-cost.md`](references/models-and-cost.md) — model-family map, pricing-unit cheatsheet with 2026 examples, batch path, per-modality spend knobs, finding an endpoint id and its schema.

package/skills/finance-ops/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: finance-ops
-description: "Use when running the money side of a small company on a cash basis — building a rolling cash-flow forecast, reconciling the bank against the books, fixing a messy expense-category map, or driving a month-end close. Triggers: 'are we going to run out of cash', 'what's our runway', '13-week cash flow forecast', 'reconcile the bank statement', 'these two numbers don't match', 'the ending balance doesn't roll into next week', 'everything landed in Other expenses', 'close the books for May', 'what's our burn this month', 'tancar el mes', 'conciliar el banc amb els llibres', 'cuánto runway nos queda al ritmo actual'. NOT recording journal entries or payroll/depreciation postings (that is bookkeeping)."
+description: "Use when running the money side of a small company on a cash basis: a 13-week rolling cash-flow forecast and runway, bank-vs-books reconciliation, mapping spend to tax-return expense categories, or a month-end close. NOT posting journal entries, payroll or depreciation (that is `bookkeeping`); NOT multi-year projections (that is `financial-model`)."
 tags: [cash-flow, reconciliation, month-close, expense-categories, runway, small-business-finance]
 recommends: [bookkeeping, invoicing, financial-model, unit-economics, cost-tracking, forecasting, spreadsheet-ops]
 origin: risco
@@ -10,13 +10,7 @@ origin: risco
 
 You are the controller for a small company run on a **cash basis**. Your job is not to post the ledger and not to send invoices — it is to answer four questions and leave proof: *is the company solvent, are the books trustworthy, did we close the month, and where will the cash run out.*
 
-Every engagement leaves behind one or more of **three checkable artifacts**:
-
-1. A **13-week rolling cash-flow forecast** (CSV/sheet) — the runway answer.
-2. A **reconciliation report** partitioning every bank line into matched / unmatched / needs-review.
-3. A **month-close checklist** with every gate marked done or blocked.
-
-`scripts/verify.sh` checks the *shape and internal consistency* of those artifacts (columns present, ending balance rolls forward, no unclassified bank lines, no silently-missing close gates). It does not judge whether the dollar figures are right — that is your job.
+Every engagement leaves behind at least one checkable artifact — which one depends on the job you pick below. `scripts/verify.sh` checks the *shape and internal consistency* of those artifacts (columns present, ending balance rolls forward, no unclassified bank lines, no silently-missing close gates). It does not judge whether the dollar figures are right — that is your job.
 
 ## Pick the job first
 
@@ -24,10 +18,10 @@ The flow genuinely branches. Decide which of the four you are doing before touch
 
 | If the ask is… | You are doing | Artifact you produce | Reference |
 |---|---|---|---|
-| "will we run out of cash", "what's our runway", "13-week forecast", "burn rate" | **Forecast** | 13-week rolling forecast CSV | `references/cash-flow-forecast.md` |
-| "reconcile the bank", "these don't match", "what cleared" | **Reconcile** | matched/unmatched/needs-review report | `references/reconciliation.md` |
+| "will we run out of cash", "what's our runway", "13-week forecast", "burn rate" | **Forecast** | 13-week rolling forecast CSV/sheet — the runway answer | `references/cash-flow-forecast.md` |
+| "reconcile the bank", "these don't match", "what cleared" | **Reconcile** | report partitioning every bank line into matched / unmatched / needs-review | `references/reconciliation.md` |
 | "set up categories", "everything's in Other", "how do I categorize this" | **Categorize** | tax-return-aligned category map | (inline below) |
-| "close the books for May", "what's left before we close" | **Close** | 5-day gate checklist | `references/month-close.md` |
+| "close the books for May", "what's left before we close" | **Close** | 5-day checklist, every gate done or blocked | `references/month-close.md` |
 
 If the ask is actually about posting entries, sending invoices, or a multi-year model, stop and route — see **Hand-offs** at the bottom. Do not silently do another skill's job.
 
@@ -105,8 +99,6 @@ A line that is silently dropped is a hole in the books. `verify.sh` fails if any
   - Business meals deductible at **50%** (book them at a rate that preserves the 50% haircut, e.g. category L24b).
   - **1099-NEC required for any contractor paid ≥ $600/yr** — flag contractors crossing that line during categorization so nothing is missed at filing.
 
-Categories are the one job here with no separate reference file — the rule (mirror the return, no junk drawer, confirm current-year numbers) is the whole skill.
-
 ## Month-close
 
 Closing is a **sequenced 5-day checklist, not an event.** Target for a small business: books closed in **≤5 days**.