rsc-universal 0.1.1

package/skills/huggingface/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: huggingface
+description: "Use when running open models or working on the Hugging Face platform: calling a model via the Inference Providers router or InferenceClient, downloading/uploading/versioning repos on the Hub with the hf CLI, deploying a dedicated Inference Endpoint with scale-to-zero, hosting a Gradio Space with ZeroGPU, picking an open model by task/license/size, or loading a model locally with transformers. Triggers: 'call an open model through Hugging Face', 'InferenceClient embeddings', 'hf download/upload', 'write a model card', 'router.huggingface.co', 'my hf-inference serverless call 404s on a 70B model', 'scale-to-zero endpoint', 'ZeroGPU Space', 'desplegar un modelo de Hugging Face con escalado a cero', 'necesito controlar el coste de inferencia en HF'. NOT serving a model locally on your own machine (that is ollama), NOT renting and operating your own GPU box (that is runpod), NOT generating creative images via a hosted API (that is replicate-images)."
+tags: [huggingface, inference-providers, transformers, model-hub, inference-endpoints, spaces, ai-infra]
+recommends: [ollama, runpod, modal, replicate, together-fireworks, fal, rag, embeddings-search, prompt-engineering, llm-pipeline, ai-media]
+origin: risco
+---
+
+# Hugging Face: Hub, routed/hosted inference, and transformers
+
+Hugging Face is three surfaces, and you should always know which one you are on:
+
+1. **The Hub** — versioned git repos for models, datasets, and Spaces. You search it, you
+   `hf download` / `hf upload`, you read and write model cards.
+2. **Inference** — three ways to actually run a model: the **Inference Providers** router
+   (serverless, you own nothing), a **dedicated Inference Endpoint** (you own a deployment
+   that autoscales), or **local `transformers`** (you own the machine).
+3. **The catalog** — 1M+ open models you choose from by task, license, and size.
+
+The whole skill is choosing the right surface for the job and proving it works: a 200 router
+response, a live endpoint URL, a pushed repo commit. If the model is open and the workflow
+lives on huggingface.co, you are in the right place. If you operate the GPU yourself, or the
+vendor is not HF, stop — see the boundaries at the bottom.
+
+## Decision: how should I run this model?
+
+Pick the row before you write a line of code. The cheapest mistake is standing up infra you
+did not need.
+
+| Situation | Use | Why |
+|---|---|---|
+| Try a model now, low/dev volume, own no infra | **Inference Providers router** (`InferenceClient`) | Fastest path; monthly credits cover dev. |
+| CPU task: embeddings, text-ranking, text-classification, small BERT/GPT-2 | `provider="hf-inference"` | That is exactly its remaining niche as of July 2025. |
+| Big LLM (8B, 70B, 405B) through HF | router with a **partner provider** (Together/Fireworks/Cerebras/DeepInfra…) | `hf-inference` does not serve big LLMs — it will 404 or stall. |
+| Steady prod traffic, need fixed latency/SLA | **dedicated Inference Endpoint** + scale-to-zero | Predictable, autoscaling, billed per minute. |
+| Interactive demo or shareable GPU app | **Space** (Gradio + ZeroGPU) | Free-ish, public URL, GPU only while a call runs. |
+| One-off GPU job (eval, batch convert) | `hf jobs run` | No standing infra; PRO feature. |
+| Offline, data-private, or already on a GPU box | local `transformers` `pipeline()` | No network, no per-call cost. |
+
+## Auth & install
+
+```bash
+pip install "huggingface_hub[inference]"   # 1.17.0; needs Python >=3.10
+pip install transformers                    # 5.x line, PyTorch-first, optional/local
+hf auth login                               # stores a token; or export HF_TOKEN=...
+```
+
+- **The CLI is `hf` now**, shaped `hf <resource> <action>` (`hf auth login`, `hf download`,
+  `hf upload`, `hf repo create`, `hf jobs run`). `huggingface-cli` still runs but prints a
+  deprecation warning — do not write it into new scripts.
+- **Never hardcode a `hf_...` token in code** — tokens leak the moment the file hits git. Read
+  from the environment instead:
+
+```python
+import os
+from huggingface_hub import InferenceClient
+client = InferenceClient(api_key=os.environ["HF_TOKEN"])   # never api_key="hf_xxx"
+```
+
+- Token scopes: **read** to pull public/gated repos and run inference, **write** to push,
+  **fine-grained** to scope to specific repos/orgs — why: a leaked read token cannot overwrite
+  your models.
+
+## Inference Providers — the default path
+
+One router reaches 200+ models across partner providers plus `hf-inference`; HF passes provider
+cost through with **no markup**. Two equivalent entry points:
+
+```python
+# Native client — task methods, NOT the removed .post()
+from huggingface_hub import InferenceClient
+client = InferenceClient(api_key=os.environ["HF_TOKEN"])
+out = client.chat.completions.create(
+    model="meta-llama/Llama-3.1-8B-Instruct",
+    messages=[{"role": "user", "content": "One sentence on diffusion models."}],
+    provider="together",          # name a partner; or omit for auto-routing
+)
+print(out.choices[0].message.content)
+```
+
+```python
+# OpenAI-compatible — same router, drop-in for existing OpenAI code
+from openai import OpenAI
+client = OpenAI(
+    base_url="https://router.huggingface.co/v1",   # this exact host, nothing else
+    api_key=os.environ["HF_TOKEN"],
+)
+```
+
+- **`InferenceClient.post()` was removed** (dropped in hub v0.31.0). Use the task methods:
+  `chat.completions.create()`, `text_generation()`, `feature_extraction()` (embeddings),
+  `text_to_image()`, `automatic_speech_recognition()`.
+- **Credits are real and small**: Free $0.10/mo, PRO $2.00/mo, Team/Enterprise $2.00 per seat
+  (shared). Past that you are pay-as-you-go and must buy credits. Budget accordingly — why: a
+  chat loop on a 70B model burns the free tier in minutes.
+- A **Custom Provider Key** bypasses HF billing entirely (the provider bills you; HF credits do
+  not apply). For org billing, pass `bill_to="org-name"` (header `X-HF-Bill-To`).
+- Full recipes (embeddings, image, ASR, streaming, rate-limit handling, the provider list) live
+  in `references/inference-providers.md`.
+
+## Hub ops
+
+```bash
+hf download meta-llama/Llama-3.1-8B-Instruct --include "*.safetensors"
+hf repo create my-org/my-model --repo-type model
+hf upload my-org/my-model ./out --commit-message "v1 weights"
+```
+
+```python
+from huggingface_hub import snapshot_download
+path = snapshot_download("BAAI/bge-small-en-v1.5")   # full repo, cached, resumable
+```
+
+- **Gated models** (Llama, Gemma, many others) need you to accept terms on the model page first,
+  then a token with read access — otherwise the download 403s.
+- A model card is a `README.md` with YAML front-matter (`license`, `pipeline_tag`, `tags`,
+  `base_model`). Ship one on every upload — why: an uncarded repo is unsearchable and unusable by
+  anyone but you. Command map and `hf jobs run` details in `references/hub-and-cli.md`.
+
+## Choosing a model
+
+Filter the Hub by **task + license + size + recent downloads**, then read the card before you
+commit. Match the model to your constraint; do not grab whatever is trending.
+
+- Check the **license**: Apache-2.0/MIT are permissive; Llama/Gemma carry commercial terms and
+  are gated; "non-commercial"/"research-only" cards mean you cannot ship them.
+- Check **size vs target**: a 70B will not fit a single A10G; an embedding model belongs on CPU.
+- Check **context length** and **intended use** in the card — the headline number is not always
+  the usable one.
+
+## Dedicated Inference Endpoints — when to graduate
+
+Move off the router when you need fixed latency/SLA, or the router's PAYG cost stops being
+predictable. An Endpoint is your own autoscaling deployment.
+
+- Pricing: CPU from ~$0.032/core/hr, GPU from ~$0.50/hr (A10G ~$1.00/hr, H100 ~$6.40–8.00/hr),
+  **billed per minute** even though shown hourly.
+- Enable **scale-to-zero** for bursty traffic — it parks at $0 when idle and cold-starts on the
+  next request. A bursty 100–1000 req/day workload typically lands at **$20–60/mo**.
+- Deploy from the UI or with `huggingface_hub` (`create_inference_endpoint(...)`). Config and a
+  cost worksheet are in `references/endpoints-and-spaces.md`.
+
+## Spaces + ZeroGPU
+
+A Space hosts a demo app with a public URL. **ZeroGPU** grabs an H200 MIG slice (~70GB) only
+while a decorated function runs, then releases it.
+
+```python
+import spaces
+@spaces.GPU                       # GPU acquired for this call only
+def generate(prompt: str) -> str:
+    ...
+```
+
+- **ZeroGPU is Gradio-SDK only** — Streamlit/Docker/static Spaces cannot use it. PRO ($9/mo)
+  gives 8x daily quota, queue priority, and up to 10 owned ZeroGPU Spaces. Details in
+  `references/endpoints-and-spaces.md`.
+
+## Local transformers
+
+```python
+from transformers import pipeline
+pipe = pipeline("text-generation", model="meta-llama/Llama-3.1-8B-Instruct",
+                device_map="auto", torch_dtype="auto")
+print(pipe("Hello", max_new_tokens=64)[0]["generated_text"])
+```
+
+- `pipeline("task", model=...)` for quick use; `AutoModelForCausalLM.from_pretrained(...)` when
+  you need control over generation/quantization. Set `device_map`/`torch_dtype` explicitly.
+- Use local only when you are **offline, data-private, or already on a GPU**. Otherwise the
+  router is far less ops than babysitting CUDA and weights.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| `InferenceClient.post(...)` | Removed in hub v0.31.0; raises | Task methods: `chat.completions.create()`, `feature_extraction()` |
+| `provider="hf-inference"` for a 70B/405B LLM | CPU niche; 404s or stalls | Route to a partner provider (Together/Fireworks/Cerebras) |
+| `api_key="hf_abc123..."` in code | Token leaks in git history | Read `os.environ["HF_TOKEN"]` |
+| Spin up a dedicated Endpoint just to try a model | Burns money idle | Use the router first; graduate only on real traffic |
+| Assuming router calls are free/unlimited | Free tier is $0.10/mo | Budget credits; expect PAYG |
+| ZeroGPU under Streamlit/Docker SDK | Unsupported, silently no GPU | Use the Gradio SDK |
+| `huggingface-cli ...` in new scripts | Deprecated, warns | Use `hf ...` |
+| OpenAI base URL other than `https://router.huggingface.co/v1` | Won't reach the HF router | Use that exact host |
+
+## verify.sh
+
+`scripts/verify.sh [TARGET]` is a static, read-only linter (no network, no token). It flags the
+hard violations above — `.post(`, hardcoded `hf_` tokens, big-LLM-to-`hf-inference`, wrong router
+host — and warns on legacy `huggingface-cli`. It exits 0 on a clean or empty target.

