rsc-universal 0.1.1

package/skills/financial-model/scripts/verify.sh

@@ -0,0 +1,232 @@
+#!/usr/bin/env bash
+#
+# verify.sh — internal-consistency gate for the `financial-model` skill.
+#
+# WHAT IT DOES (read-only; never edits a file)
+#   Static checks over a generated model CSV (assumptions + monthly projection
+#   grid). It validates that the model COMPUTES AND TIES OUT — never whether the
+#   forecast is wise. For each model.csv found:
+#     1. Required columns present: month, revenue, cogs, gross_margin, opex,
+#        net_burn, ending_cash, runway_months (headcount/starting_cash/gross_burn
+#        checked when present).
+#     2. Cash continuity: ending_cash[m] == starting_cash[m+1].
+#     3. Recompute (no hardcoded outputs):
+#        gross_margin == (revenue-cogs)/revenue; net_burn == gross_burn-revenue;
+#        runway_months == starting_cash/net_burn (when net_burn>0).
+#     4. Scenario coverage: >=1 scenario present; if a `scenario` column exists
+#        and the file claims multiple, expect >=3 distinct values.
+#     5. Defect lint: placeholders (TBD, XX, #REF, [assumption], ???) -> fail;
+#        impossible values (gross_margin >1 or <-1, negative headcount) -> fail.
+#
+#   A missing/empty target is a SKIP, never a failure. Numeric checks tolerate
+#   small rounding (default 1%). Floating math uses awk (POSIX), so no bc needed.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh                      # scan ./ for *model*.csv
+#   ./verify.sh --path model.csv     # check one file
+#   ./verify.sh --path build/        # scan a directory of model CSVs
+#   ./verify.sh --tol 0.02           # widen the recompute tolerance to 2%
+#   ./verify.sh --strict             # treat warnings as failures (CI gate)
+#
+# EXIT CODES
+#   0  clean, empty target, or warnings only without --strict
+#   1  a real failure (broken tie-out, placeholder, impossible value)
+#   2  bad usage
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+ok_count=0; skip_count=0; warn_count=0; fail_count=0
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; ok_count=$((ok_count + 1)); }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; skip_count=$((skip_count + 1)); }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+usage() { sed -n '2,40p' "$0" | sed 's/^# \{0,1\}//'; }
+
+SCAN_PATH="."
+STRICT=0
+TOL="0.01"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --path)   SCAN_PATH="${2:?--path needs a value}"; shift 2 ;;
+    --tol)    TOL="${2:?--tol needs a value}"; shift 2 ;;
+    --strict) STRICT=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) printf '%sUnknown argument: %s%s\n\n' "$RED" "$1" "$NC"; usage; exit 2 ;;
+  esac
+done
+
+if [ ! -e "$SCAN_PATH" ]; then
+  skip "path not found: $SCAN_PATH — nothing to check"
+  printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+  exit 0
+fi
+
+have() { command -v "$1" >/dev/null 2>&1; }
+if ! have awk; then
+  skip "awk not found — cannot parse CSV; install awk"
+  printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+  exit 0
+fi
+
+# Collect candidate model CSVs.
+FILES=""
+if [ -f "$SCAN_PATH" ]; then
+  case "$SCAN_PATH" in *.csv) FILES="$SCAN_PATH" ;; *) FILES="$SCAN_PATH" ;; esac
+else
+  FILES="$(find "$SCAN_PATH" -type f -name '*.csv' \( -iname '*model*' -o -iname '*projection*' -o -iname '*forecast*' \) 2>/dev/null || true)"
+  if [ -z "$FILES" ]; then
+    FILES="$(find "$SCAN_PATH" -type f -name '*.csv' 2>/dev/null || true)"
+  fi
+fi
+
+if [ -z "$FILES" ]; then
+  skip "no model CSV found under $SCAN_PATH — nothing to check (clean)"
+  printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+  exit 0
+fi
+
+# check_one <file>: runs all checks, prints findings, returns nothing.
+# Uses a single awk pass that emits "LEVEL message" lines; the shell tallies.
+check_one() {
+  f="$1"
+  [ -s "$f" ] || { skip "empty file: $f"; return; }
+  printf '%s—— %s%s\n' "$YELLOW" "$f" "$NC"
+
+  # Placeholder lint (whole file, case-insensitive).
+  if grep -niE 'TBD|#REF|\[assumption\]|\?\?\?|(^|[,;[:space:]])XX([,;[:space:]]|$)' "$f" >/dev/null 2>&1; then
+    fail "$f: placeholder token (TBD/XX/#REF/[assumption]/???) present"
+    grep -niE 'TBD|#REF|\[assumption\]|\?\?\?' "$f" 2>/dev/null | head -n 3 | sed 's/^/        /'
+  else
+    ok "$f: no placeholder tokens"
+  fi
+
+  out="$(awk -v tol="$TOL" '
+    BEGIN { FS=","; }
+    NR==1 {
+      for (i=1;i<=NF;i++){ h=tolower($i); gsub(/^[ \t"]+|[ \t"]+$/,"",h); col[h]=i }
+      # required columns
+      req="month revenue cogs gross_margin opex net_burn ending_cash runway_months"
+      n=split(req,r," ")
+      miss=""
+      for (k=1;k<=n;k++){ if(!(r[k] in col)) miss=miss" "r[k] }
+      if(miss!="") print "FAIL missing required column(s):"miss
+      else print "OK all required columns present"
+      next
+    }
+    # skip blank lines
+    NF<2 { next }
+    {
+      rows++
+      # helper to fetch a numeric cell by header name
+      mrev=val("revenue"); mcogs=val("cogs"); mgm=val("gross_margin");
+      mnb=val("net_burn"); mec=val("ending_cash"); msc=val("starting_cash");
+      mgb=val("gross_burn"); mhc=val("headcount"); mrm=val("runway_months");
+
+      # impossible: gross margin out of [-1,1]
+      if (("gross_margin" in col) && mgm!="" && (mgm>1.0000001 || mgm< -1.0000001))
+        print "FAIL row "rows": gross_margin "mgm" outside [-1,1]"
+      # impossible: negative headcount
+      if (("headcount" in col) && mhc!="" && mhc < -0.0000001)
+        print "FAIL row "rows": negative headcount "mhc
+
+      # recompute gross_margin
+      if (("revenue" in col)&&("cogs" in col)&&("gross_margin" in col)&&mrev!=""&&mrev!=0&&mcogs!=""&&mgm!="") {
+        xp=(mrev-mcogs)/mrev
+        if (reldiff(xp,mgm) > tol)
+          print "FAIL row "rows": gross_margin "mgm" != (rev-cogs)/rev "xp
+      }
+      # recompute net_burn = gross_burn - revenue
+      if (("gross_burn" in col)&&("revenue" in col)&&("net_burn" in col)&&mgb!=""&&mrev!=""&&mnb!="") {
+        xp=mgb-mrev
+        if (absdiff(xp,mnb) > tol*(absv(exp)+1))
+          print "FAIL row "rows": net_burn "mnb" != gross_burn-revenue "xp
+      }
+      # recompute runway_months = starting_cash / net_burn (net_burn>0)
+      if (("starting_cash" in col)&&("net_burn" in col)&&("runway_months" in col)&&msc!=""&&mnb!=""&&mnb>0&&mrm!="") {
+        xp=msc/mnb
+        if (reldiff(xp,mrm) > tol*5)   # runway often rounded to 1dp; loosen
+          print "FAIL row "rows": runway_months "mrm" != cash/net_burn "xp
+      }
+      # cash continuity: ending_cash[m] == starting_cash[m+1]
+      if (("ending_cash" in col)&&("starting_cash" in col)) {
+        if (rows>1 && prev_ec!="" && msc!="") {
+          if (absdiff(prev_ec,msc) > tol*(absv(prev_ec)+1))
+            print "FAIL row "rows": starting_cash "msc" != prior ending_cash "prev_ec
+        }
+        prev_ec=mec
+      }
+      # scenario tracking
+      if ("scenario" in col) { sc=raw("scenario"); if(sc!=""){ if(!(sc in seen)){seen[sc]=1; nsc++} } }
+    }
+    END {
+      if (rows==0) { print "WARN no data rows"; }
+      else print "OK "rows" data rows parsed"
+      if ("scenario" in col) {
+        if (nsc>=1) print "OK scenario column present ("nsc" distinct)"
+        if (nsc==2) print "WARN only 2 scenarios; base/downside/upside expects 3"
+      } else {
+        print "WARN no scenario column — at least a base scenario should be labeled"
+      }
+    }
+    function val(name,   v){ if(!(name in col)) return ""; v=$(col[name]); gsub(/[ \t"$,%]/,"",v); if(v=="")return ""; if(v+0==v) return v+0; return "" }
+    function raw(name,   v){ if(!(name in col)) return ""; v=$(col[name]); gsub(/^[ \t"]+|[ \t"]+$/,"",v); return v }
+    function absv(x){ return x<0?-x:x }
+    function absdiff(a,b){ return absv(a-b) }
+    function reldiff(a,b){ d=absv(a-b); m=absv(a); if(m<1) m=1; return d/m }
+  ' "$f" 2>/dev/null)"
+
+  # tally awk findings
+  if [ -n "$out" ]; then
+    printf '%s\n' "$out" | while IFS= read -r line; do
+      case "$line" in
+        FAIL*) printf '%s[fail]%s %s: %s\n' "$RED" "$NC" "$f" "${line#FAIL }" ;;
+        WARN*) printf '%s[warn]%s %s: %s\n' "$YELLOW" "$NC" "$f" "${line#WARN }" ;;
+        OK*)   printf '%s[ ok ]%s %s: %s\n' "$GREEN" "$NC" "$f" "${line#OK }" ;;
+      esac
+    done
+    nf=$(printf '%s\n' "$out" | grep -c '^FAIL' || true)
+    nw=$(printf '%s\n' "$out" | grep -c '^WARN' || true)
+    no=$(printf '%s\n' "$out" | grep -c '^OK'   || true)
+    fail_count=$((fail_count + nf))
+    warn_count=$((warn_count + nw))
+    ok_count=$((ok_count + no))
+  fi
+}
+
+printf 'Checking model CSVs under: %s (tol=%s)\n\n' "$SCAN_PATH" "$TOL"
+printf '%s\n' "$FILES" | while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  check_one "$f"
+done > /tmp/fm_verify.$$ 2>&1 || true
+cat /tmp/fm_verify.$$
+# re-tally from the captured output (subshell counters don't propagate under bash 3.2).
+# grep -c always prints a count but exits 1 on zero matches, so swallow status and
+# strip to digits to avoid concatenating a fallback.
+tally() { { grep -c "$1" /tmp/fm_verify.$$ 2>/dev/null || true; } | tr -dc '0-9'; }
+fail_count=$(tally '\[fail\]'); fail_count=${fail_count:-0}
+warn_count=$(tally '\[warn\]'); warn_count=${warn_count:-0}
+ok_count=$(tally '\[ ok \]');   ok_count=${ok_count:-0}
+skip_count=$(tally '\[skip\]'); skip_count=${skip_count:-0}
+rm -f /tmp/fm_verify.$$ 2>/dev/null || true
+
+printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+
+cat <<'EOF'
+
+Note: this gate proves the model COMPUTES AND TIES OUT (continuity, recompute,
+no placeholders). It does NOT judge whether the assumptions are wise — that is
+the capability eval's job. Re-run with --strict to gate CI on a clean pass.
+EOF
+
+if [ "$fail_count" -gt 0 ]; then exit 1; fi
+if [ "$STRICT" -eq 1 ] && [ "$warn_count" -gt 0 ]; then exit 1; fi
+exit 0

