Split how-it-works key config; document max_polling_interval

docs/introduction/how-it-works.md

@@ -51,10 +51,19 @@ The default ack policy is `NACK_ON_ERROR`: the timer is acknowledged on success,
 
 ## Key configuration
 
+### Broker constructor (`TimersBroker(...)`)
+
 | Parameter | Default | Description |
 |-----------|---------|-------------|
 | `timeline_key` | `timers_timeline` | Prefix for sorted set keys (`{timeline_key}:{topic}`) |
 | `payloads_key` | `timers_payloads` | Prefix for hash keys (`{payloads_key}:{topic}`) |
-| `polling_interval` | `0.05` s | How often to poll when no timers are due |
+| `start_timeout` | `3.0` s | Max wait for the first Redis ping during startup |
+
+### Per-subscriber (`@broker.subscriber("topic", ...)`)
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `polling_interval` | `0.05` s | Base poll interval used when the queue has work or just transitioned from idle |
+| `max_polling_interval` | `5.0` s | Ceiling for the adaptive idle backoff — `polling_interval` doubles up to this value on consecutive empty polls. Worst-case delivery latency on a previously-idle queue is `max_polling_interval × 1.5` (with ±50% jitter) |
 | `max_concurrent` | `5` | Max handlers running concurrently per subscriber; also bounds fetch batch size |
 | `lease_ttl` | `30` s | How long a worker holds the lease before another worker may re-claim |

docs/usage/router.md

@@ -56,9 +56,12 @@ You can configure polling behaviour per subscriber:
 ```python
 @router.subscriber(
     "high-priority",
-    polling_interval=0.01,   # poll every 10ms
+    polling_interval=0.01,    # poll every 10ms when the queue has work
+    max_polling_interval=0.5, # cap idle-backoff at 500ms (default 5s)
     max_concurrent=20,        # up to 20 handlers may run in parallel
     lease_ttl=60,             # hold lease for up to 60 seconds
 )
 async def handle_urgent(message: str) -> None: ...
 ```
+
+All `@broker.subscriber` options are accepted by `@router.subscriber` and `TimersRoute` — see the [subscriber page](./subscriber.md) for the full list.