package/skills/huggingface/evals/README.md

@@ -0,0 +1,11 @@
+# Evals for the `huggingface` skill
+
+These are routing and capability checks read from `cases.yaml` by the skill eval harness — no
+network, no HF token, no model calls. `should_trigger` prompts must select this skill (they cover
+the router path, embeddings, dedicated Endpoints, Hub uploads, the non-obvious hf-inference-is-
+CPU-only case, and a Spanish phrasing). `should_not_trigger` prompts must route to the named real
+sibling instead (ollama, runpod, replicate-images, rag, together-fireworks). The single
+`capability` case is a rubric: a good answer to the Llama-3.1-8B scenario must mention every item
+in `must_include` (router/InferenceClient, a partner provider, env-based HF_TOKEN, credit/PAYG
+cost, and scale-to-zero Endpoints as the graduation path). Run them with whatever harness loads
+`evals/cases.yaml`; there is nothing to install or connect.

package/skills/huggingface/evals/cases.yaml

@@ -0,0 +1,41 @@
+skill: huggingface
+
+should_trigger:
+  - prompt: "I want to call an open chat model through Hugging Face without hosting it myself."
+    why: "Core Inference Providers router path — InferenceClient/router base URL, no infra owned."
+  - prompt: "Get sentence embeddings from a Hugging Face model using InferenceClient in Python."
+    why: "feature_extraction via the router; embeddings are the canonical hf-inference CPU task."
+  - prompt: "Deploy my fine-tuned model to a Hugging Face endpoint with scale to zero so it costs nothing when idle."
+    why: "Dedicated Inference Endpoint + scale-to-zero — the graduation-off-the-router path."
+  - prompt: "Push my model and a dataset to the Hub and write a model card for them."
+    why: "Hub ops: hf upload / repo create + README front-matter model card."
+  - prompt: "My HF serverless calls return 404 for a 70B model but work fine on a BERT classifier — why?"
+    why: "Non-obvious: hf-inference is CPU/small-model only; big LLMs must route to a partner provider. User never names the fix."
+  - prompt: "Necesito desplegar un modelo de Hugging Face con escalado a cero y controlar el coste de inferencia."
+    why: "Spanish; dedicated Endpoint + scale-to-zero + cost math, squarely this skill."
+
+should_not_trigger:
+  - prompt: "Run this open model locally with `ollama serve` on my laptop."
+    route_to: ollama
+    why: "Self-hosting an open model on your own machine — ollama's territory, not HF-routed/hosted."
+  - prompt: "Rent an A100 pod, build a container, and run my own inference server with autoscaling I operate."
+    route_to: runpod
+    why: "You own and operate the GPU infra; HF is for the Hub + HF-routed/hosted inference."
+  - prompt: "Generate polished product photos from a text prompt via a hosted image API for our store."
+    route_to: replicate-images
+    why: "Creative media deliverable via a hosted API, not the open-model + Hub workflow."
+  - prompt: "Build a retrieval pipeline over our docs: chunking, an index, and reranking."
+    route_to: rag
+    why: "Building a retrieval system, not calling/hosting a model on HF."
+  - prompt: "Set up a multi-provider LLM router across Together and Fireworks as our chosen vendors."
+    route_to: together-fireworks
+    why: "Non-HF vendor abstraction where HF is not the platform in play."
+
+capability:
+  - scenario: "Run Llama-3.1-8B-Instruct through Hugging Face without hosting it, then plan the move to a dedicated endpoint as traffic grows."
+    must_include:
+      - "InferenceClient or the OpenAI-compatible router base URL https://router.huggingface.co/v1"
+      - "a partner provider (e.g. together/fireworks), not hf-inference, for the 8B LLM"
+      - "HF_TOKEN read from the environment, never a hardcoded hf_ literal"
+      - "cost awareness: Free $0.10 / PRO $2 monthly credits then pay-as-you-go, no markup"
+      - "a dedicated Inference Endpoint with scale-to-zero as the graduation path when traffic is steady"

