docs: update README and add ARCHITECTURE

Dev setup (venv, ruff, pytest), config table entries, architecture
overview, and cleanup completion report.

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -55,6 +55,24 @@ Drop a photo into `incoming/` (via Syncthing or locally). After a few
 seconds (poll interval + processing time) it shows up on the web UI; flat
 files land in `variants/` and `intermediates/` for the phone.
 
+## Development
+
+Python **3.11** (same as `Dockerfile`). On a host with newer Python, use
+Docker or a 3.11 venv — pinned `onnxruntime` does not publish wheels for 3.14+.
+
+```bash
+python3.11 -m venv .venv && source .venv/bin/activate
+pip install -r requirements-dev.txt
+
+ruff check app/ tests/       # lint
+ruff format app/ tests/      # format
+pytest -q                    # unit tests (no gmic/rembg)
+```
+
+CI (`.gitea/workflows/ci.yml`): ruff + pytest on push/PR.
+
+Architecture notes: `ARCHITECTURE.md`. Cleanup log: `CLEANUP_PLAN.md`.
+
 ## Configuration (`.env`, see `.env.example`)
 
 | Var | Default | Notes |
@@ -64,6 +82,8 @@ files land in `variants/` and `intermediates/` for the phone.
 | `BLEND_OPACITY` | `30%` | Default blend opacity for auto-generated variants |
 | `FILTER_TIMEOUT` | `120` | Seconds before a single gmic call is killed |
 | `MAX_FILTER_ATTEMPTS` | `8` | Random-filter retry budget per bg/fg pick |
+| `MAX_EDGE_PX` | `2000` | Longest edge after ImageMagick preprocess |
+| `PREPROCESS_TIMEOUT` | `120` | Seconds for preprocess step |
 | `NICE_LEVEL` | `18` | `nice -n` level for gmic/rembg subprocesses |
 
 ## Deploy notes / caveats