chore: update .gitattributes and README.md for improved text handling and usage instructions

.gitattributes

@@ -33,3 +33,6 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+
+# Ensure text files normalized with LF endings in repo
+* text=auto eol=lf

README.md

@@ -22,4 +22,103 @@ This Space showcases the **[tasal9/ZamAI-mT5-Pashto](https://huggingface.co/tasa
 
 ### About the Model
 
-This model was fine-tuned on the `tasal9/ZamAI-Pashto-High-Qualituly-Dataset`. It is designed to understand and execute a wide variety of instructions in Pashto.
+This model was fine-tuned on the `tasal9/ZamAI-Pashto-High-Qualituly-Dataset`. It is designed to understand and execute a wide variety of instructions in Pashto.
+
+### Modes (Runtime Behavior)
+
+The UI exposes a `Mode` dropdown:
+
+- `off` – Real model generation (loads weights, may take time first run)
+- `echo` – Returns the prompt exactly (fast, for UI testing)
+- `useless` – Returns a fixed placeholder response (for latency / wiring checks)
+
+You can also preset a default via environment: `ECHO_MODE=echo` or `ECHO_MODE=useless` before launching. The UI selection overrides the env per request.
+
+### Running Locally
+
+```bash
+python app.py
+```
+
+Environment variables (optional):
+
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `MODEL_ID` | Override model repo | `tasal9/ZamAI-mT5-Pashto` |
+| `GRADIO_PORT` | Change port | `9000` |
+| `GRADIO_HOST` | Bind address | `0.0.0.0` |
+| `ECHO_MODE` | Default mode (`off\|echo\|useless`) | `echo` |
+| `HF_HOME` | Hugging Face cache root | `/data/hf-cache` |
+| `OFFLINE` | If set to `1/true`, sets `HF_HUB_OFFLINE=1` | `1` |
+| `DEFAULT_MAX_NEW_TOKENS` | Slider default tokens | `128` |
+
+Example:
+
+```bash
+HF_HOME=/data/hf-cache OFFLINE=1 ECHO_MODE=echo python app.py
+```
+
+### Caching & Offline Usage
+
+1. Pick a persistent cache directory (fast disk/SSD recommended).
+2. Set `HF_HOME` to that path on every run.
+3. Launch once in real mode (`off`) so weights download.
+4. Set `OFFLINE=1` (or directly `HF_HUB_OFFLINE=1`) for subsequent offline usage.
+
+Linux example:
+
+```bash
+export HF_HOME=/data/hf-cache
+python app.py  # first run downloads
+export OFFLINE=1
+python app.py  # offline reuse
+```
+
+Windows PowerShell example:
+
+```powershell
+$env:HF_HOME = 'D:\hf-cache'
+python app.py   # first run
+$env:OFFLINE = '1'
+python app.py   # offline
+```
+
+### Health Endpoint
+
+A lightweight HTTP health check server listens on `HEALTH_PORT` (default `8080`).
+
+
+```bash
+curl http://localhost:8080/health  # returns 'ok'
+```
+
+### Development Tips
+
+- Use `echo` mode to iterate on UI changes without loading the full model.
+- `useless` mode provides a constant response for benchmarking layout latency.
+- Logs show cache configuration: `HF_HOME`, `TRANSFORMERS_CACHE`, and offline status.
+- GPU is auto-detected (CUDA) and displayed in the header if available.
+
+### Common Issues
+
+| Symptom | Likely Cause | Fix |
+|---------|--------------|-----|
+| Slow first generation | Model weights not cached | Ensure persistent `HF_HOME` |
+| Network calls while offline | Missing `OFFLINE=1` | Export `OFFLINE=1` (sets `HF_HUB_OFFLINE`) |
+| IndentationError on Space | Space not rebuilt | Trigger rebuild / push a new commit |
+| Echo mode still loads model | Open runs before switching | Set `ECHO_MODE=echo` before launch |
+
+### Trigger Rebuild (Hugging Face Space)
+
+If a rebuild doesn’t trigger automatically, make a no-op commit:
+ 
+```bash
+date > .rebuild
+git add .rebuild
+git commit -m "chore: trigger rebuild"
+git push origin main
+```
+
+### License / Usage
+
+Refer to the model card of `tasal9/ZamAI-mT5-Pashto` for any licensing or usage constraints. This demo adds only interface logic and does not modify model licensing terms.