opencode-skills-collection 3.1.12 → 3.1.14

package/bundled-skills/huggingface-spaces/references/buckets.md

@@ -0,0 +1,89 @@
+# Persistent storage with Buckets
+
+Spaces are stateless. All data is wiped on restart / rebuild. For state that must survive (user uploads, generations, dynamic feeds, logs, growing databases): mount an HF **Bucket** — S3-like object storage living at `hf://buckets/<ns>/<bucket>`.
+
+Buckets are paid (per-TB storage). Check `whoami.canPay` and confirm with the user before creating one. Pricing + free tier: https://huggingface.co/storage.
+
+Full docs: https://huggingface.co/docs/hub/storage-buckets.
+
+## Create + attach
+
+```bash
+hf buckets create <ns>/<bucket-name>                                # --private optional
+hf spaces volumes set <ns>/<space> -v hf://buckets/<ns>/<bucket-name>:/data
+```
+
+After this, writes to `/data/` in the Space are durable. Reads come from the bucket via the Xet storage backend.
+
+To make the bucket files publicly addressable: leave the bucket public. Public bucket files are served at `https://huggingface.co/buckets/<ns>/<bucket>/resolve/<path>` (HTTP 302 redirect to a signed CDN URL). The Space writes once and the public URL works forever — no streaming proxy needed.
+
+## Write-durable, read-fast pattern
+
+For a feed-style Space (e.g. a community jam where users save generations and browse a public timeline), don't re-scan disk on every request. Module-level disk scan → in-memory list → every write appends to both:
+
+```python
+import os, json, uuid
+from datetime import datetime, timezone
+
+BUCKET_ID = "<ns>/<bucket-name>"
+BUCKET_URL = f"https://huggingface.co/buckets/{BUCKET_ID}/resolve"
+_feed = []
+
+def _load_feed():
+    root = "/data/songs"
+    if not os.path.isdir(root):
+        return
+    for sid in os.listdir(root):
+        meta = f"{root}/{sid}/meta.json"
+        if os.path.isfile(meta):
+            _feed.append(json.load(open(meta)))
+    _feed.sort(key=lambda s: s["created_at"], reverse=True)
+
+_load_feed()                                       # one scan at startup
+
+@app.api(name="save", time_limit=60)
+def save(audio_bytes: bytes, title: str):
+    sid = uuid.uuid4().hex[:12]
+    d = f"/data/songs/{sid}"; os.makedirs(d, exist_ok=True)
+    open(f"{d}/audio.wav", "wb").write(audio_bytes)
+    meta = {"id": sid, "title": title,
+            "url": f"{BUCKET_URL}/songs/{sid}/audio.wav",
+            "created_at": datetime.now(timezone.utc).isoformat()}
+    json.dump(meta, open(f"{d}/meta.json", "w"))
+    _feed.insert(0, meta)                          # cache stays current — no re-scan
+    return meta
+
+@app.api(name="feed", concurrency_limit=10)
+def feed(): return _feed[:50]                      # zero disk I/O
+```
+
+Reference Space using this pattern: https://huggingface.co/spaces/victor/ace-step-jam
+
+## Anti-pattern: bucket as model-weights cache
+
+**Do NOT** `snapshot_download(..., local_dir="/data/weights")` and load checkpoints from there. Bucket I/O is S3-paced; reading a 22 GB `safetensors` from `/data` during `from_pretrained` stalls past any `@spaces.GPU` duration cap.
+
+For model weights, let HF Hub re-download to local container disk on each cold start. With `HF_HUB_ENABLE_HF_TRANSFER=1` (set in the runtime by default) this is fast — typically much faster than streaming the same bytes through bucket I/O at request time.
+
+Bucket I/O is fine for occasional metadata reads (the feed pattern above) or saving user information. It is *not* fine as the path your model loader streams gigabytes through every cold start.
+
+## Cache redirects
+
+`/home/user/.cache` is read-only on ZeroGPU. Redirect transient caches at the top of `app.py`, before any library import that uses them:
+
+```python
+import os
+os.environ.setdefault("HF_HOME", "/data/.cache/huggingface")   # or /tmp on non-bucket Spaces
+os.environ.setdefault("HF_MODULES_CACHE", "/tmp/hf_modules")
+os.environ.setdefault("MPLCONFIGDIR", "/tmp/matplotlib")
+```
+
+Missing redirections fail silently or at first matplotlib / transformers / diffusers import.
+
+## Write access from the Space
+
+The Space's `HF_TOKEN` secret needs write permission on the bucket. Set via Settings → Secrets in the Space UI, or `hf spaces secrets set <id> HF_TOKEN=<token>`.
+
+## Security note
+
+Public bucket files are publicly accessible forever at their resolve URL. **Don't write PII** to a public bucket. If you need durable but private storage (e.g. per-user history requiring an HF login), keep the bucket private and gate reads through your Space's own auth.

