feat(api): sync /api/download with dl CLI flags and add serve.* defaults

- Wire --no-proxy-download through download_manager + handlers + swagger
- Add tag/proxy/tmdb_id/animeapi_id/enrich/worst to DEFAULT_DOWNLOAD_PARAMS
- Normalize `slow` (bool/"MIN-MAX" string/list) to tuple before invoking dl.result
- Overlay any /api/download flag declared under `serve:` in unshackle.yaml as a default (downloads, workers, best_available, etc.); request body still wins
- Quiet successful worker stderr from `warning` to `debug` (kept under job.worker_stderr for ?full=true)
- Include HYBRID in range validator
- Document new flags + overlay layering + max_concurrent_downloads / download_job_retention_hours

docs/ADVANCED_CONFIG.md

@@ -46,6 +46,22 @@ unshackle serve --remote-only            # Only expose remote service session en
   - `username` - Internal logging name for the user (not visible to users)
   - `services` - Optional per-user service allowlist. Effective access is the intersection of global and per-user allowlists.
 
+#### Server-side `dl` defaults
+
+Any key accepted by `/api/download` (see `docs/API.md`) can also be declared directly under `serve:` and the REST API will treat it as a default. Per-request bodies still win. Use this to raise concurrency, force `best_available`, etc. without each client repeating the values:
+
+```yaml
+serve:
+  api_secret: "..."
+  users: { ... }
+  downloads: 4              # parallel tracks per job
+  workers: 16               # threads per track
+  best_available: true
+  no_proxy_download: false
+```
+
+Layering: built-in defaults < `serve.*` overrides < service-specific defaults < request body.
+
 For example,
 
 ```yaml
@@ -88,6 +104,26 @@ See [API.md](API.md) for full REST API documentation with endpoints, parameters,
 
 ---
 
+## max_concurrent_downloads (int)
+
+Maximum number of `/api/download` jobs the serve queue manager will execute in parallel. Each job runs the full `dl` pipeline (authenticate, fetch tracks, decrypt, mux) in its own worker subprocess. This is independent of `serve.downloads`, which controls parallel tracks **inside** a single job. Default: `2`.
+
+```yaml
+max_concurrent_downloads: 4
+```
+
+---
+
+## download_job_retention_hours (int)
+
+How long completed, failed, or cancelled download jobs remain queryable via `/api/download/jobs/{job_id}` before the periodic cleanup loop drops them. Default: `24`.
+
+```yaml
+download_job_retention_hours: 48
+```
+
+---
+
 ## debug (bool)
 
 Enables comprehensive debug logging. Default: `false`

docs/API.md

@@ -77,6 +77,22 @@ There is no separate "tier" flag. Whether the server can return KID:KEY for a se
 
 Per-service CDM type can be pinned via `config.cdm` (`widevine`/`playready`) or per-service `cdm_type`; otherwise the server picks the type the user has devices for.
 
+### Server-side `dl` defaults
+
+Any flag accepted by `/api/download` (see the table below) can be declared under `serve:` in `unshackle.yaml` and the API will apply it as a default. Request-body values still win. Useful for raising concurrency without changing every client call:
+
+```yaml
+serve:
+  api_secret: "..."
+  users: { ... }
+  downloads: 4        # parallel tracks per download job
+  workers: 16         # threads per track segment fetch
+  best_available: true
+  no_proxy_download: false
+```
+
+Layering order: built-in defaults < `serve.*` overrides < service-specific click defaults < request body.
+
 ---
 
 ## Endpoint Map
@@ -300,10 +316,12 @@ Start a download job. Returns immediately with a job ID (HTTP 202). Disabled in
 | `profile` | string | `null` | Profile for credentials/cookies |
 | `proxy` | string | `null` | Proxy URI or country code |
 | `no_proxy` | boolean | `false` | Disable all proxy use |
+| `no_proxy_download` | boolean | `false` | Bypass proxy for segment downloads only. Manifest, license, and auth still use proxy |
 | `workers` | int | `null` | Max threads per track download |
 | `downloads` | int | `1` | Concurrent track downloads |
-| `slow` | boolean | `false` | Add 60-120s delay between titles |
+| `slow` | boolean or string | `null` | Add randomized delay between titles. `true` = 60-120s, or `"MIN-MAX"` string (e.g., `"20-40"`). Min must be >= 20 |
 | `best_available` | boolean | `false` | Continue if requested quality unavailable |
+| `worst` | boolean | `false` | Select the lowest bitrate track within the specified quality. Requires `quality` |
 | `skip_dl` | boolean | `false` | Skip download, only get decryption keys |
 | `export` | boolean | `false` | Export manifest, track URLs, keys, and subtitles to JSON in the exports directory |
 | `cdm_only` | boolean | `null` | Only use CDM (`true`) or only vaults (`false`) |
@@ -758,6 +776,6 @@ queued -> cancelled
 downloading -> cancelled
 ```
 
-Jobs are retained for 24 hours after completion. The server supports up to 2 concurrent downloads by default.
+Jobs are retained for 24 hours after completion (override via top-level `download_job_retention_hours` in `unshackle.yaml`). The server runs up to 2 concurrent download jobs by default; override via top-level `max_concurrent_downloads`. This is independent of `serve.downloads`, which controls parallel tracks **within** a single job.
 
 Remote sessions are managed by `SessionStore` (`unshackle/core/api/session_store.py`); idle sessions and their `InputBridge` instances are cleaned up by a background loop started/stopped with the app lifecycle.

docs/DOWNLOAD_CONFIG.md

@@ -102,6 +102,7 @@ to a CLI option on the `dl` command. CLI arguments always take priority over con
 | `require_subs` | list | `[]` | Required subtitle languages (skip title if missing) |
 | `forced_subs` | bool | `false` | Include forced subtitle tracks |
 | `exact_lang` | bool | `false` | Exact language matching (no regional variants) |
+| `latest_episode` | bool | `false` | Download only the single most recent episode of a series |
 
 **Track selection:**
 
@@ -147,6 +148,7 @@ to a CLI option on the `dl` command. CLI arguments always take priority over con
 | `downloads` | int | `1` | Concurrent track downloads |
 | `workers` | int | `min(16, cpu_count + 4)` | Max threads per track download (segments / ranged parts) |
 | `slow` | bool or `MIN-MAX` | `false` | Randomized delay between titles. `true` uses 60-120s; pass `MIN-MAX` (e.g., `20-40`) for a custom range |
+| `no_proxy_download` | bool | `false` | Bypass proxy for segment downloads only. Manifest, license, and auth still use proxy |
 | `skip_dl` | bool | `false` | Skip download, only get decryption keys |
 | `cdm_only` | bool | `null` | Only use CDM (`true`) or only vaults (`false`) |