package/skills/firebase/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: firebase
+description: "Use when building on Firebase — modeling Firestore data, writing or auditing Security Rules, wiring Auth, shipping Cloud Functions, storing files in Cloud Storage, or choosing modular Web/Admin SDK imports — and when symptoms appear like 'my database is open to the internet', 'rules reject my query', a counter stuck at 1 write/sec, custom-claim RBAC, or a callable function. Triggers: 'firestore.rules audit', 'denormalize for read paths', 'collection vs subcollection', 'my query works in the emulator but fails in prod with requires-an-index', 'set a custom admin claim', 'regles de seguretat de Firestore', 'mi base de datos está abierta a internet'. NOT managed-Postgres BaaS with SQL and RLS (that is supabase)."
+tags: [firebase, firestore, security-rules, cloud-functions, auth]
+recommends: [secure-coding, gcp-essentials, nextjs]
+origin: risco
+---
+
+# Firebase — Firestore, Rules, Auth, Functions, Storage
+
+Build correctly on the Firebase product surface that sits on top of GCP: model Firestore data,
+write and test Security Rules, wire Auth, ship Cloud Functions, and store files — all on the
+modular Web SDK (v12) and the Admin SDK. The whole skill exists to stop two failure modes: dragging
+relational/SQL habits into a NoSQL document store, and leaving the database open to the internet.
+
+Hold these three facts the entire time:
+
+- **It is a NoSQL document store.** No joins, no server-side `OR` across different fields without a
+  composite index, no `SELECT *` across collections. You shape data for the read path, not for
+  normalization.
+- **Rules ARE the access control.** Firestore is reachable directly from untrusted clients. There is
+  no app server in the trust path by default — `firestore.rules` (CEL) is the only thing between a
+  browser and your data. App Check attests the request even came from your app before Rules evaluate.
+- **Shape data for reads.** Denormalize and fan-out so a screen is one cheap query. Reads are the
+  thing you pay for and the thing users wait on.
+
+## When to use / When NOT to use
+
+**When to use:**
+
+- Firestore data modeling: collections vs subcollections, denormalization, fan-out, the 1 MiB
+  document limit, hotspot avoidance, query constraints.
+- Writing or auditing Firestore/Storage Security Rules and testing them with the emulator.
+- Firebase Auth: providers, ID-token verification on the server, custom claims, session cookies.
+- Cloud Functions (2nd gen): Firestore/HTTPS/callable/Auth-blocking triggers, secrets, idempotency.
+- Cloud Storage uploads/downloads gated by Rules + signed URLs.
+- Modular SDK imports for tree-shaking, `firebase.json` / `firestore.indexes.json`, Emulator Suite.
+
+**When NOT to use:**
+
+- Relational schema, SQL, EXPLAIN, indexing a SQL engine → `../postgresdb/SKILL.md`.
+- Managed Postgres BaaS (SQL + Postgres RLS + PostgREST) → `supabase`. This is the most-confused
+  sibling: same "backend-as-a-service" shape, but a completely different data model and rules language.
+- AWS document/key-value store with its own capacity model → `dynamodb`.
+- Self-hosted Mongo document modeling → `mongodb`.
+- Generic GCP project/IAM/billing not specific to a Firebase product → `gcp-essentials`.
+- React/Next.js component or rendering work that merely calls Firebase → `react` / `../nextjs/SKILL.md`.
+
+## Data modeling
+
+Firestore charges and waits on reads. Model so the common screen is one query against one collection.
+
+**Collection vs subcollection vs root + denormalized field — decide by access pattern:**
+
+| Shape | Use when | Why |
+|---|---|---|
+| Subcollection (`rooms/{id}/messages`) | Child list is only ever read inside its parent, can grow unbounded | Subcollections don't bloat the parent doc; deleting a parent does NOT delete them (handle that) |
+| Separate root collection + foreign id | Child must be queried across all parents (collection-group query) | A `collectionGroup('messages')` query needs the docs in same-named subcollections OR a root collection |
+| Denormalized field on the parent | A few values are shown alongside the parent and rarely change | Avoids a second read; you accept writing the copy on every change |
+
+**Hard limits — design around them, don't discover them in prod:**
+
+- A document maxes out at **1 MiB (1,048,576 bytes)**. Don't accumulate an unbounded array (chat
+  messages, audit log) inside one doc — it will hit the wall and every read pays for the whole blob.
+  Use a subcollection.
+- A single document tolerates only **~1 sustained write/sec**. Monotonic IDs and indexed sequential
+  timestamps create a hotspot on one index range. Use scattered auto-IDs (`doc(collection(db,'x'))`),
+  and for high-frequency counters use a **sharded counter** (N shard docs, sum on read).
+
+**Query reality:** no joins; range/inequality filters on a field plus an `orderBy` on another field
+require a **composite index**; `in` / `array-contains-any` are capped (~30 values). If a query needs
+an index, declare it in `firestore.indexes.json` — see the emulator gotcha below.
+
+```ts
+// Bad — unbounded array inside one doc; hits 1 MiB, every read pays for all of it
+await setDoc(doc(db, "rooms", roomId), { messages: [...allMessages, newMsg] });
+
+// Good — one doc per message in a subcollection, scattered auto-ID, no hotspot
+await addDoc(collection(db, "rooms", roomId, "messages"), {
+  text, authorId, createdAt: serverTimestamp(),
+});
+```
+
+Denormalization recipes, counter sharding, cursor pagination, `getCountFromServer`, collection-group
+queries, and composite-index design live in `references/data-modeling.md`.
+
+## Security Rules — the load-bearing section
+
+**Rules are NOT filters.** A query is rejected outright unless the rules can guarantee *every* matched
+document is readable — Firestore will not silently drop the docs you can't see. So a `list` rule and
+the query that runs against it must agree: if the rule allows reading only your own docs, the query
+must itself be constrained (`where("ownerId","==",uid)`), or the whole query fails.
+
+```javascript
+// Bad — the entire database is readable AND writable by anyone on the internet
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+    match /{document=**} { allow read, write: if true; }
+  }
+}
+
+// Good — default-deny, ownership-scoped, with create-time validation
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+    match /posts/{postId} {
+      allow get:    if resource.data.ownerId == request.auth.uid;
+      allow list:   if request.auth != null;            // query MUST add where(ownerId == uid)
+      allow create: if request.auth.uid == request.resource.data.ownerId;
+      allow update, delete: if resource.data.ownerId == request.auth.uid;
+    }
+    // everything else: no rule = denied
+  }
+}
+```
+
+Rules to internalize:
+
+- **Default-deny.** No matching `allow` = denied. Never add a `/{document=**}` catch-all with
+  `if true`. That single line is the "open to the internet" headline risk.
+- **`request.auth`** is the authenticated identity (null when signed out); `request.auth.token`
+  carries **custom claims** for RBAC (e.g. `request.auth.token.admin == true`).
+- **`resource.data`** is the existing doc; **`request.resource.data`** is the incoming write. Validate
+  the incoming write on `create`/`update` (types, immutable `ownerId`, no privilege escalation).
+- **`get()` / `exists()`** read another doc for cross-document checks (e.g. role lookup) — each costs
+  a billed read and counts against rule-evaluation limits, so keep them shallow.
+- **`get` vs `list`** are distinct: a single-doc read vs a query. `read` = both; split them so a
+  query can't leak documents a single `get` would also have blocked.
+
+Set custom claims with the Admin SDK, never from the client. Add **App Check** in production so Rules
+only run for requests that provably came from your real app.
+
+Full CEL patterns — RBAC via claims, ownership, validation functions, time-based throttling, and the
+complete `@firebase/rules-unit-testing` recipe — are in `references/security-rules.md`.
+
+## Auth
+
+- **Client sign-in** with `getAuth()` + a provider; the SDK manages the refresh of the ID token.
+- **Server-side, verify the ID token** with `getAuth(adminApp).verifyIdToken(idToken)` before trusting
+  any caller. A raw UID from the client is not proof of anything.
+- **Custom claims for RBAC:** `getAuth(adminApp).setCustomUserClaims(uid, { admin: true })`. Claims
+  land in `request.auth.token` in Rules and in the decoded token on the server. They refresh on the
+  client's next token refresh, not instantly — force a refresh if you need it immediately.
+- **Session cookies** (`createSessionCookie`) suit SSR / server-rendered apps where you want an
+  httpOnly cookie instead of shipping the ID token to every request — pairs with `../nextjs/SKILL.md`.
+
+## Cloud Functions (2nd gen)
+
+2nd gen is the default and the only generation that runs **Node.js 22**. Use `firebase-functions` v7
+modular triggers and `firebase-admin`.
+
+```ts
+import { onDocumentWritten } from "firebase-functions/v2/firestore";
+import { onCall, HttpsError } from "firebase-functions/v2/https";
+import { defineSecret } from "firebase-functions/params";
+
+const STRIPE_KEY = defineSecret("STRIPE_KEY"); // never hard-code secrets
+
+export const onPostWrite = onDocumentWritten(
+  { document: "posts/{postId}", region: "europe-west1" },
+  async (event) => {
+    // Background events deliver AT-LEAST-ONCE — make this idempotent.
+    const eventId = event.id; // dedupe on this (e.g. a processed/{eventId} marker doc)
+  }
+);
+
+export const setAdminClaim = onCall(async (request) => {
+  if (request.auth?.token.admin !== true) throw new HttpsError("permission-denied", "admins only");
+  // ... verify, then setCustomUserClaims via admin SDK
+});
+```
+
+- **Callable** (`onCall`) gives you `request.auth` already verified; raw **`onRequest`** HTTPS does not
+  — you must verify the ID token yourself.
+- **Idempotency is mandatory** for background triggers (`onDocumentWritten` etc.): events can fire more
+  than once, so guard side effects with the event id.
+- Pin **region**, set **secrets** with `defineSecret` (not env literals), and tune concurrency for cost.
+- Functions require the **Blaze** plan; outbound networking from a function also requires Blaze.
+
+Trigger catalogue, callable-vs-HTTPS auth, idempotency keys, cold-start/cost, Auth blocking functions,
+and region pinning are in `references/cloud-functions.md`.
+
+## Cloud Storage
+
+Storage paths are gated by their own Rules; clients can hit them directly.
+
+```javascript
+// Bad — any signed-in user can overwrite any other user's avatar
+match /avatars/{fileName} { allow write: if request.auth != null; }
+
+// Good — path-scoped to the owner, with a size/type guard
+match /avatars/{uid}/{fileName} {
+  allow read:  if true;                          // public avatars
+  allow write: if request.auth.uid == uid
+               && request.resource.size < 5 * 1024 * 1024
+               && request.resource.contentType.matches('image/.*');
+}
+```
+
+For server-issued time-limited access (private downloads), generate a **signed URL** from the Admin
+SDK rather than loosening the Rules.
+
+## SDK & project mechanics
+
+Use the **modular** SDK so the bundler tree-shakes unused Firebase code. The old namespaced
+`firebase.firestore()` API is gone in v9+.
+
+```ts
+// Bad — pulls the entire SDK; defeats tree-shaking (and the compat/namespaced API is legacy)
+import firebase from "firebase";
+firebase.firestore().collection("posts").get();
+
+// Good — named imports, only what you use ships (Web SDK v12)
+import { initializeApp } from "firebase/app";
+import { getFirestore, collection, getDocs } from "firebase/firestore";
+const db = getFirestore(initializeApp(config));
+const snap = await getDocs(collection(db, "posts"));
+```
+
+- `firebase.json` configures emulators, rules/index file paths, and hosting; `firestore.indexes.json`
+  declares composite indexes.
+- Run the **Local Emulator Suite** (`firebase emulators:start`) for local dev and tests.
+- **Emulator gotcha:** the Firestore emulator does NOT enforce composite indexes — it runs any valid
+  query. So "works in the emulator, fails in prod with *requires an index*" is expected. Verify index
+  coverage separately by keeping `firestore.indexes.json` in sync and deploying it.
+- The Firebase API key in client config is **not a secret** (it identifies the project, not authorizes
+  access — Rules + App Check do that). Service-account JSON keys ARE secrets; keep them server-side.
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong | Do instead |
+|---|---|---|
+| `allow read, write: if true;` catch-all | Whole DB is open to the internet | Default-deny; scope each `match` to `request.auth` + ownership |
+| Treating rules as query filters | Query is rejected, not filtered — it fails entirely | Constrain the query to match what `list` allows |
+| Unbounded array in one document | Hits the 1 MiB limit; every read pays for the whole blob | Subcollection, one doc per item |
+| Monotonic IDs / sequential indexed timestamps | Index hotspot → ~1 write/sec/doc wall | Scattered auto-IDs; sharded counters for high write rate |
+| Trusting client writes for sensitive fields | Client can set `role: "admin"` on itself | Validate `request.resource` in Rules; set claims via Admin SDK only |
+| No App Check in production | Rules run for any caller, including scripts/scrapers | Enable App Check (reCAPTCHA / Play Integrity / App Attest) |
+| Service-account key in client / repo | Full admin access leaks | Keep service-account JSON server-side; client API key is fine |
+| Namespaced/compat SDK (`firebase.firestore()`) | Legacy, not tree-shakeable, gone in modular | Modular named imports from `firebase/firestore` |
+| No emulator / rules tests | Open or broken rules ship silently | `@firebase/rules-unit-testing` via `firebase emulators:exec` |
+| Background trigger with non-idempotent side effects | At-least-once delivery double-charges/double-writes | Dedupe on `event.id` |
+
+## Verify
+
+`scripts/verify.sh` is read-only and runs from your project root. It locates `firestore.rules` and
+fails if a root `match /{document=**}` carries an `allow read, write: if true;` catch-all or the rules
+file is empty; validates `firestore.indexes.json` parses as JSON; and, when the Firebase CLI is
+present, points at the `firebase emulators:exec` rules-test path. It exits 0 and skips cleanly when no
+Firebase artifacts are in the working directory — not every repo has them.