package/skills/huggingface/references/endpoints-and-spaces.md

@@ -0,0 +1,99 @@
+# Dedicated Endpoints & Spaces
+
+## Dedicated Inference Endpoints
+
+Your own autoscaling deployment of a model on managed HF infra. Graduate here from the router
+when you need fixed latency/SLA or the router's pay-as-you-go cost stops being predictable.
+
+### Pricing (billed per minute, shown hourly)
+
+| Tier | From |
+|---|---|
+| CPU | ~$0.032 / core / hr |
+| GPU (entry) | ~$0.50 / hr |
+| GPU A10G | ~$1.00 / hr |
+| GPU H100 | ~$6.40–8.00 / hr |
+
+### Scale-to-zero
+
+Enable scale-to-zero so the endpoint parks at **$0 when idle** and cold-starts on the next
+request — the right default for bursty traffic. A bursty 100–1000 req/day workload typically
+lands at **$20–60/mo**. The trade-off is cold-start latency on the first request after idle; keep
+a minimum replica > 0 only if you cannot tolerate that.
+
+### Deploy from the UI
+
+1. Model page → **Deploy → Inference Endpoints**, pick cloud/region/hardware.
+2. Set **Autoscaling**: min replicas (`0` for scale-to-zero), max replicas, scale-to-zero idle
+   timeout.
+3. Set security (Protected/Public) and create. Copy the endpoint URL.
+
+### Deploy with `huggingface_hub`
+
+```python
+from huggingface_hub import create_inference_endpoint
+
+ep = create_inference_endpoint(
+    name="llama-31-8b",
+    repository="meta-llama/Llama-3.1-8B-Instruct",
+    framework="pytorch",
+    task="text-generation",
+    accelerator="gpu",
+    instance_size="x1",
+    instance_type="nvidia-a10g",
+    vendor="aws",
+    region="us-east-1",
+    min_replica=0,          # scale-to-zero
+    max_replica=2,
+)
+ep.wait()                   # block until the endpoint is running
+print(ep.url)
+```
+
+Call it like any provider endpoint:
+
+```python
+from huggingface_hub import InferenceClient
+client = InferenceClient(base_url=ep.url, api_key=os.environ["HF_TOKEN"])
+```
+
+### Cost worksheet
+
+```text
+monthly_cost ≈ active_minutes/month × (hourly_rate / 60)
+# scale-to-zero ⇒ active_minutes ≈ requests × seconds_per_request / 60, plus cold starts
+# Example: 500 req/day × 2s × 30 days = 500 min ≈ 8.3 hr/mo on A10G ($1/hr) ≈ $8/mo + cold starts
+```
+
+## Spaces
+
+A Space hosts a demo app at a public `*.hf.space` URL. Pick the SDK by need:
+
+| SDK | Use for | ZeroGPU? |
+|---|---|---|
+| Gradio | ML demos, the default | **Yes** |
+| Streamlit | data-app UIs | No |
+| Docker | arbitrary servers/full control | No |
+| Static | HTML/JS front-ends | No |
+
+### ZeroGPU
+
+Dynamic GPU allocation: an **H200 MIG slice (3g.71gb, ~70GB)** is grabbed only while a decorated
+function runs and released when idle. **Gradio SDK only.**
+
+```python
+import spaces
+import gradio as gr
+
+@spaces.GPU                       # GPU acquired for the duration of this call
+def generate(prompt: str) -> str:
+    # load/run your model here
+    return run_model(prompt)
+
+gr.Interface(fn=generate, inputs="text", outputs="text").launch()
+```
+
+- Free accounts get a daily ZeroGPU quota; **PRO ($9/mo)** gives **8x daily quota**, queue
+  priority, and up to **10 owned ZeroGPU Spaces**.
+- Keep `@spaces.GPU` functions short — the slice is held for the whole call, so quota burns with
+  wall-clock GPU time.

