Add Postman collection guide and fix URL normalization

POSTMAN_COLLECTION.md

@@ -0,0 +1,171 @@
+# Postman Collection - Hugging Face Deployment
+**Base URL**: `https://ubuntu593-alt-scraper-api.hf.space`
+
+---
+
+## 1️⃣ Health Check
+**Simple uptime check**
+
+- **Method**: `GET`
+- **URL**: `https://ubuntu593-alt-scraper-api.hf.space/health`
+- **Expected Response**:
+```json
+{
+  "status": "alive"
+}
+```
+
+---
+
+## 2️⃣ System Status
+**Check server region, latency, and domain connectivity**
+
+- **Method**: `GET`
+- **URL**: `https://ubuntu593-alt-scraper-api.hf.space/api/status?domain=https://wpengine.com/`
+- **Parameters**:
+  - `domain` (optional): Target domain to test connectivity
+- **Expected Response**:
+```json
+{
+  "region": "Frankfurt, DE",
+  "latency": 45,
+  "status": "operational",
+  "engine": "AutoAlt Neural v2"
+}
+```
+
+---
+
+## 3️⃣ Start a New Scan
+**Initiate async crawl job**
+
+- **Method**: `POST`
+- **URL**: `https://ubuntu593-alt-scraper-api.hf.space/api/scanstart`
+- **Headers**: 
+  - `Content-Type: application/json`
+- **Body** (raw JSON):
+```json
+{
+  "domain": "https://wpengine.com/",
+  "limit": 25
+}
+```
+- **Expected Response**:
+```json
+{
+  "job_id": "abc123-def456-..."
+}
+```
+**⚠️ Save this `job_id` for the next steps!**
+
+---
+
+## 4️⃣ Check Scan Progress
+**Poll for real-time updates**
+
+### Option A: Path Parameter
+- **Method**: `GET`
+- **URL**: `https://ubuntu593-alt-scraper-api.hf.space/api/progress/{job_id}`
+  - Replace `{job_id}` with the actual ID from step 3
+
+### Option B: Query Parameter (Easier for browser testing)
+- **Method**: `GET`
+- **URL**: `https://ubuntu593-alt-scraper-api.hf.space/api/progress?job_id=YOUR_JOB_ID_HERE`
+
+**Expected Response**:
+```json
+{
+  "status": "running",
+  "percent": 60,
+  "pages_scanned": 15,
+  "images_found": 87,
+  "message": "Scanning: https://wpengine.com/about",
+  "elapsed_seconds": 12,
+  "eta_seconds": 8,
+  "error": null
+}
+```
+
+**Status Values**: `pending`, `running`, `done`, `error`
+
+---
+
+## 5️⃣ Get Final Results
+**Retrieve complete JSON report (once status is `done`)**
+
+### Option A: Path Parameter
+- **Method**: `GET`
+- **URL**: `https://ubuntu593-alt-scraper-api.hf.space/api/result/{job_id}`
+
+### Option B: Query Parameter
+- **Method**: `GET`
+- **URL**: `https://ubuntu593-alt-scraper-api.hf.space/api/result?job_id=YOUR_JOB_ID_HERE`
+
+**Expected Response**:
+```json
+{
+  "summary": {
+    "total_pages_scanned": 25,
+    "total_images_found": 145,
+    "total_images_missing_alt": 23,
+    "total_images_poor_quality": 5,
+    "total_pages_discovered": 50,
+    "blocked_reason": null,
+    "crawl_blocked": false
+  },
+  "details": [ ... ]
+}
+```
+
+---
+
+## 🧪 Complete Test Flow (Copy to Postman)
+
+### Test 1: Health Check
+```bash
+curl https://ubuntu593-alt-scraper-api.hf.space/health
+```
+
+### Test 2: System Status
+```bash
+curl "https://ubuntu593-alt-scraper-api.hf.space/api/status?domain=https://wpengine.com/"
+```
+
+### Test 3: Start Scan
+```bash
+curl -X POST "https://ubuntu593-alt-scraper-api.hf.space/api/scanstart" \
+  -H "Content-Type: application/json" \
+  -d '{"domain": "https://wpengine.com/", "limit": 25}'
+```
+
+### Test 4: Progress (use job_id from Test 3)
+```bash
+curl "https://ubuntu593-alt-scraper-api.hf.space/api/progress?job_id=PASTE_JOB_ID"
+```
+
+### Test 5: Result (when status = done)
+```bash
+curl "https://ubuntu593-alt-scraper-api.hf.space/api/result?job_id=PASTE_JOB_ID"
+```
+
+---
+
+## ⚠️ Common Mistakes to Avoid
+
+1. **Don't use `limit` parameter on `/api/status`** ❌
+   - ❌ Wrong: `/api/status?domain=...&limit=25`
+   - ✅ Right: `/api/status?domain=...`
+
+2. **Use POST (not GET) for `/api/scanstart`** ❌
+   - ❌ Wrong: GET request
+   - ✅ Right: POST with JSON body
+
+3. **Don't forget to URL-encode the domain parameter** ⚠️
+   - If testing in browser, use `https%3A%2F%2Fwpengine.com%2F`
+   - Postman/curl handle this automatically
+
+---
+
+## 🎯 Quick Postman Import
+
+Create a new Postman collection and add these 5 requests with the URLs above. Test them in order!

api.py

@@ -190,6 +190,7 @@ def health_check():
 
 @app.get("/api/status")
 def get_system_status(domain: Optional[str] = None):
+    # If a domain is provided, we check its connectivity specifically
     stats = SystemMonitor.get_system_stats(target_url=domain)
     return stats