package/skills/firebase/evals/README.md

@@ -0,0 +1,12 @@
+# Eval harness — `firebase`
+
+`cases.yaml` is a human/LLM-graded trigger-and-capability set; there is no automated runner in this
+folder. To run it, feed each prompt to the routing model with only the `firebase` skill discoverable
+and check that `should_trigger` prompts fire it (run 3–5 trials each, since the decision is
+stochastic) while `should_not_trigger` prompts stay quiet and would plausibly route to the named
+sibling. For each `capability` scenario, run the prompt with and without the skill loaded and grade
+the answer against its `must_include` rubric — one point per bullet that is specifically and
+correctly covered, not merely name-dropped. The skill passes when triggering is right on the large
+majority of cases and the capability answer covers the rubric (and clearly beats the no-skill
+baseline). Grade by hand or via the repo's shared eval harness; record trial counts and per-bullet
+verdicts so a reviewer can audit.

package/skills/firebase/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: firebase
+
+should_trigger:
+  - prompt: "Design the Firestore collections for a chat app with users, rooms, and messages. How should I structure it?"
+    why: "Core Firestore data modeling — collections vs subcollections, where messages live, denormalizing author info onto messages."
+  - prompt: "Can you review my firestore.rules? I'm worried the database is basically open to the internet."
+    why: "Rules audit and the headline 'open to the internet' risk — the catch-all open-rule failure mode the skill is built to catch."
+  - prompt: "My Firestore query works fine in the emulator but fails in production with a 'the query requires an index' error. What's going on?"
+    why: "Non-obvious: the emulator does NOT enforce composite indexes, so it silently runs queries that need an index declared in firestore.indexes.json."
+  - prompt: "Write a callable Cloud Function that sets a custom admin claim on a user after checking the caller is already an admin."
+    why: "Cloud Functions (2nd gen onCall) plus Auth custom claims set via the Admin SDK — squarely in scope and combines two product areas."
+  - prompt: "Necesito unes regles de seguretat perquè cada usuari només pugui llegir i editar els seus propis documents a Firestore."
+    why: "Catalan-language ownership Security Rules request — request.auth.uid == resource.data.ownerId; tests non-English trigger phrasing."
+  - prompt: "Our 'likes' counter document keeps choking under load and rejecting writes. How do I get past the 1-write-per-second limit?"
+    why: "Non-obvious scaling: the ~1 sustained write/sec/document soft limit and the sharded-counter remedy."
+  - prompt: "Should this be a subcollection under the room, or a separate top-level collection? I need to query messages across all rooms sometimes."
+    why: "Subcollection-vs-root decision driven by a collection-group access pattern — a named decision-table case."
+
+should_not_trigger:
+  - prompt: "Design a normalized Postgres schema with foreign keys for orders and line items, and pick the right indexes."
+    route_to: postgresdb
+    why: "Relational SQL schema design with FKs and SQL indexing — engine-level Postgres, not a NoSQL document store."
+  - prompt: "Set up Supabase row-level security policies and wire up the postgres-js client for my app."
+    route_to: supabase
+    why: "Postgres-backed BaaS with SQL RLS and PostgREST — the closest sibling but a different data model and rules language (the NOT-boundary)."
+  - prompt: "Model a single-table DynamoDB design with a GSI to support my access patterns and capacity planning."
+    route_to: dynamodb
+    why: "AWS NoSQL with its own single-table/GSI and capacity model — different product entirely."
+  - prompt: "Configure GCP IAM roles and a billing budget alert for our Google Cloud project."
+    route_to: gcp-essentials
+    why: "Generic GCP IAM/billing, not a Firebase product surface — Firebase sits on top of GCP but this is the layer below."
+  - prompt: "Build the React component tree and state management for the analytics dashboard."
+    route_to: react
+    why: "UI component architecture that merely happens to call Firebase — a rendering/state concern, not data modeling or rules."
+
+capability:
+  - scenario: "Here is a firestore.rules file with `match /{document=**} { allow read, write: if true; }` at the root, plus a `posts` collection where each post has an `ownerId` and users should only be able to read and edit their own posts. Fix the rules and explain how to test them locally."
+    must_include:
+      - "Removes the open `allow read, write: if true;` catch-all and relies on default-deny"
+      - "Ownership check: `request.auth.uid == resource.data.ownerId` for get/update/delete"
+      - "Uses `request.resource.data.ownerId == request.auth.uid` (or hasOnly/validation) on create"
+      - "Distinguishes the granular methods get / list / create / update rather than blanket read/write"
+      - "States that rules are NOT filters — the list query must be constrained (where ownerId == uid) or it is rejected entirely"
+      - "Provides a @firebase/rules-unit-testing snippet run via `firebase emulators:exec`"
+      - "Mentions App Check as the production trust boundary before rules evaluate"

