rsc-universal 0.1.1

package/skills/expo/evals/cases.yaml

@@ -0,0 +1,44 @@
+skill: expo
+
+should_trigger:
+  - prompt: "Set up eas.json with dev, preview, and production profiles and push an iOS build to TestFlight."
+    why: "Core EAS Build + Submit + build-profile configuration — the heart of this skill."
+  - prompt: "My EAS Update published fine but none of the devices ever get the new JS bundle."
+    why: "Non-obvious; the runtime-version exact-match footgun, the #1 reason updates silently never apply."
+  - prompt: "How do I add a custom AndroidManifest permission without ejecting or editing native code?"
+    why: "Config plugin / CNG — declaring native config in JS instead of hand-editing android/."
+  - prompt: "com configuro EAS Update amb branques i canals per a staging i producció?"
+    why: "Catalan; channel/branch model for staged OTA rollouts."
+  - prompt: "expo-doctor says a dependency isn't New-Architecture compatible and newArchEnabled is gone from app.json — how do I ship?"
+    why: "Non-obvious; New Arch is mandatory since SDK 55 with no legacy fallback, so a non-compliant dep is a hard blocker, not a flag flip."
+  - prompt: "Write an EAS Workflow that builds Android then submits to the Play Store."
+    why: "EAS Workflows YAML with build->submit chaining via needs/outputs."
+  - prompt: "subir la app a la Play Store con EAS y configurar el runtimeVersion con fingerprint"
+    why: "Spanish; EAS Submit plus runtime-version policy choice."
+
+should_not_trigger:
+  - prompt: "Build a custom swipeable card list with React Native Reanimated."
+    route_to: "react-native"
+    why: "Pure RN UI/animation, no EAS/Expo toolchain or shipping concern."
+  - prompt: "Set up a GitHub Actions workflow to run my Jest tests on every push."
+    route_to: "github-actions"
+    why: "Generic CI unrelated to EAS Workflows; only route here if the user explicitly wants EAS CI."
+  - prompt: "How do I structure a Flutter app with Riverpod and go_router?"
+    route_to: "flutter"
+    why: "Different ecosystem (Dart), not React Native / Expo."
+  - prompt: "Write a native Swift widget extension for iOS."
+    route_to: "swift-ios"
+    why: "Native-Swift-only work with no Expo/CNG angle."
+  - prompt: "Memoize this React component so it stops re-rendering on every parent update."
+    route_to: "react"
+    why: "Web/component performance, no mobile shipping or native config."
+
+capability:
+  - scenario: "I have an Expo SDK 55 app. Configure eas.json for preview and production, set up EAS Update so I can ship JS fixes safely, and give me the build and submit commands."
+    must_include:
+      - "eas.json with a build.production profile + channel mapping and a preview profile with distribution internal"
+      - "runtimeVersion fingerprint policy recommended (or appVersion), with the exact-match rule explained: an update applies only when BOTH platform AND runtimeVersion match exactly"
+      - "explicit commands: eas build -p ios --profile production and eas submit -p ios --profile production"
+      - "eas update --branch production --message <msg> for JS-only OTA, noting native changes need a new build"
+      - "warning never to hand-edit ios/ or android/ (use a config plugin / prebuild --clean) and never to commit a keystore/.p12/.mobileprovision"
+      - "note that the New Architecture is mandatory since SDK 55 (Legacy Architecture removed, newArchEnabled deleted from app.json) so the app is already on New Arch"

package/skills/expo/references/config-plugins.md