package/skills/huggingface/references/hub-and-cli.md

@@ -0,0 +1,85 @@
+# Hub & the `hf` CLI
+
+The CLI was renamed `huggingface-cli` → **`hf`**, shaped `hf <resource> <action>`. The legacy
+name still works but prints a deprecation warning — use `hf` in all new scripts.
+
+## Command map
+
+```bash
+hf auth login                 # interactive token store; or export HF_TOKEN=...
+hf auth whoami                # confirm identity + token scope
+hf download <repo>            # pull a repo (model/dataset/space) to the local cache
+hf upload <repo> <path>       # push files to a repo
+hf repo create <repo>         # create a new repo (--repo-type model|dataset|space)
+hf jobs run <image> -- <cmd>  # run a containerized/uv job on HF infra (PRO)
+```
+
+## Download patterns
+
+```bash
+# Only the weights you need, not the whole repo:
+hf download meta-llama/Llama-3.1-8B-Instruct --include "*.safetensors" "config.json"
+
+# A dataset:
+hf download HuggingFaceH4/ultrachat_200k --repo-type dataset
+```
+
+```python
+from huggingface_hub import snapshot_download, hf_hub_download
+
+# Whole repo (resumable, cached):
+local = snapshot_download("BAAI/bge-small-en-v1.5")
+
+# A single file:
+cfg = hf_hub_download("BAAI/bge-small-en-v1.5", filename="config.json")
+```
+
+## Upload patterns
+
+```bash
+hf repo create my-org/my-model --repo-type model
+hf upload my-org/my-model ./checkpoints --commit-message "v1 weights"
+```
+
+```python
+from huggingface_hub import HfApi
+api = HfApi()
+api.create_repo("my-org/my-model", repo_type="model", private=True)
+api.upload_folder(repo_id="my-org/my-model", folder_path="./checkpoints",
+                  commit_message="v1 weights")
+```
+
+## Model cards
+
+A model card is the repo's `README.md` with YAML front-matter. Ship one on every upload — an
+uncarded repo is unsearchable and unusable by others.
+
+```markdown
+---
+license: apache-2.0
+pipeline_tag: text-generation
+base_model: meta-llama/Llama-3.1-8B
+tags: [llama, fine-tune, instruct]
+language: [en]
+---
+
+# my-model
+
+What it is, what it was trained on, intended use, limitations, and how to load it.
+```
+
+## Gated & licensed models
+
+- **Gated** repos (Llama, Gemma, many others): accept the terms on the model page first, then use
+  a token with **read** scope. Without acceptance the download/inference returns `403`.
+- Read the `license` field before shipping: Apache-2.0/MIT are permissive; Llama/Gemma carry
+  commercial conditions; `cc-by-nc`/"research-only" means you cannot ship it commercially.
+
+## `hf jobs run`
+
+Run a one-off containerized or `uv`-script job on HF infra (a PRO feature) — the path for an
+eval, a batch convert, or a fine-tune without standing up an Endpoint or a Space.
+
+```bash
+hf jobs run python:3.12 -- python -c "print('runs on HF infra')"
+```