package/skills/firebase/references/cloud-functions.md

@@ -0,0 +1,102 @@
+# Cloud Functions — 2nd gen catalogue
+
+2nd gen is the default and the only generation that runs Node.js 22. Use `firebase-functions` v7
+(current major; the modular v2 trigger API is unchanged from v6) and `firebase-admin`. Functions require the Blaze (pay-as-you-go) plan, and any
+outbound network call from a function also requires Blaze.
+
+## Trigger catalogue
+
+```ts
+import { onDocumentWritten, onDocumentCreated } from "firebase-functions/v2/firestore";
+import { onCall, onRequest, HttpsError } from "firebase-functions/v2/https";
+import { onSchedule } from "firebase-functions/v2/scheduler";
+import { beforeUserCreated } from "firebase-functions/v2/identity"; // Auth blocking
+
+export const onPostCreated = onDocumentCreated("posts/{postId}", async (event) => {
+  const data = event.data?.data();
+  // event.id is stable per delivery attempt — use it for idempotency
+});
+
+export const tidy = onSchedule("every 24 hours", async () => { /* cron */ });
+```
+
+## Callable vs HTTPS auth
+
+- **`onCall`** — the SDK passes and verifies the caller's auth automatically. `request.auth` is the
+  decoded, verified identity (or undefined). Custom claims are in `request.auth.token`.
+
+  ```ts
+  export const promote = onCall(async (request) => {
+    if (!request.auth) throw new HttpsError("unauthenticated", "sign in");
+    if (request.auth.token.admin !== true) throw new HttpsError("permission-denied", "admins only");
+    // do privileged work
+  });
+  ```
+
+- **`onRequest`** — raw HTTP. There is NO automatic auth. You must read the `Authorization: Bearer`
+  header and call `getAuth().verifyIdToken(token)` yourself. Use this for webhooks and public
+  endpoints, not for trusted-client RPC.
+
+## Secrets
+
+Never put secrets in code or in `functions.config()` literals. Define them and grant access:
+
+```ts
+import { defineSecret } from "firebase-functions/params";
+const STRIPE_KEY = defineSecret("STRIPE_KEY");
+
+export const charge = onCall({ secrets: [STRIPE_KEY] }, async (req) => {
+  const key = STRIPE_KEY.value(); // resolved at runtime from Secret Manager
+});
+```
+
+Set the value with `firebase functions:secrets:set STRIPE_KEY`.
+
+## Idempotency
+
+Background event triggers (`onDocumentWritten`, `onDocumentCreated`, etc.) deliver **at least once** —
+the same event can fire more than once. Any side effect (charge, email, increment) must be guarded.
+
+```ts
+export const fulfil = onDocumentCreated("orders/{orderId}", async (event) => {
+  const marker = db.doc(`processed/${event.id}`);
+  await db.runTransaction(async (tx) => {
+    if ((await tx.get(marker)).exists) return; // already handled this delivery
+    // ... do the side effect ...
+    tx.set(marker, { at: FieldValue.serverTimestamp() });
+  });
+});
+```
+
+## Region, concurrency, cost
+
+- Pin region near your users/data: `onCall({ region: "europe-west1" }, ...)`. Cross-region hops add
+  latency and egress cost.
+- 2nd gen runs multiple requests per instance (`concurrency`) — tune it to cut cold starts and cost,
+  but only if your handler is concurrency-safe (no shared mutable global state per request).
+- Cold starts: keep dependencies lean, do heavy init lazily, and set `minInstances` for latency-
+  critical callables (it costs idle time — only where it matters).
+
+## Auth blocking functions
+
+`beforeUserCreated` / `beforeUserSignedIn` run inside the auth flow and can reject or mutate. Use them
+to enforce email-domain allow-lists or to set initial custom claims at sign-up.
+
+```ts
+import { beforeUserCreated, HttpsError } from "firebase-functions/v2/identity";
+export const gate = beforeUserCreated((event) => {
+  if (!event.data?.email?.endsWith("@acme.com")) {
+    throw new HttpsError("permission-denied", "company accounts only");
+  }
+});
+```
+
+## firebase.json wiring
+
+```json
+{
+  "functions": { "source": "functions", "runtime": "nodejs22" },
+  "firestore": { "rules": "firestore.rules", "indexes": "firestore.indexes.json" },
+  "emulators": { "functions": { "port": 5001 }, "firestore": { "port": 8080 } }
+}
+```