@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/finetuning/references/methods.md

@@ -0,0 +1,189 @@
+# methods — full SFT → preference scripts, dataset schemas, adapter merge
+
+Depth overflow for `SKILL.md`. All snippets target the `trl` **v1.x** API (verify the current
+major and any `trl.experimental.*` import paths at author time — this stack changes monthly).
+
+## Dataset schemas the trainers expect
+
+TRL auto-applies the model's **chat template** when a dataset is *conversational* (`messages` or
+role dicts). This is the single most important correctness point: train with the same template you
+serve with, or inference is garbage.
+
+```python
+# SFT — conversational language modeling (chat template applied automatically)
+{"messages": [{"role": "user", "content": "What color is the sky?"},
+              {"role": "assistant", "content": "It is blue."}]}
+
+# SFT — prompt/completion (loss on completion only by default)
+{"prompt": "The sky is", "completion": " blue."}
+
+# DPO / ORPO — paired preference (explicit prompt recommended)
+{"prompt":  [{"role": "user", "content": "What color is the sky?"}],
+ "chosen":  [{"role": "assistant", "content": "It is blue."}],
+ "rejected":[{"role": "assistant", "content": "It is green."}]}
+
+# KTO — UNPAIRED binary preference (a completion + a boolean label)
+{"prompt": [{"role":"user","content":"What color is the sky?"}],
+ "completion": [{"role":"assistant","content":"It is blue."}], "label": True}
+
+# GRPO — prompts only; the reward function scores generated completions
+{"prompt": [{"role": "user", "content": "Solve: 2+2. Put the answer in \\boxed{}."}],
+ "solution": "4"}   # extra columns arrive in the reward fn via **kwargs
+```
+
+Building and validating these corpora (dedup, contamination, format checks) is `training-data`.
+
+## Full QLoRA SFT run
+
+```python
+import torch
+from datasets import load_dataset
+from transformers import BitsAndBytesConfig
+from peft import LoraConfig
+from trl import SFTTrainer, SFTConfig
+
+dataset = load_dataset("trl-lib/Capybara", split="train")   # conversational messages
+
+bnb = BitsAndBytesConfig(
+    load_in_4bit=True, bnb_4bit_quant_type="nf4",
+    bnb_4bit_use_double_quant=True, bnb_4bit_compute_dtype=torch.bfloat16,
+)
+peft_config = LoraConfig(
+    r=16, lora_alpha=32, lora_dropout=0.05, bias="none",
+    task_type="CAUSAL_LM", target_modules="all-linear",
+)
+args = SFTConfig(
+    output_dir="qlora-sft",
+    per_device_train_batch_size=2, gradient_accumulation_steps=8,  # eff. batch 16
+    learning_rate=2e-4, num_train_epochs=2, warmup_ratio=0.05,
+    max_length=2048, packing=True,          # packing uses max_length as block size
+    bf16=True,                              # SFTConfig defaults: bf16=True, grad-ckpt=True
+    logging_steps=10, eval_strategy="steps", eval_steps=100, save_steps=100,
+    assistant_only_loss=True,               # loss on assistant turns only (conversational)
+)
+trainer = SFTTrainer(
+    model="Qwen/Qwen2.5-7B-Instruct",
+    args=args, train_dataset=dataset, eval_dataset=eval_dataset,
+    peft_config=peft_config, quantization_config=bnb,
+)
+trainer.train()
+trainer.save_model("qlora-sft")   # writes the adapter (adapter_config.json + weights)
+```
+
+Notes:
+- `SFTConfig` inherits `TrainingArguments`; its non-default defaults include `bf16=True`,
+  `gradient_checkpointing=True`, `learning_rate=2e-5`, `logging_steps=10`, `max_length=1024`.
+- `loss_type` defaults to `"chunked_nll"` (same math as `"nll"`, lower peak activation memory;
+  auto-falls back to `"nll"` when `use_liger_kernel=True`). Verify on your `trl` version.
+- **Base (non-instruct) models have no chat template.** Set one via `SFTConfig(chat_template_path=...)`
+  and align the EOS token (e.g. `eos_token="<|im_end|>"` for some Qwen bases) or the model never
+  learns to stop.
+
+## SFT → DPO
+
+```python
+from datasets import load_dataset
+from peft import LoraConfig
+from trl import DPOTrainer, DPOConfig
+
+pref = load_dataset("trl-lib/ultrafeedback_binarized", split="train")  # prompt/chosen/rejected
+peft_config = LoraConfig(r=16, lora_alpha=32, task_type="CAUSAL_LM", target_modules="all-linear")
+
+trainer = DPOTrainer(
+    model="qlora-sft",                    # the SFT checkpoint from above
+    args=DPOConfig(
+        output_dir="dpo", beta=0.1,       # beta ↑ = stay closer to the reference model
+        learning_rate=5e-7,               # preference LR is tiny vs SFT
+        per_device_train_batch_size=2, gradient_accumulation_steps=8,
+        max_length=1024, max_prompt_length=512,
+        precompute_ref_log_probs=True,    # cache ref logprobs → less VRAM; ref model auto-built
+        num_train_epochs=1,
+    ),
+    train_dataset=pref,
+    peft_config=peft_config,
+)
+trainer.train()
+```
+
+DPO tips: `loss_type` can be a list to blend variants (e.g. `["sigmoid","sft"]`); lower `beta` lets
+the policy drift further from the reference (more change, more risk). With LoRA you skip a separate
+frozen reference copy — the base with adapters disabled *is* the reference.
+
+## GRPO (reward-driven RL, DeepSeek-R1 style)
+
+Use when correctness is **checkable** (math, code, exact format). GRPO samples a *group* of
+`num_generations` completions per prompt and uses the group-mean reward as the baseline.
+
+```python
+from datasets import load_dataset
+from trl import GRPOTrainer, GRPOConfig
+
+dataset = load_dataset("trl-lib/DeepMath-103K", split="train")  # prompt + solution
+
+def correctness_reward(completions, solution, **kwargs):
+    # completions: list[list[{"role","content"}]]; extra dataset cols arrive as kwargs.
+    out = []
+    for comp, sol in zip(completions, solution):
+        text = comp[0]["content"]
+        got = text.split("\\boxed{")[-1].split("}")[0] if "\\boxed{" in text else ""
+        out.append(1.0 if got.strip() == str(sol).strip() else 0.0)
+    return out                              # list[float] (None allowed to skip a sample)
+
+trainer = GRPOTrainer(
+    model="qlora-sft",
+    reward_funcs=[correctness_reward],      # 1..N callables (or a reward-model id string)
+    args=GRPOConfig(
+        output_dir="grpo", num_generations=8, max_completion_length=1024,
+        beta=0.04, learning_rate=1e-6,
+        reward_weights=[1.0],               # weights when combining multiple reward fns
+        use_vllm=True, vllm_gpu_memory_utilization=0.7,   # vLLM makes rollouts affordable
+    ),
+    train_dataset=dataset,
+)
+trainer.train()
+```
+
+Reward-function contract: a Python callable (sync or async) receiving `completions` plus any extra
+dataset columns as kwargs, returning a `list[float]` (or `None` per sample to skip). `trl.rewards`
+ships built-ins (e.g. accuracy). Composed rewards are combined by `reward_weights`.
+
+## ORPO and KTO
+
+- **ORPO** — a **single stage** that fuses SFT + preference alignment (reference-free), so you can
+  align a *base* model without a separate SFT run. Import path migrated to experimental at author
+  time: `from trl.experimental.orpo import ORPOTrainer, ORPOConfig` (verify).
+- **KTO** — takes **unpaired** binary good/bad labels (thumbs up/down), not matched pairs; it will
+  also accept paired data and convert it internally. Use `KTOTrainer` / `KTOConfig` (stable API).
+
+```python
+from trl.experimental.orpo import ORPOTrainer, ORPOConfig   # verify import path
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from datasets import load_dataset
+
+model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-0.5B-Instruct")
+tok = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-0.5B-Instruct")
+if tok.pad_token is None: tok.pad_token = tok.eos_token
+ds = load_dataset("trl-lib/ultrafeedback_binarized", split="train")
+
+trainer = ORPOTrainer(model, args=ORPOConfig(output_dir="orpo"),
+                      processing_class=tok, train_dataset=ds)
+trainer.train()
+```
+
+## Merging the adapter for serving
+
+`save_model` writes the small LoRA adapter, not a full model. To serve, either load base + adapter
+at runtime (many servers hot-load adapters — see `../../vllm/SKILL.md`) or merge into standalone
+weights:
+
+```python
+from peft import AutoPeftModelForCausalLM
+merged = AutoPeftModelForCausalLM.from_pretrained("qlora-sft").merge_and_unload()
+merged.save_pretrained("merged-model")     # standalone fp16/bf16 weights
+```
+
+Caveat: merging LoRA into a **4-bit** base can shift numerics — merge into the fp16/bf16 base for a
+clean standalone model, or keep the adapter separate and serve it on top of the full-precision base.
+Pushing the adapter/merged model to the Hub and hosting inference is `huggingface`; high-throughput
+serving (adapter hot-swap, batching) is `../../vllm/SKILL.md`; a fast single-GPU train + GGUF export
+path is `../../unsloth/SKILL.md`.

package/skills/shared/firebase/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: firebase
+description: "Use when building on Firebase — Firestore data modeling, Security Rules, Auth and custom claims, Cloud Functions, Storage, modular Web/Admin SDK imports — including symptoms like a database open to the internet, a query rejected by rules, or a doc stuck at ~1 write/sec. 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: ai-hub
+---
+
+# Firebase — Firestore, Rules, Auth, Functions, Storage
+
+The Firebase product surface that sits on top of GCP, 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.
+
+Two facts drive everything below:
+
+- **It is a NoSQL document store, shaped for the read path.** No joins, no server-side `OR` across
+  different fields without a composite index, no `SELECT *` across collections. Denormalize and
+  fan-out so a screen is one cheap query — reads are what you pay for and what users wait on.
+- **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.
+
+Not this skill:
+
+| Instead of Firebase | Go to |
+|---|---|
+| Relational schema, SQL, EXPLAIN, indexing a SQL engine | `../postgresdb/SKILL.md` |
+| Managed Postgres BaaS (SQL + Postgres RLS + PostgREST) — the most-confused sibling: same "backend-as-a-service" shape, completely different data model and rules language | `supabase` |
+| 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/shared/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/shared/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/shared/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 } }
+}
+```