Document ZeroGPU deploy and gated-model troubleshooting

README.md

@@ -48,19 +48,28 @@ If the Space already exists on `cpu-basic`, switch hardware:
 hf spaces settings build-small-hackathon/tiny-aya-compare --hardware zero-a10g
 ```
 
-### 2. Add the gated-model token
+### 2. Accept gated model access
 
-Both Tiny Aya checkpoints are gated. Add a Space secret so the runtime can download them:
+Both checkpoints are **gated** (`auto`). The account whose token you store as `HF_TOKEN` must accept access first:
+
+1. https://huggingface.co/CohereLabs/tiny-aya-global — click **Agree and access**
+2. https://huggingface.co/CohereLabs/tiny-aya-earth — click **Agree and access**
+
+Without this, startup fails with `403 Client Error` / `Cannot access gated repo`.
+
+### 3. Add the gated-model token
+
+Add a Space secret so the runtime can download the weights:
 
 ```bash
-hf spaces secrets add build-small-hackathon/tiny-aya-compare \
-  --key HF_TOKEN \
-  --value "$(hf auth token)"
+hf spaces secrets add build-small-hackathon/tiny-aya-compare -s HF_TOKEN
 ```
 
-Use a token with access to `CohereLabs/tiny-aya-global` and `CohereLabs/tiny-aya-earth`.
+This uses your logged-in `hf` token. Re-run after accepting model access if the Space already failed once.
+
+Use a token with `read` scope and access to both CohereLabs repos.
 
-### 3. Push the app
+### 4. Push the app
 
 From this repo:
 
@@ -81,7 +90,7 @@ hf upload build-small-hackathon/tiny-aya-compare . \
   --include "requirements.txt"
 ```
 
-### 4. Verify the deployment
+### 5. Verify the deployment
 
 ```bash
 # Runtime stage and hardware
@@ -97,7 +106,23 @@ gradio predict build-small-hackathon/tiny-aya-compare /compare \
 
 Expect `requested_hardware: zero-a10g` and both models loading at startup (~6 GB each in bf16).
 
-### 5. Update after changes
+### Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `Cannot access gated repo` / `403` on startup | Accept access on both model pages (step 2), then **Factory reboot** the Space |
+| `RUNTIME_ERROR` after changing secrets | Factory reboot: Space Settings → Factory rebuild |
+| `ZeroGPU quota exceeded` (visitors) | Visitors need GPU quota; creators don't pay per visit |
+| Hardware shows `cpu-basic` | `hf spaces settings build-small-hackathon/tiny-aya-compare --hardware zero-a10g` |
+
+Restart after fixing access:
+
+```bash
+# Re-upload or reboot from the Space Settings UI → "Factory rebuild"
+hf spaces info build-small-hackathon/tiny-aya-compare --expand runtime
+```
+
+### 6. Update after changes
 
 | Change | Action |
 |--------|--------|