@ericrisco/rsc 0.1.48 → 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-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/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**.

package/skills/financial-model/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: financial-model
-description: "Use when a founder needs the multi-period, driver-based projection that raises a round and steers the company — build 3-year projections, model revenue + costs + headcount + runway, size the raise, or stress-test scenarios. Triggers: 'build a financial model for our seed', 'model our revenue costs and runway', 'when do we run out of cash', 'how much should we raise to get 24 months', 'what runway does $2M buy us', 'model the hiring plan's effect on burn', 'add a downside scenario if we miss plan by 30%', 'modelo financiero a 3 años', 'cuánto runway nos da la ronda', 'model financer i projeccions', 'quant de pista de despegament'. The engine is assumptions → revenue/cost/headcount builds → cash/burn/runway/scenarios, 18–36 months forward, every output a formula. NOT the next-13-weeks liquidity reconciled to the actual bank balance (that is finance-ops), NOT the isolated LTV/CAC math (that is unit-economics, which this model consumes as drivers), NOT the slide story (that is pitch-deck)."
+description: "Use when a founder needs the driver-based 18–36 month projection: revenue, cost and headcount builds resolving to net burn, runway, cash-out date, scenarios and the raise size. NOT the 13-week bank-reconciled cash view (that is `finance-ops`), NOT single-series forecasting (that is `forecasting`), NOT running the round (that is `fundraising`)."
 tags: [financial-model, projections, runway, burn-rate, fundraising, fp-and-a, forecast]
 recommends: [finance-ops, unit-economics, pricing, forecasting, pitch-deck, investor-materials, fundraising]
 origin: risco
@@ -8,7 +8,7 @@ origin: risco
 
 # Financial model — the projection engine that raises and steers
 
-You are a startup FP&A analyst building the **projection engine**: an assumptions layer that feeds a monthly revenue build, a cost build (COGS + OpEx by function + a headcount plan), and a cash projection that resolves to **net burn, runway, and the cash-out date** — plus a scenario switch (base / downside / upside). It is forward-looking and assumption-driven, 18–36 months out. It is not the controller's short-horizon liquidity tool, not the deck narrative, not the LTV/CAC deep dive. It produces the numbers the fundraising siblings present.
+You are a startup FP&A analyst building the **projection engine**: an assumptions layer that feeds a monthly revenue build, a cost build (COGS + OpEx by function + a headcount plan), and a cash projection that resolves to **net burn, runway, and the cash-out date** — plus a scenario switch (base / downside / upside). It is forward-looking and assumption-driven, 18–36 months out. It produces the numbers the fundraising siblings present.
 
 The test of a model is not "does it look right" but **"does it re-flow when I change three input cells."** A spreadsheet of typed-in numbers is a picture, not a model.
 
@@ -20,18 +20,21 @@ Three connected artifacts, every output traced to an input:
 2. **A monthly projection grid** (CSV/spreadsheet, 18–36 columns) — month index, revenue, COGS, gross margin, OpEx by function, headcount, net burn, starting/ending cash, runway-months. This is what `scripts/verify.sh` checks for shape and internal consistency.
 3. **A scenario + runway summary** — one screen: ending-cash trajectory and runway under base/downside/upside, the raise number, and the burn-multiple / Rule-of-40 cross-check.
 
-## What it does NOT do — route out first
+## Route out first
 
-This skill answers **"how much / what runway / does the plan tie out."** The moment the real ask is something else, stop and route:
+This skill answers **"how much / what runway / does the plan tie out."** The moment the real ask is something else, stop and route — at the intake gate or mid-build:
 
-- Next-13-weeks liquidity reconciled to the **actual bank balance**, this-month burn, are-we-solvent-now → `finance-ops`.
-- Recording actual ledger entries, journals, double-entry, payroll postings → `bookkeeping`.
-- The isolated **LTV / CAC / payback / contribution-margin** math → `unit-economics` (the model imports these as drivers, it does not derive them).
-- Setting the **price / packaging / tier / margin floor** itself → `pricing` (the model takes price as input).
-- Statistical / time-series **forecasting** of a single series (churn, demand, ARR) from history → `forecasting`.
-- The slide **story** and decision-grade headline numbers → `pitch-deck`. Packaging the model into the data room / sending it → `investor-materials`.
-- Round **strategy**, investor pipeline, SAFE-vs-priced, term-sheet mechanics → `fundraising`.
-- Per-unit COGS / infra / AI spend as actuals → `cost-tracking`.
+| The real ask | Route to |
+| --- | --- |
+| Next-13-weeks liquidity reconciled to the **actual bank balance**, this-month burn, are-we-solvent-now | `finance-ops` |
+| Recording actual ledger entries, journals, double-entry, payroll postings | `bookkeeping` |
+| The isolated **LTV / CAC / payback / contribution-margin** math — the model imports these as drivers, it does not derive them | `unit-economics` |
+| Setting the **price / packaging / tier / margin floor** itself — the model takes price as input | `pricing` |
+| Statistical / time-series **forecast** of a single series (churn, demand, ARR) from history | `forecasting` |
+| The slide **story** and decision-grade headline numbers | `pitch-deck` |
+| Packaging the model into the data room / sending it | `investor-materials` |
+| Round **strategy**, investor pipeline, SAFE-vs-priced, term-sheet mechanics | `fundraising` |
+| Per-unit COGS / infra / AI spend as actuals | `cost-tracking` |
 
 ## The intake gate
 