package/skills/huggingface/references/inference-providers.md

@@ -0,0 +1,115 @@
+# Inference Providers — client recipes & routing
+
+The router (`https://router.huggingface.co/v1`, or `InferenceClient`) is the unified, serverless
+entry point — formerly "Inference API (serverless)". One token reaches 200+ models across partner
+providers (Cerebras, Together, Fireworks, Replicate, DeepInfra, Public AI, …) plus `hf-inference`.
+HF passes the provider's price through with **no markup**.
+
+All snippets read the token from `os.environ["HF_TOKEN"]` — never hardcode `hf_...`.
+
+## Chat / LLM
+
+```python
+import os
+from huggingface_hub import InferenceClient
+
+client = InferenceClient(api_key=os.environ["HF_TOKEN"])
+resp = client.chat.completions.create(
+    model="meta-llama/Llama-3.1-8B-Instruct",
+    messages=[{"role": "user", "content": "Explain MoE in one line."}],
+    provider="together",      # omit to let HF auto-route to an available provider
+    max_tokens=256,
+)
+print(resp.choices[0].message.content)
+```
+
+Streaming:
+
+```python
+for chunk in client.chat.completions.create(
+    model="meta-llama/Llama-3.1-8B-Instruct",
+    messages=[{"role": "user", "content": "Count to five."}],
+    stream=True,
+):
+    delta = chunk.choices[0].delta.content
+    if delta:
+        print(delta, end="", flush=True)
+```
+
+## Embeddings (feature_extraction)
+
+```python
+vecs = client.feature_extraction(
+    "Retrieval-augmented generation grounds answers in sources.",
+    model="BAAI/bge-small-en-v1.5",
+    provider="hf-inference",   # embeddings are a CPU task — hf-inference is correct here
+)
+# vecs is a numpy array of shape (dim,) or (n_tokens, dim) depending on the model
+```
+
+## Text-to-image
+
+```python
+image = client.text_to_image(
+    "a minimalist line drawing of a fox",
+    model="black-forest-labs/FLUX.1-dev",
+    provider="replicate",
+)
+image.save("fox.png")   # returns a PIL.Image
+```
+
+## Speech-to-text (ASR)
+
+```python
+text = client.automatic_speech_recognition(
+    "sample.flac",
+    model="openai/whisper-large-v3",
+)
+print(text.text)
+```
+
+## OpenAI-compatible drop-in
+
+```python
+import os
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="https://router.huggingface.co/v1",   # exact host; anything else won't route
+    api_key=os.environ["HF_TOKEN"],
+)
+resp = client.chat.completions.create(
+    model="meta-llama/Llama-3.1-8B-Instruct:together",  # optional :provider suffix
+    messages=[{"role": "user", "content": "hi"}],
+)
+```
+
+## Provider selection & the hf-inference niche
+
+- `provider="auto"` (default when omitted) routes to an available partner for the model.
+- Name a partner explicitly (`together`, `fireworks-ai`, `cerebras`, `replicate`,
+  `deepinfra`, …) when you need a specific backend's pricing or features.
+- **`hf-inference`** (the old serverless API) as of July 2025 focuses on CPU tasks: embeddings,
+  text-ranking, text-classification, and small historic LLMs (BERT, GPT-2). Do **not** route a
+  big LLM there — it 404s or stalls. Send 8B/70B/405B chat to a partner provider.
+
+## Billing & org headers
+
+- Monthly Inference-Providers credits: **Free $0.10**, **PRO $2.00**, **Team/Enterprise $2.00 per
+  seat** (shared across the org). Past credits → pay-as-you-go (you must purchase credits).
+- A **Custom Provider Key** (your own key for a partner) bypasses HF billing — the provider bills
+  you directly and HF credits do not apply.
+- Bill an organization instead of your personal account:
+
+```python
+client = InferenceClient(api_key=os.environ["HF_TOKEN"], bill_to="my-org")
+# or, with the OpenAI client, set the header:  X-HF-Bill-To: my-org
+```
+
+## Errors & rate limits
+
+- `402` / out-of-credits → buy credits or switch to a Custom Provider Key.
+- `404` on a big LLM via `hf-inference` → wrong provider; pick a partner.
+- `429` rate limit → back off and retry with jitter; the router does not retry for you.
+- Always read the token from env and catch `huggingface_hub.errors.HfHubHTTPError` to surface the
+  provider's message.

