Sync from GitHub via hub-sync

VERSION

@@ -1 +1 @@
-1513969c6acce4c4f7ceba008e8b704165e46658
+591b607e9256f858b32b23f79a2badc081ba4a0f

docs/github-hf-custom-domain-guide.md

@@ -216,3 +216,36 @@ Run through this checklist after initial setup or after any DNS/domain change:
 | TLS certificate "Pending" for >30 min | CNAME not propagated yet or wrong target | Verify CNAME value matches exactly what HF shows |
 | Custom domain works but assets 404 | `root_path` set to a subpath that doesn't exist | Set `GRADIO_ROOT_PATH=""` or the correct subpath |
 | Space rebuilds but shows old code | `fetch-depth: 0` missing in workflow | Add `fetch-depth: 0` to `actions/checkout@v4` (see §4) |
+| API Error / `ValueError: API key is missing` | Secrets added to GitHub but missing in HF Space | Add API keys directly in HF Space → Settings → Variables and secrets |
+---
+
+## 10. Using this Template for AI Projects
+
+This repository is designed as a ready-to-use template for future projects, coming with a pre-built **Multi-Provider AI Chat Application** in `main.py`.
+
+### Built-in Features
+- **Multi-Provider Backend**: Supports Hugging Face (z.ai), Google Gemini, GitHub Models, OpenRouter, and Fireworks.
+- **Dynamic UI Selection**: Gradio UI dropdowns to select providers and dynamically updated models natively without code edits.
+- **Cost-Optimization Presets**: Select quick presets like **Ultra Cheap**, **Budget Dev**, **Balanced**, and **Quality Check** to auto-configure cost-effective development environments.
+- **Automatic Fallback**: Specify `auto` as the backend to automatically cycle through fallback providers if one fails (configured via `AI_FALLBACK_ORDER`).
+
+### Environment Variables
+⚠️ **Important Pitfall:** GitHub Action secrets do **not** automatically sync to Hugging Face Space secrets. While `HF_TOKEN` must be a GitHub Secret for CI/CD, runtime API keys must be added directly to Hugging Face.
+
+**1. GitHub Action Secrets (For Sync Only)**
+- `HF_TOKEN`: Hugging Face write token (Required for `hub-sync` to work)
+
+**2. Hugging Face Space Secrets (For Runtime)**
+Configure these in your HF Space via **Settings → Variables and secrets**:
+- `HF_TOKEN`: Hugging Face token (if you want the space itself to make authenticated HF API calls)
+- `GOOGLE_API_KEY`: API key for Gemini models
+- `GITHUB_TOKEN`: API key for GitHub Models
+- `OPENROUTER_API_KEY`: API key for OpenRouter
+- `FIREWORKS_API_KEY`: API key for Fireworks
+
+*(Note: For local development, you can place these in a `.env` file or export them in your terminal).*
+
+You can further customize defaults and available choices by setting:
+- `AI_BACKEND`: Default provider (e.g., `hf`, `google`, `github`, `auto`)
+- `<PROVIDER>_MODEL`: Default model for the provider (e.g., `GOOGLE_MODEL=gemini-2.0-flash-lite`)
+- `<PROVIDER>_MODELS`: Comma-separated list for model dropdown choices (e.g., `GOOGLE_MODELS=gemini-2.0-flash-lite,gemini-1.5-flash`)