@@ -44,12 +47,6 @@ Pin four inputs before you build a single cell. Without them the model is fictio
 | **Current revenue / MRR + recent growth** | the base the revenue build grows from, not a fresh hockey stick |
 | **Target raise & horizon** (or "size it for me") | the model either takes the raise as input or solves for it from a runway target |
 
-STOP-and-route at the gate:
-
-- If the ask is "what does next quarter's cash look like against the bank" → that is the 13-week tool, route to `finance-ops`.
-- If the ask is "what's our LTV and CAC" with no projection attached → route to `unit-economics`; come back when you need them as drivers.
-- If the ask is "what should we charge" → route to `pricing`; the model takes the price it sets.
-
 ## Rule 1 — three layers, no hardcoded outputs
 
 The model is a connected system: **assumptions → drivers → outputs.** Changing a few input cells must re-flow the whole plan. Hardcoded outputs that don't recompute are the cardinal modeling sin — they pass inspection and then silently lie the moment an assumption moves.
@@ -131,7 +128,7 @@ Most companies miss Rule of 40 — McKinsey's run of 200+ software firms (2011
 
 ## Anti-patterns
 
-| Bad | Good | Why |
+| Anti-pattern | Do instead | Why |
 | --- | --- | --- |
 | Hockey-stick revenue, one line, no downside | base / downside / upside off toggled drivers | investors stress-test the downside first; no downside reads as naive |
 | Runway computed from net income / P&L | runway from cash balance ÷ net cash burn | depreciation, prepaids, AR make profit ≠ cash; cash is the survival line |
@@ -152,19 +149,4 @@ The model emits a checkable artifact, so `scripts/verify.sh` runs against your g
 ./scripts/verify.sh --strict             # treat warnings as failures (CI gate)
 ```
 
-It checks: required columns present (month, revenue, cogs, gross_margin, opex, net_burn, ending_cash, runway_months); **cash continuity** (ending_cash[m] == starting_cash[m+1]); **gross_margin == (revenue − COGS)/revenue** recomputes; **net_burn == gross_burn − revenue** ties; runway_months ties to cash ÷ net_burn; ≥1 scenario present; and a defect lint for placeholders (`TBD`, `XX`, `#REF`, `[assumption]`) and impossible values (gross margin >100%/<−100%, negative headcount). It exits 0 on a clean or empty target — a missing file is a skip, never a false failure. The schema it enforces is documented in `references/model-structure.md`.
-
-## Hand-offs
-
-- Need the LTV/CAC/payback that feed the drivers → `unit-economics`.
-- Price/packaging the model assumes → `pricing`.
-- Single-series statistical forecast of churn/ARR → `forecasting`.
-- The near-term bank-reconciled cash view → `finance-ops`.
-- Turn the numbers into the slide story → `pitch-deck`; into the data room → `investor-materials`.
-- Run the actual round off the raise number → `fundraising`.
-
-## references/
-
-- `references/revenue-build.md` — bottom-up funnel template, the MRR new/expansion/contraction/churn waterfall, the top-down TAM cross-check, and a worked monthly build.
-- `references/benchmarks-and-scenarios.md` — the 2025/26 benchmark sanity-table, the base/downside/upside driver-toggle recipe, and a worked runway-under-scenarios example.
-- `references/model-structure.md` — the assumptions/projection row+column contract `verify.sh` enforces, the cash-continuity rule, and the `model.csv` schema with a filled mini-example.
+It checks: required columns present (month, revenue, cogs, gross_margin, opex, net_burn, ending_cash, runway_months); **cash continuity** (ending_cash[m] == starting_cash[m+1]); **gross_margin == (revenue − COGS)/revenue** recomputes; **net_burn == gross_burn − revenue** ties; runway_months ties to cash ÷ net_burn; ≥1 scenario present; and a defect lint for placeholders (`TBD`, `XX`, `#REF`, `[assumption]`) and impossible values (gross margin >100%/<−100%, negative headcount). It exits 0 on a clean or empty target — a missing file is a skip, never a false failure. The row+column contract it enforces, the cash-continuity rule, and the `model.csv` schema with a filled mini-example are in `references/model-structure.md`.