@@ -0,0 +1,117 @@
+# Config plugins & CNG (Continuous Native Generation)
+
+Deep dive for the native-config-via-JS half of the pipeline. With CNG the `ios/` and
+`android/` directories are **ephemeral build artifacts**, regenerated by
+`npx expo prebuild` from `app.config` + the `plugins` array + autolinking. The
+golden rule: **never hand-edit generated native dirs — write a plugin instead.**
+
+## When you need a plugin
+
+You need a config plugin whenever a native change must survive `prebuild --clean`:
+an Info.plist key, an AndroidManifest permission/intent-filter, an entitlement, a
+Gradle/Podfile tweak, an extra resource file. Most popular native libraries ship
+their own plugin — you just add the package name (and options) to `plugins`.
+
+## Anatomy: mods
+
+A config plugin is a function `(config, props) => config`. It usually delegates to a
+**mod** — a hook that runs during a specific prebuild phase and receives the parsed
+native file in `config.modResults`:
+
+| Mod | Edits |
+|---|---|
+| `withInfoPlist` | iOS `Info.plist` |
+| `withEntitlementsPlist` | iOS entitlements |
+| `withAndroidManifest` | `AndroidManifest.xml` |
+| `withStringsXml` / `withAndroidColors` | Android resources |
+| `withAppBuildGradle` / `withProjectBuildGradle` | Gradle |
+| `withPodfile` (dangerous) | iOS Podfile |
+| `withDangerousMod` | raw filesystem access — last resort |
+
+```ts
+// withMicPermission.ts — typed plugin with options, editing both platforms.
+import {
+  ConfigPlugin,
+  withInfoPlist,
+  withAndroidManifest,
+  AndroidConfig,
+} from "expo/config-plugins";
+
+const withMicPermission: ConfigPlugin<{ reason: string }> = (config, { reason }) => {
+  config = withInfoPlist(config, (cfg) => {
+    cfg.modResults.NSMicrophoneUsageDescription = reason;
+    return cfg;
+  });
+  config = withAndroidManifest(config, (cfg) => {
+    AndroidConfig.Permissions.addPermission(
+      cfg.modResults,
+      "android.permission.RECORD_AUDIO",
+    );
+    return cfg;
+  });
+  return config;
+};
+
+export default withMicPermission;
+```
+
+```ts
+// app.config.ts — wire it with options.
+export default {
+  expo: {
+    name: "MyApp",
+    runtimeVersion: { policy: "fingerprint" },
+    plugins: [["./withMicPermission.ts", { reason: "Record voice memos" }]],
+  },
+};
+```
+
+## Mod ordering
+
+Plugins run **top to bottom** in the `plugins` array. Order matters when one plugin
+depends on a file/key another created — put the producer before the consumer.
+Within a single config, base mods run before the platform mods they feed. If a key
+seems to vanish, a later plugin is overwriting it; reorder or merge instead of
+assigning the whole object.
+
+## Dangerous mods
+
+`withDangerousMod` and `withPodfile` give raw filesystem/string access and run
+*outside* the structured merge, so two dangerous mods touching the same file can
+clobber each other silently. Use them only when no structured mod exists, keep the
+edit idempotent (check before you append), and prefer string-anchored insertion over
+full-file rewrites.
+
+## Dynamic app config
+
+`app.config.{js,ts,mjs,cjs,mts,cts}` lets you compute config at evaluation time —
+read environment variables, switch bundle ids per profile, gate plugins by env.
+Keep secrets *out*: anything returned here ships in the public bundle.
+
+```ts
+export default ({ config }) => ({
+  ...config,
+  ios: { bundleIdentifier: process.env.APP_VARIANT === "preview" ? "com.app.pre" : "com.app" },
+});
+```
+
+## Common community plugins
+
+Most are added by package name; many auto-register so you don't even list them.
+Examples: `expo-build-properties` (set iOS deployment target / Android `compileSdk`,
+enable specific build flags), `expo-camera`/`expo-location` (permission strings via
+plugin props), `@react-native-firebase/app` (config files + native setup),
+`react-native-ble-plx` (Bluetooth permission/usage). Always read the library's
+README for its plugin props rather than editing native files by hand.
+
+## Prebuild troubleshooting
+
+- **Change didn't appear** → you edited a generated file; move it into a plugin and
+  rerun `npx expo prebuild --clean`.
+- **Plugin error during prebuild** → run `npx expo prebuild --clean --platform ios`
+  (or `android`) to isolate which platform's mod throws.
+- **Stale native state after an upgrade** → always `prebuild --clean` (not plain
+  `prebuild`) after bumping the SDK or native deps; plain prebuild merges and can
+  keep stale config.
+- **Verify before building** → run `expo-doctor` after editing plugins to catch
+  incompatible versions before paying for a cloud build.

package/skills/expo/references/eas-update.md