package/skills/huggingface/scripts/verify.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+#
+# verify.sh — static linter for Hugging Face integration code/config.
+#
+# Usage:
+#   ./scripts/verify.sh [TARGET_PATH]   (default: current directory)
+#
+# Read-only. No network, no HF token, nothing executed from the target. It greps emitted
+# CODE/CONFIG artifacts (.py/.sh/.toml/.yaml/.yml) for the hard mistakes this skill warns
+# about and exits non-zero only on HARD violations. Soft issues print a yellow WARN and do not
+# fail. Prose docs (.md/.txt) are NOT scanned — they legitimately quote anti-patterns as
+# examples, so scanning them would false-positive. This script and the skill's own files are
+# skipped. An empty or clean target exits 0 — never a false failure.
+#
+# Compatible with stock macOS bash 3.2: no mapfile, no associative arrays, find|while loop.
+
+set -euo pipefail
+
+TARGET="${1:-.}"
+
+if [ -t 1 ]; then
+  RED=$'\033[0;31m'; GREEN=$'\033[0;32m'; YELLOW=$'\033[0;33m'; RESET=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; RESET=''
+fi
+fail_msg() { printf '%sFAIL%s %s\n' "$RED" "$RESET" "$*"; }
+warn_msg() { printf '%sWARN%s %s\n' "$YELLOW" "$RESET" "$*"; }
+ok_msg()   { printf '%sOK%s   %s\n' "$GREEN" "$RESET" "$*"; }
+
+if [ ! -e "$TARGET" ]; then
+  warn_msg "target '$TARGET' does not exist — nothing to check"
+  exit 0
+fi
+
+HARD=0
+
+# Collect candidate files (skip VCS and dependency dirs).
+FILES=""
+while IFS= read -r f; do
+  FILES="$FILES
+$f"
+done <<EOF
+$(find "$TARGET" \
+    \( -name .git -o -name node_modules -o -name .venv -o -name venv -o -name __pycache__ \) -prune -false \
+    -o -type f \( -name '*.py' -o -name '*.sh' \
+                  -o -name '*.toml' -o -name '*.yaml' -o -name '*.yml' \) \
+    ! -name 'verify.sh' -print 2>/dev/null)
+EOF
+
+# Trim leading blank line.
+FILES="$(printf '%s\n' "$FILES" | sed '/^$/d')"
+
+if [ -z "$FILES" ]; then
+  ok_msg "no HF-related source/config files found — clean"
+  exit 0
+fi
+
+scan() { # scan <regex> <label>; returns 0 if a match was found
+  printf '%s\n' "$FILES" | while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    grep -nE "$1" "$f" 2>/dev/null | sed "s#^#$f:#"
+  done
+}
+
+# --- HARD: InferenceClient.post() was removed ---
+HITS="$(scan '\.post\s*\(' || true)"
+if printf '%s' "$HITS" | grep -q .; then
+  # only treat as HF .post if the file mentions InferenceClient
+  PHITS="$(printf '%s\n' "$FILES" | while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    if grep -q 'InferenceClient' "$f" 2>/dev/null; then grep -nE '\.post\s*\(' "$f" 2>/dev/null | sed "s#^#$f:#"; fi
+  done)"
+  if printf '%s' "$PHITS" | grep -q .; then
+    fail_msg "InferenceClient.post() is removed (hub v0.31.0) — use task methods (chat.completions.create / feature_extraction):"
+    printf '%s\n' "$PHITS"
+    HARD=1
+  fi
+fi
+
+# --- HARD: hardcoded hf_ token literal ---
+THITS="$(scan '["'\'']hf_[A-Za-z0-9]{8,}' || true)"
+if printf '%s' "$THITS" | grep -q .; then
+  fail_msg "hardcoded hf_ token literal — read os.environ[\"HF_TOKEN\"] instead:"
+  printf '%s\n' "$THITS"
+  HARD=1
+fi
+
+# --- HARD: big LLM routed to hf-inference (CPU/small-model niche) ---
+BHITS="$(scan 'provider\s*=\s*["'\'']hf-inference["'\'']' || true)"
+if printf '%s' "$BHITS" | grep -q .; then
+  BIG="$(printf '%s\n' "$BHITS" | grep -iE '(-|_)(7b|8b|13b|34b|70b|72b|405b)|llama-?3|mixtral|qwen2|deepseek' || true)"
+  if printf '%s' "$BIG" | grep -q .; then
+    fail_msg "large LLM routed to provider=\"hf-inference\" (CPU/small-model niche; will 404/stall) — use a partner provider:"
+    printf '%s\n' "$BIG"
+    HARD=1
+  fi
+fi
+
+# --- HARD: wrong OpenAI-compat router host ---
+URLHITS="$(scan 'router\.huggingface\.co' || true)"
+if printf '%s' "$URLHITS" | grep -q .; then
+  BADURL="$(printf '%s' "$URLHITS" | grep -E 'router\.huggingface\.co' | grep -vE 'router\.huggingface\.co/v1([^A-Za-z0-9]|$)' || true)"
+  if printf '%s' "$BADURL" | grep -q .; then
+    fail_msg "router host must be https://router.huggingface.co/v1 for OpenAI-compat:"
+    printf '%s\n' "$BADURL"
+    HARD=1
+  fi
+fi
+
+# --- SOFT: legacy huggingface-cli in shell/scripts ---
+CLIHITS="$(scan 'huggingface-cli ' || true)"
+if printf '%s' "$CLIHITS" | grep -q .; then
+  warn_msg "legacy 'huggingface-cli' is deprecated — prefer 'hf <resource> <action>':"
+  printf '%s\n' "$CLIHITS"
+fi
+
+if [ "$HARD" -ne 0 ]; then
+  fail_msg "hard violations found"
+  exit 1
+fi
+
+ok_msg "no hard violations"
+exit 0