package/skills/finetuning/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: finetuning
-description: "Use when adapting an open-weight model to a target FORM or BEHAVIOR — tone, output format, domain style, a reasoning/tool-calling pattern — via LoRA/QLoRA or full fine-tuning with TRL SFTTrainer and then preference optimization (DPO/ORPO/KTO/GRPO); when choosing fine-tune vs prompt vs RAG vs longer context; when setting LoRA r/alpha/target_modules; when eval loss climbs while train loss keeps falling; when the adapter seems to have learned nothing; when inference outputs garbage after a run. Triggers: 'fine-tune Llama/Qwen on our data', 'LoRA vs QLoRA vs full fine-tune', 'SFT then DPO/ORPO/KTO/GRPO', 'set target_modules / rank / alpha', 'my fine-tune overfits', 'the model forgot everything after training', 'write a GRPO reward function', 'ajustar un modelo amb LoRA amb les nostres dades'. NOT adding facts or fresh knowledge to a model (that is rag); NOT the fast single-GPU Unsloth backend or GGUF export (that is unsloth); NOT serving the trained model (that is vllm)."
+description: "Use when adapting an open-weight model to a target form or behavior — tone, output format, reasoning pattern — via LoRA/QLoRA or full fine-tuning with TRL SFTTrainer, then preference optimization (DPO/ORPO/KTO/GRPO), and for fine-tune vs prompt vs RAG. NOT adding facts to a model (that is rag); NOT the single-GPU Unsloth backend or GGUF export (that is unsloth)."
 tags: [finetuning, lora, qlora, sft, dpo, grpo, peft, trl, preference-optimization]
 recommends: [training-data, unsloth, open-weights, huggingface, vllm, rag]
 origin: risco
@@ -33,8 +33,10 @@ row below is a real off-ramp.
 
 Route out explicitly. Facts / freshness / citations → `../rag/SKILL.md`. Squeezing a prompt before
 spending money → `prompt-engineering`. Picking *which* base model (size/license/task) → `open-weights`.
-Building the JSONL/preference corpus → `training-data`. A fast single-GPU run + GGUF export →
-`../unsloth/SKILL.md`. Serving the result → `../vllm/SKILL.md`.
+Building the JSONL/preference corpus → `training-data` (LLM corpora, NOT tabular cleaning — that is
+`data-cleaning`). A fast single-GPU run + GGUF export → `../unsloth/SKILL.md` (same LoRA/QLoRA
+concepts, one optimized implementation; this skill stays backend-agnostic). Downloading the base or
+pushing the adapter/merged model → `huggingface`. Serving the result → `../vllm/SKILL.md`.
 
 > The cheapest fine-tune is the one you didn't need. Prompt + RAG solves most "make it behave"
 > asks at zero training cost and updates instantly. Fine-tune when that ceiling is real, measured,
@@ -201,6 +203,8 @@ score). Judge the run on that, plus **eval loss**.
   eval; keep the held-out set quarantined. (Corpus-side hygiene is `training-data`.)
 - General LLM/agent eval harness and judging → `agent-eval`. Bring your task metric here.
 
+The full tuning + forgetting + evaluation playbook is in `references/hyperparameters-and-eval.md`.
+
 ## When NOT to fine-tune (anti-patterns)
 
 | Anti-pattern | Why it breaks | Do instead |
@@ -214,19 +218,6 @@ score). Judge the run on that, plus **eval loss**.
 | A few dozen examples for full FT | Not enough signal; unstable | Curate ~hundreds–thousands (LIMA) or use LoRA |
 | Fine-tune a model you can't legally deploy | License blocks your use case | Check the model card first → `open-weights` |
 
-## Related skills
-
-- **`../rag/SKILL.md`** — the fork of the decision gate: facts/freshness/citations live there;
-  form/behavior lives here. Most "make it behave" asks are RAG or prompting, not training.
-- **`prompt-engineering`** — the cheaper lever to exhaust before spending a GPU.
-- **`training-data`** — builds/validates the JSONL `messages` and preference-pair corpus you feed
-  here (LLM corpora, NOT tabular cleaning — that is `data-cleaning`).
-- **`open-weights`** — chooses *which* base model by task/size/license; you consume that choice.
-- **`../unsloth/SKILL.md`** — a fast single-GPU training backend + GGUF export; same LoRA/QLoRA
-  concepts, one optimized implementation. This skill stays backend-agnostic.
-- **`huggingface`** — download the base, push the adapter/merged model, host inference (NOT training).
-- **`../vllm/SKILL.md`** — serves the trained/merged model (adapter hot-swap, throughput flags).
-
 ## Checklist
 
 - [ ] Ran the decision gate: confirmed this is a form/behavior need, not a facts need (else → rag).
@@ -239,6 +230,3 @@ score). Judge the run on that, plus **eval loss**.
 - [ ] Trained 1–3 epochs; watched **eval** loss (not train) for the overfitting turn.
 - [ ] Preference stage only if needed; correct method for the data (pairs→DPO/ORPO, votes→KTO, verifier→GRPO); tiny LR.
 - [ ] Verified `trl`/`peft`/`transformers` current majors and import paths at author time.
-
-See `references/methods.md` for full SFT→DPO/GRPO/ORPO/KTO scripts, dataset schemas, and adapter
-merging; `references/hyperparameters-and-eval.md` for the tuning + forgetting + evaluation playbook.