package/bundled-skills/huggingface-spaces/references/debugging.md

@@ -0,0 +1,234 @@
+# Debugging and iteration
+
+How to iterate cheaply, read logs, and smoke-test. Dev mode + SSH exists as a last resort (covered at the bottom).
+
+## The rung ladder
+
+Pick the cheapest update mechanism that fits the change. Going one rung too high wastes 30 s – 15 min per cycle.
+
+| Rung | When | Command | Cost |
+|---|---|---|---|
+| 1. Hot-reload | Pure Python edit on a Gradio Space (SDK 6.1+), **no new deps** | `hf spaces hot-reload <id> -f app.py` | seconds, no rebuild |
+| 2. `hf upload` | Code-only change hot-reload can't handle (`gr.Server`, Streamlit, Docker entrypoint, non-Python file) | `hf upload <id> . --include '<file>'` | 30–90 s app restart |
+| 3. Full rebuild | `requirements.txt`, `Dockerfile`, README frontmatter, or hardware change | `hf upload <id> . && hf spaces logs <id> --build --follow` | 1–15 min |
+| 4. Factory reboot | Container in inconsistent state (broken pip env, etc.) | `hf spaces restart <id> --factory-reboot` | full rebuild + cold start |
+
+### How hot-reload works
+
+`hf spaces hot-reload <id> -f app.py` patches the running Python process in place via `jurigged` (vendored inside the `spaces` package), then commits the change to the repo with a hot-reload marker that tells the platform to skip its usual restart. Seconds, no rebuild.
+
+Applies cleanly to function-body changes and new top-level symbols. Does **not** rerun module-level imports or one-time init — the model was loaded when `app.py` first ran and jurigged won't re-execute that load. New pip deps, README frontmatter, `Dockerfile`, and hardware changes need a full rebuild (rung 3).
+
+Independent of dev mode. Marked experimental in the CLI. Requires Gradio SDK 6.1+.
+
+### Footguns
+
+- **Hot-reload poisons factory reboot.** A commit that's only a hot-reload leaves runtime metadata that's valid only while the hot process is alive. `--factory-reboot` on top of one can fail with `fatal: could not read Username for 'https://huggingface.co'`. Recovery: push any normal `hf upload` commit (even a one-line no-op) first, then restart.
+- **`runtime.sha` lags repo SHA on restart.** `hf upload` succeeds → repo updates → `hf spaces info` keeps reporting the *previous* commit's SHA under `runtime` for several minutes while the new container loads. Poll `runtime.sha`, not just `stage`, and don't issue another restart until it flips.
+- **Concurrent uploads or restart-while-uploading collide.** Wait for one to finish.
+- **"Let me try locally first"** for anything that depends on the Space's Python / torch / CUDA env. The Space environment is the only one that matters. `python3 -m py_compile app.py` is the maximum local check worth doing before pushing.
+
+## Reading logs
+
+```bash
+hf spaces info <id> --expand runtime           # stage at a glance
+hf spaces logs <id> --build --follow           # build log, live
+hf spaces logs <id> --follow                   # run log, live
+hf spaces logs <id> --build --tail 500         # bigger window — default is small
+```
+
+Find the **first** error in the build log, not the last. Cascading errors after the first are noise.
+
+State machine (terminal states in bold):
+
+```
+BUILDING → APP_STARTING → RUNNING
+                      ↘ RUNTIME_ERROR
+        ↘ BUILD_ERROR
+        ↘ CONFIG_ERROR
+```
+
+For stage-specific lookups, see [`known-errors.md`](known-errors.md).
+
+## Smoke-test patterns
+
+A Space isn't done until a `gradio_client` call against the live URL exercises the endpoint end-to-end. Four steps in order — keep `hf spaces logs <id> --follow` running in another terminal throughout, so any silent fallback (model snapping to a different size, missing optional dep, dtype downgrade) surfaces.
+
+### A. Alive?
+
+```bash
+hf spaces info <id> --expand runtime --format json \
+  | python3 -c "import json,sys; r=json.load(sys.stdin)['runtime']; \
+                print(r['stage'], r.get('hardware','?'))"
+# expect: RUNNING zero-a10g
+```
+
+If `requested_hardware` is `cpu-basic` when you wanted GPU, your `--flavor` was rejected silently. Fix with `hf spaces settings <id> --hardware zero-a10g`.
+
+### B. Logs clean post-boot?
+
+```bash
+hf spaces logs <id> --tail 200
+```
+
+Confirm the model finished loading, no import warnings, no "falling back to CPU" / dtype-downgrade messages, no failing health checks the platform forgave. Do this before calling the API — many silent failures (a config typo loading the wrong model, a missing optional dep, a one-time init that errored but didn't crash boot) are only visible here.
+
+### C. API actually functions?
+
+Default — sync `gr.Interface` / `gr.Blocks` / `gr.ChatInterface` / `gr.Server` `@app.api`:
+
+```python
+from gradio_client import Client, handle_file
+import os
+
+c = Client("<ns>/<name>", token=os.environ["HF_TOKEN"],
+           httpx_kwargs={"timeout": 600})   # ≥ @spaces.GPU duration + 60s
+
+print(c.view_api())                          # discover endpoints — don't guess api_name
+
+result = c.predict(
+    handle_file("test.png"),                 # file inputs need handle_file()
+    "short prompt",
+    api_name="/generate",                    # matches @app.api(name=...) or the function name
+)
+```
+
+**Streaming endpoints** (function uses `yield` or `TextIteratorStreamer`) — `.predict()` returns only the final value. Iterate chunks via `.submit()`:
+
+```python
+job = c.submit("short prompt", api_name="/chat")
+for chunk in job: print(chunk, end="")
+# or job.result() for the final value
+```
+
+**`gr.Server` custom `@app.get/post(...)` routes** don't appear in `view_api()`. Hit them with plain HTTP:
+
+```python
+import httpx
+r = httpx.post(f"https://<subdomain>.hf.space/your_route",
+               json={...}, timeout=600,
+               headers={"Authorization": f"Bearer {os.environ['HF_TOKEN']}"})
+```
+
+**OAuth-gated Spaces** (`hf_oauth: true` + `gr.LoginButton`) — anonymous `Client` can't authenticate. Test interactively after sign-in, or capture a session token and pass via `httpx_kwargs={"headers": {...}}`.
+
+**MCP server mode** (`launch(mcp_server=True)`) — different protocol. Use an MCP client.
+
+### D. Output bytes AND logs look right?
+
+HTTP 200 ≠ correct output. Sniff both the returned file and the run log emitted during the call.
+
+```python
+head = open(path, "rb").read(16)
+# b'glTF...'          → glb
+# b'\x89PNG'          → png
+# b'\xff\xd8'         → jpeg
+# b'RIFF...WEBP'      → webp
+# b'RIFF...WAVE'      → wav
+# head[4:8]==b'ftyp'  → mp4
+# b'ply\n'            → ply
+```
+
+For text: non-empty, not all `<think>...</think>` (thinking-model leak), length reasonable. For images: returned dimensions match what was requested (some models snap to nearest preset).
+
+Look at the tailed run log alongside — silent fallbacks (model snapping resolution, missing optional dep falling back to a slower path, dtype downgrade) only show up there.
+
+### What NOT to do
+
+- **Don't launch Playwright / headless browser** to verify backend logic. The Gradio UI calls the same API `gradio_client` does — one `predict` tests both.
+- **Don't build mock-mode + local-server harnesses** before pushing. Local-green ≠ Space-green.
+- **Don't smoke-test with full-budget inputs.** Smallest input that exercises the GPU code path — short prompt, small image, low step count. You're verifying wiring, not quality.
+
+## Iterating on the Space, not locally
+
+The Space env is the only one that matters: Python, torch, CUDA, file paths, env vars, gradio version, the `spaces` hijack all differ from your laptop.
+
+Workflow:
+
+1. Decide SDK + hardware. Write the smallest `app.py` / `Dockerfile` + `requirements.txt` + README frontmatter — just enough that the entry point loads.
+2. Push immediately. Don't build a Playwright / mock harness first.
+3. Once `RUNNING`: verify with `gradio_client` against the real Space. That's your test loop.
+4. Iterate via the cheapest rung.
+
+`python3 -m py_compile app.py` is the maximum local check worth doing.
+
+## Last resort: dev mode + SSH
+
+Use only when:
+
+- A failure is non-deterministic (device-side asserts, OOM under specific shapes, race conditions).
+- You need `CUDA_LAUNCH_BLOCKING=1` or `gdb` to localize a CUDA error.
+- You'd burn 4+ build cycles trying variations from outside.
+
+Reading logs + grepping [`known-errors.md`](known-errors.md) + a tight `gradio_client` smoke loop solves the vast majority of issues. Dev mode is a heavy hammer.
+
+### Prerequisites
+
+1. **PRO / Team / Enterprise plan** — dev mode is a paid feature.
+2. **An SSH key registered on the user's HF profile.** Without this, SSH refuses the connection. If the user doesn't have one yet, they need to:
+   - Generate a keypair locally: `ssh-keygen -t ed25519 -f ~/.ssh/hf_dev -N ''` (no passphrase keeps automation simple; user can pick differently if they prefer).
+   - Add the **public** key (`~/.ssh/hf_dev.pub`) at https://huggingface.co/settings/keys.
+   - Keep the **private** key (`~/.ssh/hf_dev`) on the machine they'll SSH from.
+3. **The Space must be in `RUNNING` or `RUNTIME_ERROR`** before dev mode lets you in — not `BUILD_ERROR`. If it's in build error, push a stub `app.py` that boots cleanly first (e.g. `import gradio as gr; gr.Interface(lambda: 'ok', None, 'text').launch()`), then enable dev mode.
+
+### Enable
+
+No `huggingface_hub` Python wrapper yet — use the REST endpoint:
+
+```bash
+curl -s -X POST \
+  -H "Authorization: Bearer $HF_TOKEN" \
+  -H "Content-Type: application/json" \
+  "https://huggingface.co/api/spaces/<ns>/<space>/dev-mode" \
+  -d '{"enabled": true}'
+```
+
+### SSH in
+
+```bash
+ssh -i ~/.ssh/hf_dev -o BatchMode=yes -o StrictHostKeyChecking=accept-new \
+    <ns>-<space>@ssh.hf.space
+```
+
+Username is `<namespace>-<space>` **lowercase**, with `-` replacing `/`. Dots in the Space name become hyphens too.
+
+### Inside the VM
+
+It's a normal container at `/home/user/app/`. You can edit files, `pip install`, run repros, call `@spaces.GPU`-decorated functions interactively (they get a real GPU window).
+
+**`nvidia-smi` in the bare terminal will fail** with `NVML: Unknown Error`. Expected — ZeroGPU only exposes the real GPU inside `@spaces.GPU` calls. Don't assume the GPU is broken.
+
+**Edits in `/home/user/app/` don't survive** a restart, sleep, or dev-mode-disable. Only commits persist.
+
+### Smoke-test the fix inside the container
+
+Before exiting dev mode, verify the fix actually works under a real GPU window:
+
+```bash
+cat > /home/user/app/_devtest.py <<'PY'
+import spaces, torch
+from app import predict   # or whatever your @spaces.GPU function is
+print(predict(<realistic-args>))
+PY
+python3 _devtest.py
+```
+
+### Persist + exit
+
+Commit + push from inside the container (`git config user.email / user.name` first; the HF git remote works). Then disable dev mode:
+
+```bash
+curl -s -X POST -H "Authorization: Bearer $HF_TOKEN" \
+  -H "Content-Type: application/json" \
+  "https://huggingface.co/api/spaces/<ns>/<space>/dev-mode" \
+  -d '{"enabled": false}'
+```
+
+**Factory-reboot** to apply the pushed state (in dev mode the Space won't rebuild on commits):
+
+```python
+from huggingface_hub import HfApi
+HfApi(token=HF_TOKEN).restart_space("<ns>/<space>", factory_reboot=True)
+```
+
+Then re-run the outside-the-container smoke test. Dev-mode success does **not** guarantee post-rebuild success — different image, different process tree.

package/bundled-skills/huggingface-spaces/references/gradio.md

@@ -0,0 +1,171 @@
+# Gradio for Spaces
+
+Patterns and quirks specific to running Gradio inside a Space. Assumes you're already comfortable with stock Gradio components and `gr.Blocks` / `gr.Interface`.
+
+For deeper Gradio API guidance — components, layouts, event listeners, chatbots, the Gradio 5→6 migration — use the dedicated `huggingface-gradio` skill. Install it with `hf skills add huggingface-gradio` (add `--claude --global` to also install for Claude Code, user-level).
+
+For ZeroGPU-specific decorator + worker semantics, see [`zerogpu.md`](zerogpu.md).
+
+## Themes and layout
+
+- Default theme preference: `gr.themes.Soft()`. Alternatives: no theme, or `gr.themes.Citrus()`. Pick once and don't over-style.
+- For apps that don't need full-width, constrain with CSS so they're readable on 4K displays:
+  ```python
+  CSS = """
+  #col-container { max-width: 1100px; margin: 0 auto; }
+  .dark .gradio-container { color: var(--body-text-color); }
+  """
+  with gr.Blocks(theme=gr.themes.Soft(), css=CSS) as demo: ...
+  ```
+  The dark-mode override fixes a recurring Gradio bug where dark text inherits unset colors.
+- Width-cap with `!important` if Gradio 6's own breakpoints fight you — target `main`, `.gradio-container`, and the inner fillable wrapper, otherwise the width caps but goes flush-left.
+
+## Minimal layout most demos converge to
+
+```python
+with gr.Row():
+    prompt = gr.Textbox(show_label=False, placeholder="…", container=False, scale=4)
+    run = gr.Button("Run", variant="primary", scale=1)
+output = gr.Image(...)
+with gr.Accordion("Advanced settings", open=False):
+    ...
+```
+
+`container=False` on the inline Textbox removes the default outer border for a tighter look.
+
+## `gr.Markdown` for the intro
+
+Be succinct. Title, one-line description, a links section. Don't over-explain how it works — that's what the model card is for.
+
+## `gr.Examples`
+
+The pattern that doesn't trip people up:
+
+```python
+gr.Examples(
+    examples=[
+        ["a cat sitting on a windowsill", 42],
+        ["mountains at sunset, photorealistic", 7],
+    ],
+    inputs=[prompt, seed],
+    outputs=output,
+    fn=generate,
+    cache_examples=True,
+    cache_mode="lazy",
+)
+```
+
+Why these flags:
+
+- `cache_examples=True` makes example clicks instant (no re-inference per visitor).
+- **`cache_mode="lazy"`** — caches on first user click for each example. **Required on ZeroGPU** (Gradio's default on ZeroGPU is already lazy via `GRADIO_CACHE_MODE=lazy`). Eager would pre-run every example at app startup, but ZeroGPU has no GPU attached at startup — it'd fail and burn the creator's daily quota.
+- `cache_examples=True` silently disables `run_on_click` / `run_examples_on_click`. If your app relies on click-only behavior, set `cache_examples=False`.
+
+The cache key is the **example row's file path**, not a content hash. Regenerating an asset in place serves the stale cached output forever. If you replace example files, bump a `cache_version` marker or wipe `.gradio/cached_examples/<id>/`.
+
+Hot-reload (rung 1) does **not** rebuild the cache. A `cache_version` bump needs a real commit + restart.
+
+## Streaming and generators
+
+`gr.Interface(fn=...)` and `.click(fn=...)` both accept generator functions. Each `yield` pushes a new value:
+
+```python
+@spaces.GPU(duration=120)
+def generate(prompt):
+    yield gr.update(value=None, label="Starting…")
+    for k in range(num_steps):
+        yield gr.update(value=preview(k), label=f"Step {k+1}/{num_steps}")
+    yield gr.update(value=final, label="Done")
+```
+
+Use `gr.update(label=...)` for status narration — feels like a status line without a separate component.
+
+**Caveat**: `gr.Progress(track_tqdm=True)` and `yield` partial outputs fight each other — pick one streaming mechanism.
+
+## Useful UX bits
+
+- `progress=gr.Progress(track_tqdm=True)` in the GPU function gives a free tqdm-driven progress bar.
+- Pair a "Randomize seed" checkbox with the seed input, and write the actually-used seed back so users can re-run deterministically:
+  ```python
+  randomize = gr.Checkbox(label="Randomize seed", value=True)
+  seed = gr.Number(label="Seed", value=0, precision=0)
+
+  @spaces.GPU
+  def gen(..., seed, randomize_seed):
+      if randomize_seed:
+          seed = random.randint(0, 2**31 - 1)
+      seed = int(seed)
+      yield ..., gr.update(value=seed)   # write back into the Seed input
+      ...
+
+  run.click(gen, inputs=[..., seed, randomize], outputs=[..., seed])
+  ```
+
+## Custom HTML components
+
+Stock Gradio components cover 95% of cases. When they don't, `gr.HTML(...)` lets you build contextual custom UI without leaving the Gradio Space (no need to switch to Docker).
+
+Guide: https://www.gradio.app/guides/custom-HTML-components
+Example with a 3D camera-angle picker that makes sense in context: https://huggingface.co/spaces/multimodalart/qwen-image-multiple-angles-3d-camera
+
+Don't reach for this if a stock component covers the need.
+
+## Custom frontends — `gr.Server`
+
+For fully custom frontends with their own HTML/JS, while keeping Gradio's queue + GPU scheduling:
+
+```python
+from gradio import Server
+from fastapi.responses import HTMLResponse
+
+app = Server(title="my-app")
+
+@spaces.GPU(duration=60)
+def _run_gpu(prompt): return inference(prompt)
+
+@app.api(name="generate", concurrency_limit=1, time_limit=180)
+def generate(prompt: str) -> str:
+    return _run_gpu(prompt)        # @app.api wraps, doesn't stack with @spaces.GPU
+
+@app.get("/", response_class=HTMLResponse)
+async def homepage():
+    return open("index.html").read()
+
+demo = app                          # HF runtime expects `demo`
+if __name__ == "__main__":
+    demo.launch(ssr_mode=False)
+```
+
+Required for the custom `/` route to actually serve:
+
+```bash
+hf spaces variables add <ns>/<name> --env GRADIO_SSR_MODE=false
+```
+
+`launch(ssr_mode=False)` is ignored on HF — must be the env var.
+
+Valid `@app.api` kwargs: `name`, `description`, `concurrency_limit`, `concurrency_id`, `queue`, `batch`, `max_batch_size`, `api_visibility`, `time_limit`, `stream_every`.
+
+**Don't stack `@spaces.GPU` and `@app.api`** on the same function — silently breaks request flow. Keep them on separate functions.
+
+**Two-ceiling coordination**: both `@spaces.GPU(duration=N)` and `@app.api(time_limit=M)` apply; the lower wins. Set `time_limit` to your max duration across modes — a too-low `time_limit` kills the request even if GPU duration would have allowed it.
+
+Hot-reload (rung 1 in [`debugging.md`](debugging.md)) does **not** work with `gr.Server` — always `hf upload` or commit.
+
+Reference Space: https://huggingface.co/spaces/huggingface-projects/rf-detr-realtime-webcam
+
+## Slow-startup Gradio (big-model Spaces)
+
+For Spaces that take 10–20 min to load weights:
+
+- Set `startup_duration_timeout: 1h` in README frontmatter (default 30 min).
+- Disable SSR: `hf spaces variables add <id> --env GRADIO_SSR_MODE=false`. Otherwise the SSR health check times out before the app finishes loading.
+
+## Don't
+
+- `gr.Button(text="X")` — `text=` was removed; use `gr.Button("X")`.
+- `gr.Button(type="button")` — drop the kwarg.
+- `.click(..., _js=share_js)` — renamed to `js=`.
+- `.style(height=...)` — removed in gradio 4+.
+- `gr.ImageMask(brush_color=...)` — kwarg removed.
+- `demo.launch(mcp_server=True)` on gradio 4.x — only valid on 5+.

package/bundled-skills/huggingface-spaces/references/grants.md

@@ -0,0 +1,56 @@
+# Community GPU grants
+
+When a non-PRO user has a good use case for ZeroGPU (open research demo, hobbyist project, educational tool, institutional showcase) and doesn't want to subscribe, they can request a free community grant from Hugging Face.
+
+## The flow
+
+1. **Build the Space.** Create it as `--flavor cpu-basic` (the user is not PRO, so creating with `--flavor zero-a10g` will fail at `create_repo`). Code the app for ZeroGPU anyway — `import spaces`, `@spaces.GPU`, module-scope `.to("cuda")`. The Space will technically run on CPU until the grant is approved, but it'll be ready to switch over instantly.
+
+   In this mode you **can't iterate-with-real-inference** before the grant — the CPU Space won't actually run heavy compute. Get the app to BUILD cleanly and `RUNNING` (even if the runtime would OOM on real input), then submit.
+
+2. **Submit a Community Tab discussion** on the Space. Title:
+
+   ```
+   Apply for a GPU community grant: <Personal|Company|Academic> project
+   ```
+
+   Pick the closest fit. Body:
+
+   ```
+   Description of the app: one paragraph on what it does + who it's for.
+   Justification: one paragraph on why this should run on ZeroGPU
+   (open-source, research, educational, etc.).
+   ```
+
+   If the user didn't give you a justification, a reasonable default is "Non-PRO wants to build a public ZeroGPU app — happy to provide more context if helpful."
+
+3. **Wait.** Open and publicly-facing applications by researchers, tinkerers, and institutions are typically approved. Approval can take days.
+
+4. **Once approved**, the Space is moved to ZeroGPU automatically — no code change needed. The user comes back and you can iterate / refine with real GPU access.
+
+## When to suggest this
+
+- User is not on PRO but their use case is a clear fit for ZeroGPU (a public ML demo, not a private tool).
+- The model fits in `large` (≤ 48 GB VRAM at the chosen precision).
+
+## When NOT to suggest this
+
+- Private / commercial / closed-source projects — push the user toward PRO instead.
+- The model genuinely needs dedicated paid hardware (huge LLM, vLLM/JAX/ONNX as main model with heavy init) — `canPay=True` users can use paid flavors directly.
+- The user is already PRO — they have ZeroGPU access; no grant needed.
+
+## Posting the request programmatically
+
+```python
+from huggingface_hub import HfApi
+
+api = HfApi(token="hf_...")
+api.create_discussion(
+    repo_id="<ns>/<space>",
+    repo_type="space",
+    title="Apply for a GPU community grant: Personal project",
+    description="<description and justification>",
+)
+```
+
+The Community Tab must be enabled on the Space (default — keep it on).

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

@@ -0,0 +1,85 @@
+# Inference Providers — when not to host the model
+
+Some Spaces don't need a GPU at all. If the model is available through HF Inference Providers (Cerebras, Fireworks, Together, Replicate, OpenRouter, etc.), the Space can be a thin Gradio shell that proxies to a hosted endpoint:
+
+- Zero VRAM, no `@spaces.GPU`, no model download.
+- Works for models too large to fit on ZeroGPU (120B+).
+- Hardware can be `cpu-basic` — no GPU at all.
+
+## When to use this pattern
+
+- **Stateless chat or text completion** with a big model.
+- **The user wants a public demo of a frontier-scale model** that obviously doesn't fit on a single 48 GB MIG.
+- **The user wants to ship something fast** without worrying about quantization / sharding.
+
+## When NOT to use this pattern
+
+- The model isn't available on any Inference Provider. Check with:
+  ```bash
+  curl "https://huggingface.co/api/models/<ns>/<repo>?expand[]=inferenceProviderMapping"
+  ```
+- The Space needs **custom decoding** (special sampling, tool use, retrieval, anything stateful or interactive across calls).
+- The Space needs **multimodal** beyond what the provider exposes.
+- The user explicitly wants to own the inference stack (model loading, decoding, performance tuning).
+
+For those, host the model yourself on ZeroGPU — see [`zerogpu.md`](zerogpu.md).
+
+## Two billing modes
+
+Choose based on who pays for inference.
+
+### Mode A — Space creator pays (simple)
+
+Set `HF_TOKEN` as a Space secret. The Space uses `InferenceClient` directly. Every visitor's call is billed to the Space creator's account.
+
+```python
+import os, gradio as gr
+from huggingface_hub import InferenceClient
+
+client = InferenceClient(api_key=os.environ["HF_TOKEN"], provider="fireworks-ai")
+
+def chat(msg, history):
+    return client.chat_completion(
+        model="<org>/<model>",
+        messages=[*history, {"role": "user", "content": msg}],
+        max_tokens=512,
+    ).choices[0].message.content
+
+gr.ChatInterface(chat).launch()
+```
+
+Use when you want users to "just click and try it" — no sign-in friction. Cost is on you.
+
+### Mode B — Visitor pays (recommended for public demos)
+
+`gr.LoginButton` + `gr.load("models/...")` with `accept_token=button`. Each visitor signs in with their HF account; inference is billed to **their** account.
+
+```python
+import gradio as gr
+
+with gr.Blocks(fill_height=True) as demo:
+    with gr.Sidebar():
+        button = gr.LoginButton("Sign in")
+    gr.load("models/<org>/<model>", accept_token=button, provider="fireworks-ai")
+demo.launch()
+```
+
+README frontmatter needs:
+
+```yaml
+hf_oauth: true
+hf_oauth_scopes:
+  - inference-api
+```
+
+This is the **recommended pattern for public demos** — sustainable cost-wise, and visitors get to use their own provider quotas (which most have paid for or get free).
+
+## Hardware
+
+`cpu-basic`. No GPU. Don't put `--flavor zero-a10g` — you'd waste a paid grant.
+
+## Anti-pattern: `@spaces.GPU` wrapping a provider call
+
+If you do use Inference Providers, do **not** wrap the call in `@spaces.GPU`. The decorator reserves a GPU slot on your Space for the full `duration=`, but the function does no GPU work — just an HTTP call out. You burn your own ZeroGPU quota for nothing.
+
+A provider-proxy Space wants `cpu-basic` hardware and zero `@spaces.GPU`.