@@ -0,0 +1,118 @@
+# EAS Update: runtime versions, channels, rollouts
+
+Deep dive for the OTA-JS half of the pipeline. EAS Update ships **JavaScript and
+asset** changes over the air; anything touching native code needs a new `eas build`.
+
+## The exact-match rule (read this first)
+
+An update is delivered to a build only when **BOTH** of these match **exactly**:
+
+1. the **platform** (`ios` / `android`), and
+2. the **`runtimeVersion`** of the build and the update.
+
+There is no fuzzy/semver matching. A build with runtime `42` will never receive an
+update published under runtime `43`, even if "43 is newer". This single rule
+explains the vast majority of "my update isn't showing up" reports.
+
+## Runtime version policies
+
+Set `runtimeVersion` in `app.config`/`app.json`. Pick a *policy* object, not a
+literal string, so it tracks the native runtime automatically.
+
+| Policy | Behaviour | Use when |
+|---|---|---|
+| `{ "policy": "fingerprint" }` | EAS hashes everything affecting the native runtime (deps, config, plugins) and derives the runtime version; auto-bumps on any native change | **default** — safest; impossible to serve JS to an incompatible binary |
+| `{ "policy": "appVersion" }` | runtime tied to `version` | you already discipline yourself to bump `version` on every native change |
+| `"1.0.0"` (literal) | frozen; you bump by hand | almost never — drifts silently from the binary |
+
+```jsonc
+// GOOD default
+{ "expo": { "runtimeVersion": { "policy": "fingerprint" } } }
+```
+
+`expo-updates` reads this at build time and stamps the binary; the same value is
+computed when you `eas update`, and the two are compared by the exact-match rule.
+
+## Channel → branch → update
+
+- **Channel**: stamped onto each build via the `eas.json` profile's `"channel"`.
+  It is baked into the binary and cannot be changed without a new build.
+- **Branch**: where updates are published. A channel maps to a same-named branch by
+  default; you can repoint a channel to a different branch (e.g. promote `staging`'s
+  branch to the `production` channel) without rebuilding.
+- **Update**: one publish to a branch.
+
+```bash
+eas update --branch production --message "fix checkout copy"
+eas channel:view production          # see which branch a channel points at
+eas channel:edit production --branch release-2025-06   # repoint without rebuilding
+eas branch:list
+eas update:list --branch production
+```
+
+Promotion pattern: build once with the `preview`/`production` channel, publish to
+the `staging` branch, validate, then repoint the `production` channel at that same
+branch — the binary never changes, only which JS it pulls.
+
+## Rollouts and rollbacks
+
+There are two distinct rollout mechanisms; pick by what you are ramping.
+
+**Per-update rollout** (ramp one new update against the branch's prior update):
+publish with `--rollout-percentage <1-100>`, then adjust with `eas update:edit`.
+
+```bash
+# Publish to 10% of the channel's devices, then ramp.
+eas update --branch production --message "v2 flow" --rollout-percentage 10
+eas update:edit --branch production --rollout-percentage 50   # ramp (then 100)
+```
+
+**Branch-based rollout** (gradually switch a channel's traffic to a different
+branch — e.g. a hotfix branch): managed with `eas channel:rollout`.
+
+```bash
+# Start a rollout sending 10% of the production channel to the hotfix branch.
+eas channel:rollout production --action=create --percent=10 --branch=hotfix-123
+eas channel:rollout production --action=edit --percent=50    # ramp
+eas channel:rollout production --action=view                 # inspect state
+eas channel:rollout production --action=end                  # commit / finish
+```
+
+Roll back by republishing the previous good update as the *newest* one (optionally
+itself rolled out gradually), or by repointing the channel:
+
+```bash
+# Republish a known-good update group as the newest update; can itself be staged.
+eas update:republish --branch production --group <previous-update-group-id> --rollout-percentage 100
+
+# Or point a channel back at a known-good branch.
+eas channel:edit production --branch release-last-good
+```
+
+`republish` is preferred over deleting: it makes the older bundle the *newest*
+update on the branch, so devices move forward (clients only ever roll forward to a
+newer update id), not into an undefined state.
+
+## Embedded vs downloaded updates
+
+Every build embeds the JS bundle it was compiled with — that is the fallback shown
+on first launch and offline. Downloaded updates are fetched on the *next* launch
+after the current one (default check-on-launch), not mid-session, unless you call
+the `expo-updates` API to fetch and reload explicitly.
+
+## "Update not applying" — debug flow
+
+Work top to bottom; stop at the first mismatch:
+
+1. **Runtime mismatch?** Compare the build's runtime version with the update's
+   (`eas update:list`). Different → the binary can never see it. Rebuild or
+   republish under the matching runtime.
+2. **Wrong channel/branch?** `eas channel:view <channel>` — is it pointing at the
+   branch you published to? Repoint or republish to the right branch.
+3. **Native change shipped as JS?** If you bumped a native dependency or changed
+   native config, an OTA update cannot deliver it — `eas build` a new binary.
+4. **Rollout < 100%?** A gradual rollout only reaches a fraction of devices; ramp it.
+5. **Launch timing?** The update installs on the *next* cold start; a device that
+   hasn't relaunched still runs the old bundle.
+6. **`expo-updates` disabled / dev build?** Updates are off in development mode and
+   when `expo-updates` isn't installed/configured.

package/skills/expo/scripts/verify.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# verify.sh — Expo / EAS config gate.
+#
+# Run from the root of an Expo project:
+#   bash scripts/verify.sh
+#
+# Checks the EMITTED CONFIG ARTIFACTS, not your process:
+#   1. eas.json parses as JSON and declares a build.production profile.
+#   2. If EAS Update / expo-updates is in use, a runtimeVersion policy is declared
+#      (a hardcoded literal string is WARNED, not failed).
+#   3. No keystore / .p12 / .mobileprovision is tracked, and no obvious plaintext
+#      secret sits in app.config / app.json.
+#   4. Informational: flag dead newArchEnabled config on SDK >= 55 (Legacy
+#      Architecture was removed; the flag no longer exists in app.json).
+#
+# Read-only. Exits 0 on a clean OR empty/non-Expo target (no false failure).
+# Hard violations exit 1; soft issues print warnings only.
+# Portable to stock macOS bash 3.2.
+set -eu
+
+YELLOW=$'\033[1;33m'
+RED=$'\033[0;31m'
+GREEN=$'\033[0;32m'
+RESET=$'\033[0m'
+
+errors=0
+
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$RESET" "$1"; }
+info() { printf '==> %s\n' "$1"; }
+fail() { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$1"; errors=$((errors + 1)); }
+have() { command -v "$1" >/dev/null 2>&1; }
+
+# JSON validity helper: prefer node, fall back to python3, else skip the parse.
+json_valid() {
+  if have node; then
+    node -e "JSON.parse(require('fs').readFileSync('$1','utf8'))" >/dev/null 2>&1
+  elif have python3; then
+    python3 -c "import json,sys; json.load(open('$1'))" >/dev/null 2>&1
+  else
+    return 2  # cannot verify
+  fi
+}
+
+# Guard: only meaningful inside an Expo project. Empty/unrelated dir -> clean exit.
+app_config=""
+for f in app.config.ts app.config.js app.config.mjs app.config.cjs app.json app.config.json; do
+  [ -f "$f" ] && app_config="$f" && break
+done
+
+if [ -z "$app_config" ] && [ ! -f eas.json ]; then
+  warn "no app.config/app.json/eas.json in $PWD — not an Expo project; nothing to check"
+  exit 0
+fi
+
+# 1. eas.json — valid JSON + production profile.
+if [ -f eas.json ]; then
+  info "eas.json"
+  rc=0; json_valid eas.json || rc=$?
+  if [ "$rc" -eq 1 ]; then
+    fail "eas.json is not valid JSON"
+  elif [ "$rc" -eq 2 ]; then
+    warn "no node/python3 on PATH — skipping eas.json JSON parse"
+  fi
+  # production profile (tolerant grep; works even without a JSON parser)
+  if ! grep -Eq '"production"[[:space:]]*:' eas.json; then
+    fail "eas.json has no build.production profile — add one before releasing"
+  fi
+else
+  warn "no eas.json — run 'eas build:configure' to create build profiles"
+fi
+
+# 2. runtimeVersion policy, only if EAS Update / expo-updates is in use.
+uses_updates=false
+if [ -f package.json ] && grep -q 'expo-updates' package.json; then uses_updates=true; fi
+if [ -n "$app_config" ] && grep -q 'expo-updates\|EAS Update\|"updates"' "$app_config"; then uses_updates=true; fi
+
+if [ "$uses_updates" = true ]; then
+  info "runtimeVersion policy (EAS Update detected)"
+  if [ -n "$app_config" ]; then
+    if grep -q 'runtimeVersion' "$app_config"; then
+      # A policy object is good; a bare string literal is a footgun -> warn.
+      if grep -Eq 'runtimeVersion["'\'' ]*:[^{]*"[0-9A-Za-z._-]+"' "$app_config"; then
+        warn "runtimeVersion looks like a hardcoded literal in $app_config — prefer { policy: 'fingerprint' } so it tracks the native runtime"
+      fi
+    else
+      fail "EAS Update is in use but no runtimeVersion is declared in $app_config — add { policy: 'fingerprint' }"
+    fi
+  else
+    warn "EAS Update detected but no app.config to inspect for runtimeVersion"
+  fi
+fi
+
+# 3. Tracked credentials / secrets.
+info "credentials & secrets"
+secret_hits=$(find . \
+  -path ./node_modules -prune -o \
+  -type f \( -name '*.jks' -o -name '*.keystore' -o -name '*.p12' -o -name '*.mobileprovision' \) -print 2>/dev/null)
+if [ -n "$secret_hits" ]; then
+  fail "signing material is present in the tree (let EAS manage credentials, gitignore these):"
+  printf '%s\n' "$secret_hits" | sed 's/^/    /'
+fi
+
+# Plaintext secrets in app config (heuristic).
+if [ -n "$app_config" ]; then
+  if grep -Eiq '(api[_-]?key|secret|password|access[_-]?token|private[_-]?key)["'\'' ]*[:=]["'\'' ]*[A-Za-z0-9_\-]{12,}' "$app_config"; then
+    fail "possible plaintext secret in $app_config — app config ships in the public bundle; use EAS env vars or a backend"
+  fi
+fi
+
+# 4. New Architecture state (informational). Since SDK 55 the Legacy Architecture
+#    is gone and the New Architecture is always on; the newArchEnabled flag was
+#    removed from app.json. On SDK >= 55 any lingering flag is dead config.
+if [ -f package.json ]; then
+  sdk_major=$(grep -Eo '"expo"[[:space:]]*:[[:space:]]*"[~^>=<[:space:]]*[0-9]+' package.json 2>/dev/null \
+    | grep -Eo '[0-9]+$' | head -n1 || true)
+  if [ -n "${sdk_major:-}" ] && [ "$sdk_major" -ge 55 ] 2>/dev/null; then
+    if grep -Eq 'newArchEnabled' "${app_config:-/dev/null}" 2>/dev/null; then
+      warn "newArchEnabled is set in $app_config but was removed in SDK 55 — the New Architecture is always on now; delete the dead flag"
+    else
+      info "SDK $sdk_major detected — Legacy Architecture removed; New Architecture is always enabled"
+    fi
+  elif [ -n "${sdk_major:-}" ] && [ "$sdk_major" -eq 54 ] 2>/dev/null; then
+    info "SDK 54 detected — the last Legacy-Architecture release; SDK 55+ removed it, so plan your upgrade onto New Arch"
+  fi
+fi
+
+# Summary.
+if [ "$errors" -gt 0 ]; then
+  printf '%s%d hard violation(s).%s\n' "$RED" "$errors" "$RESET"
+  exit 1
+fi
+printf '%sall checks passed.%s\n' "$GREEN" "$RESET"

package/skills/fal/SKILL.md

@@ -0,0 +1,210 @@
+---
+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)."
+tags: [fal, fal-ai, inference, image-generation, video-generation, queue, webhooks, serverless]
+recommends: [ai-media, replicate, replicate-images, modal, webhooks]
+origin: risco
+---
+
+# fal
+
+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`.
+
+## When NOT to use
+
+| You want… | Go to |
+| --- | --- |
+| Which model / what to generate / art direction / multi-provider media pipeline | `ai-media` |
+| The same kind of models on **Replicate** (`replicate.run` / predictions) | `replicate` — images-specifically `replicate-images` |
+| Renting a **raw GPU pod** you SSH into to train or custom-serve | `runpod` |
+| Deploying **your own** Python function as an autoscaling endpoint | `modal` |
+| Cheap hosted **LLM text/chat** completions | `together-fireworks` |
+| The generic provider-agnostic webhook receiver/verifier pattern | `webhooks` |
+
+Rule: if you are not invoking a fal endpoint id with `FAL_KEY`, you are in the wrong skill.
+
+## Setup & auth
+
+```bash
+# JS — current client. NOT @fal-ai/serverless-client (deprecated, migrate).
+npm i @fal-ai/client          # latest 1.10.1
+
+# Python
+pip install fal-client
+```
+
+```bash
+export FAL_KEY="key_id:key_secret"
+```
+
+```ts
+import { fal } from "@fal-ai/client";
+// Reads FAL_KEY from env automatically; or set it explicitly:
+fal.config({ credentials: process.env.FAL_KEY });
+```
+
+Rule: **never ship `FAL_KEY` to a browser bundle.** Proxy every call through your own server. Why: a key in client-side JS lets anyone drain your account — fal endpoints bill per call with no per-request cap.
+
+## Pick a call mode
+
+All three modes hit the same queue. Choose by how long the job runs and where you call it from.
+
+| Situation | Mode | Why |
+| --- | --- | --- |
+| Need the result now, can block, single short job (image, short TTS) | `subscribe` | Submits + auto-polls until done; feels synchronous, no polling code |
+| Long job (video), batch, or running in a serverless/edge handler that can't hold a connection | `submit` + `webhook_url` (or poll) | Returns a `request_id` instantly; result arrives later, no held connection |
+| Trivially short call, you accept no queue control | `run` | Direct synchronous call — no status, no logs; drops on long jobs |
+
+```ts
+// Bad: run() on a 60s video — connection can drop, no retry, no progress.
+const res = await fal.run("fal-ai/veo3", { input });
+
+// Good: submit + webhook for anything that takes more than a few seconds.
+const { request_id } = await fal.queue.submit("fal-ai/veo3", {
+  input,
+  webhookUrl: "https://api.example.com/fal/webhook",
+});
+```
+
+## subscribe — block and stream progress
+
+```ts
+const result = await fal.subscribe("fal-ai/flux/dev", {
+  input: { prompt: "a red bicycle on a wet street, cinematic" },
+  logs: true,
+  onQueueUpdate: (update) => {
+    if (update.status === "IN_PROGRESS") {
+      update.logs?.forEach((l) => console.log(l.message)); // stream to user
+    }
+  },
+});
+console.log(result.data.images[0].url); // hosted output URL
+```
+
+```python
+import fal_client
+
+def on_update(update):
+    if isinstance(update, fal_client.InProgress):
+        for log in update.logs:
+            print(log["message"])
+
+result = fal_client.subscribe(
+    "fal-ai/flux/dev",
+    arguments={"prompt": "a red bicycle on a wet street, cinematic"},
+    with_logs=True,
+    on_queue_update=on_update,
+)
+print(result["images"][0]["url"])
+```
+
+Python has an async twin for every method — `subscribe_async`, `submit_async`, `run_async`. Use them inside an event loop.
+
+## submit + queue polling
+
+When you cannot or will not block, submit and poll the queue yourself.
+
+```ts
+const { request_id } = await fal.queue.submit("fal-ai/flux/dev", { input });
+
+// Poll. Status moves IN_QUEUE -> IN_PROGRESS -> COMPLETED.
+const status = await fal.queue.status("fal-ai/flux/dev", {
+  requestId: request_id,
+  logs: true,
+});
+
+// Once COMPLETED, fetch the result.
+const result = await fal.queue.result("fal-ai/flux/dev", { requestId: request_id });
+console.log(result.data.images[0].url);
+```
+
+Rule: **back off between polls** — start at ~1s, grow to a few seconds. Why: a tight `while` loop polling `queue.status` hammers the API and gains nothing; the job finishes when it finishes. For anything long-running, prefer a webhook over any polling at all.
+
+## Webhooks
+
+Pass `webhook_url` (camelCase `webhookUrl` in the JS client) on `submit`; fal POSTs the result when the job finishes.
+
+```jsonc
+// Success
+{ "request_id": "...", "gateway_request_id": "...", "status": "OK", "payload": { /* result */ } }
+// Failure
+{ "request_id": "...", "status": "ERROR", "error": "..." }
+// Result couldn't be serialized
+{ "request_id": "...", "status": "OK", "payload": null, "payload_error": "..." }
+```
+
+Delivery facts you must design for:
+
+- The initial POST has a **15-second timeout**. On timeout or non-2xx, fal **retries up to 10 times over ~2 hours**.
+- Therefore your handler **must be idempotent** — the same `request_id` can arrive more than once. Dedupe on `request_id` (e.g. an upsert keyed on it) before acting.
+- **Verify the ED25519 signature** before trusting the body — four `X-Fal-Webhook-*` headers + a JWKS fetched from `https://rest.fal.ai/.well-known/jwks.json`. Why: an unverified webhook endpoint is a public write to your DB / spend trigger.
+
+The full verification (header parsing, JWKS caching, ±5-minute timestamp check, message construction, per-key verify) and a complete idempotent handler in Node and Python live in [`references/queue-and-webhooks.md`](references/queue-and-webhooks.md).
+
+## File inputs and outputs
+
+Upload a local file to get a URL, then pass that URL into `input` for image-to-X jobs. Outputs always come back as hosted URLs.
+
+```ts
+const url = await fal.storage.upload(file); // File/Blob -> hosted URL
+const out = await fal.subscribe("fal-ai/flux/dev/image-to-image", {
+  input: { image_url: url, prompt: "make it snow" },
+});
+```
+
+```python
+url = fal_client.upload_file("input.png")
+out = fal_client.subscribe(
+    "fal-ai/flux/dev/image-to-image",
+    arguments={"image_url": url, "prompt": "make it snow"},
+)
+```
+
+## Cost control
+
+Pricing is **pay-per-use, per-model unit** — never flat. The unit differs by model, so always read the model's pricing tab before you ship a loop.
+
+| Unit | Used by | 2026 example |
+| --- | --- | --- |
+| Per image | image diffusion | Seedream V4 ~`$0.03`/image |
+| Per second of output | video | Wan 2.5 ~`$0.05`/s; Veo 3 ~`$0.4`/s |
+| Per megapixel | some image models | varies — read the tab |
+| GPU-hour | fal-served compute | A100 40GB `$0.99`/h, H100 80GB `$1.89`/h (2026-05-13) |
+
+Spend knobs, by modality:
+
+- **Image:** lower `num_inference_steps`, drop resolution / megapixels, cut `num_images`.
+- **Video:** shorten `duration`, lower fps/resolution — per-second pricing scales linearly.
+- **Batch:** fal **batch inference is 50% of serverless price** — use it for offline bulk jobs where latency does not matter.
+
+Worked estimate: 500 Seedream V4 images at ~$0.03 ≈ **$15** serverless, ≈ **$7.50** on the batch path.
+
+The full model-family map and per-modality knob list live in [`references/models-and-cost.md`](references/models-and-cost.md).
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| `FAL_KEY` in a browser bundle | Anyone reads it and bills your account | Proxy through your server |
+| `run` for a 30–60s video | Connection drops, no retry, no progress | `submit` + `webhook_url` |
+| Webhook handler with no signature check | Public write / spend trigger anyone can forge | Verify ED25519 against the JWKS |
+| Non-idempotent webhook handler | 10 retries over 2h create duplicate side effects | Dedupe on `request_id` |
+| 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/fal/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — fal
+
+These cases are run by the repo's eval harness: it loads `cases.yaml` and scores the skill's `description` + body against the `should_trigger` / `should_not_trigger` routing and the `capability` rubric. The `should_trigger` prompts (including the non-obvious "subscribe vs submit" and "signature won't verify" ones, and the Spanish webhook prompt) check that fal fires when an agent is wiring a fal endpoint call. The `should_not_trigger` prompts check the boundaries — each `route_to` id (`ai-media`, `replicate`, `runpod`, `modal`) must exist as a sibling skill for the routing to resolve. Because fal emits a checkable artifact (runnable client code + a webhook handler), the `capability` case is the real rigor check: the produced flow must hit every `must_include` item — current client + `FAL_KEY`, `submit` + `webhook_url` for the long job with the why, the webhook payload shape, ED25519 verification against the JWKS, an idempotent handler, reading the output URL, and a per-second cost estimate with the batch path. Run the harness from the repo root against `skills/fal/`.