docs: add project instructions

CLAUDE.md

@@ -0,0 +1,96 @@
+# PPF Project Instructions
+
+## Current State
+
+PPF is a Python 2 proxy scraping and validation framework with:
+- Multi-target validation (2/3 majority voting)
+- SSL/TLS proxy testing with MITM detection
+- Web dashboard with electric cyan theme
+- Interactive world map (/map endpoint)
+- Memory profiling (/api/memory endpoint)
+- Tor connection pooling with health monitoring
+
+## Deployment to Odin
+
+When deploying PPF to odin server, follow these specifications exactly:
+
+### Production Deployment
+
+```
+Host:           odin
+Container User: podman
+Source Path:    /home/podman/ppf/src/
+Data Path:      /home/podman/ppf/data/
+Config:         /home/podman/ppf/config.ini
+HTTP Port:      8081
+Container:      ppf (localhost/ppf:latest)
+```
+
+### Deployment Steps
+
+1. **Validate syntax** - Run `python3 -m py_compile` on all .py files
+2. **Sync to staging** - rsync Python files to `odin:/tmp/ppf-update/`
+3. **Copy to container source** - `sudo -u podman cp /tmp/ppf-update/*.py /home/podman/ppf/src/`
+4. **Restart container** - `sudo -u podman podman restart ppf`
+5. **Clean staging** - Remove `/tmp/ppf-update/`
+6. **Verify** - Check container logs for successful startup
+
+### Test Pod (Development)
+
+If running a test container, use:
+- Different port: 8082
+- Different container name: ppf-test
+- Separate data directory: /home/podman/ppf-test/data/
+
+```bash
+# Test container example
+sudo -u podman podman run -d --name ppf-test \
+    -p 8082:8081 \
+    -v /home/podman/ppf/src:/app/src:ro \
+    -v /home/podman/ppf-test/data:/app/data \
+    localhost/ppf:latest
+```
+
+### Files to Deploy
+
+All Python files in project root:
+- proxywatchd.py (main daemon)
+- httpd.py (web dashboard)
+- config.py, dbs.py, fetch.py, etc.
+
+### Do NOT Deploy
+
+- config.ini (server-specific)
+- data/ directory contents
+- *.sqlite files
+
+## API Endpoints
+
+```
+/dashboard       Web UI with live statistics
+/map             Interactive world map (Leaflet.js)
+/health          Health check: {"status": "ok"}
+/api/stats       Runtime statistics (JSON)
+/api/memory      Memory profiling data (JSON)
+/api/countries   Proxy counts by country
+/api/locations   Precise proxy locations (requires DB5)
+/proxies         Working proxies (limit, proto, country params)
+```
+
+## Memory Analysis
+
+Query production memory state:
+```bash
+ssh odin "curl -s localhost:8081/api/memory" | python3 -m json.tool
+```
+
+Key metrics:
+- `start_rss` / `process.VmRSS` - memory growth
+- `objgraph_common` - top object types by count
+- `samples` - RSS history over time
+- `gc.objects` - total GC-tracked objects
+
+Current baseline (~260k queue):
+- Start: 442 MB
+- Running: 1.6 GB
+- Per-job overhead: ~4.5 KB