Merge branch 'pr-36' (rate limiting) into 0.0.3-draft

Combined MAX_RESPONSE_SIZE dynamic calculation with RateLimiter class.

skills/polymarket-browse/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: polymarket-browse
+version: 0.0.2
 category: research
 description: Browse tradeable Polymarket events by game category. Shows active matches with ML odds (cents format), volume, tournament, and market URLs. Supports Counter Strike, League of Legends, Dota 2, Valorant, NBA, NFL, UFC, Tennis.
 ---
@@ -34,7 +35,7 @@ hermes mcp add polymarket https://docs.polymarket.com/mcp
 ## Usage
 
 ```
-polymarket-browse [--category "Counter Strike"] [--limit 5] [--matches N] [--non-matches N] [--search "TeamName"] [--matches-only] [--non-matches-only] [--detail N] [--raw] [--telegram]
+polymarket-browse [--category "Counter Strike"] [--limit 5] [--matches N] [--non-matches N] [--search "TeamName"] [--matches-only] [--non-matches-only] [--detail N] [--raw] [--telegram] [--no-cache] [--max-total N] [--starts-before TIMESTAMP] [--timezone UTC+X]
 ```
 
 ## Arguments
@@ -49,6 +50,10 @@ polymarket-browse [--category "Counter Strike"] [--limit 5] [--matches N] [--non
 - `--detail` : Index of match event (1-indexed) to show detailed markets. Default: 1. Set to 0 to disable.
 - `--list-categories` : List available game categories and exit
 - `--raw` : Show all events without tradeable filter (for debugging). Includes fetch stats.
+- `--no-cache` : Disable caching and fetch fresh data from the API.
+- `--max-total` : Maximum total events to fetch before early exit. Default: no limit. Useful for quick snapshots.
+- `--starts-before` : Unix timestamp filter. Only show match events starting before this time (LIVE events always shown regardless of timestamp).
+- `--timezone` : Timezone for displaying times. Format: `UTC+X` or `UTC-X` (e.g., `UTC+7`, `UTC-5`). Default: UTC+7 (WIB).
 - `--telegram` : Send results to Telegram. Requires `BOT_TOKEN` and `CHAT_ID` in environment variables.
 
 ## Output Format
@@ -118,13 +123,32 @@ Use `--raw` to disable the tradeable filter and see all match markets regardless
 
 ## Pagination
 
-The script fetches **ALL pages** until the API runs out of results (up to 100 pages as a safety cap).
+The script fetches **ALL pages** until the API runs out of results.
+
+### Parallel Fetching
+
+Pages are fetched in **parallel batches of 5** using ThreadPoolExecutor. This significantly reduces fetch time:
+
+| Scenario | Without Parallelization | With Parallelization |
+|----------|------------------------|---------------------|
+| 10 pages (50 events) | ~20s (2s per page × 10) | ~4s (2s per batch × 2 batches) |
+| 20 pages (100 events) | ~40s | ~8s |
+
+The script first fetches page 1 to determine total pages, then fetches remaining pages in parallel batches of 5.
 
 ## Rate Limiting
 
 - Exponential backoff: 2s → 4s → 8s → 16s → 32s
 - Max 5 retries before aborting
 
+## Caching
+
+Results are cached in `~/.cache/polymarket-browse/` with a **5-minute TTL** to reduce redundant API calls.
+
+- Use `--no-cache` to bypass the cache and fetch fresh data
+- Cached data is automatically used when available and not expired
+- Useful when running the script repeatedly (e.g., for monitoring)
+
 ## Odds Format
 
 All odds are shown in **cents** format: