fix(ingestor): align WebSocket subscribe + routing with live API

The Polymarket ws-live-data WebSocket requires `action: "subscribe"` in
the subscribe envelope. Without it the server accepts the connection but
never delivers trade events, causing the tracker to silently produce
zero alerts.

Additionally, incoming frames are shaped `{connection_id, payload:{...}}`
-- they do NOT echo the `topic`/`type` keys we sent. The previous routing
check matched nothing and every real trade was silently dropped.

Changes:
- Add `action: "subscribe"` to subscription message
- Route incoming messages by payload shape (transactionHash + proxyWallet)
- Add ratchet tests for payload routing edge cases
- Rewrite README as agent-first with <2min quickstart
- Add skill draft (docs/skill-tracking-prediction-market-flow.md)

Closes #89

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/skill-tracking-prediction-market-flow.md

@@ -0,0 +1,113 @@
+# Skill: tracking-prediction-market-flow
+
+Use when analyzing prediction market activity for informed-flow signals, insider
+trading patterns, or suspicious wallet behavior on Polymarket.
+
+## What This Tool Does
+
+polymarket-insider-tracker streams real-time trades from Polymarket's WebSocket
+feed, profiles trader wallets on the Polygon blockchain, and scores each trade
+for informed-flow risk using multiple detection signals:
+
+- **Fresh wallet detection**: New wallets (age < 48h, nonce <= 5) making large
+  trades (> $1k). Insiders create disposable wallets per trade.
+- **Size anomaly detection**: Trades consuming > 2% of 24h volume or > 5% of
+  visible order book depth. Informed traders bet bigger when they have edge.
+- **Niche market scoring**: Low-volume markets (< $50k daily) get a 1.5x risk
+  multiplier. Easier to have inside information on obscure events.
+- **Funding chain analysis**: Traces wallet funding sources on-chain to link
+  seemingly separate wallets to the same entity or exchange.
+- **Sniper cluster detection**: DBSCAN clustering identifies wallets that
+  consistently enter markets within minutes of creation.
+
+Composite risk scoring combines signals with configurable weights (default
+alert threshold: 0.6). Multi-signal bonuses: 2 signals +20%, 3+ signals +30%.
+
+## Installation
+
+```bash
+git clone https://github.com/pselamy/polymarket-insider-tracker.git
+cd polymarket-insider-tracker
+uv sync --all-extras
+docker compose up -d   # PostgreSQL + Redis
+cp .env.example .env   # defaults work for local dev
+uv run alembic upgrade head
+```
+
+No API keys required for basic operation (Polymarket APIs are public).
+
+## Usage
+
+```bash
+# Start the tracker (streams trades, profiles wallets, scores risk, alerts)
+uv run python -m polymarket_insider_tracker
+
+# Dry run (no alerts sent)
+uv run python -m polymarket_insider_tracker --dry-run
+
+# Debug mode (see every trade)
+uv run python -m polymarket_insider_tracker --log-level DEBUG
+
+# Validate config without starting
+uv run python -m polymarket_insider_tracker --config-check
+```
+
+## Interpreting Signals
+
+### Risk Assessment Output
+
+Each flagged trade produces a risk assessment with:
+
+- **Confidence score** (0.0-1.0): Composite of weighted signals
+- **Signal breakdown**: Which detectors fired and their individual confidence
+- **Wallet profile**: Age, nonce, transaction count, funding source
+- **Market context**: Volume, category, order book depth
+
+### Signal Interpretation Guide
+
+| Score Range | Interpretation | Action |
+|-------------|---------------|--------|
+| 0.6-0.7 | Moderate: single strong signal or two weak ones | Monitor, note the market |
+| 0.7-0.85 | High: multiple signals converging | Investigate the market and wallet |
+| 0.85-1.0 | Critical: fresh wallet + large size + niche market | High-confidence informed flow |
+
+### What This Is NOT
+
+- Not a trading signal generator. Informed flow != actionable alpha without
+  further analysis (hypothesis -> leakage-aware backtest -> capital).
+- Not real-time enough for front-running. The tool detects patterns for
+  research and monitoring, not millisecond-level execution.
+- Detection of informed flow does not prove insider trading. Many legitimate
+  reasons exist for the patterns this tool flags.
+
+## Rate Limits and Etiquette
+
+- **Polymarket WebSocket**: No explicit rate limit; one persistent connection.
+  Do not open multiple connections unnecessarily.
+- **Polymarket CLOB REST**: Built-in rate limiter at 10 req/s with retry
+  backoff on 429/5xx. Respect this for metadata/orderbook queries.
+- **Polygon RPC**: Public endpoints (polygon-rpc.com) have low limits. For
+  sustained use, configure a dedicated RPC provider via `POLYGON_RPC_URL`.
+  Built-in token-bucket rate limiter at 25 req/s with Redis caching (5min TTL).
+
+## Known Pitfalls
+
+1. **WebSocket subscription format**: Must include `action: "subscribe"` in the
+   envelope. Without it, the server accepts the connection but delivers zero
+   trade events (silent failure). Fixed in the current version.
+
+2. **Message routing**: Live-data WebSocket pushes `{connection_id, payload:
+   {...trade fields}}`, not `{topic, type, payload}`. Route by checking for
+   `transactionHash` + `proxyWallet` keys in `payload`.
+
+3. **Public RPC rate limits**: Default Polygon RPC will throttle under load.
+   Use a dedicated provider for production.
+
+4. **Database required**: PostgreSQL + Redis must be running. Use
+   `docker compose up -d` for local dev.
+
+## Cross-References
+
+- **Repository**: https://github.com/pselamy/polymarket-insider-tracker
+- **Issues**: https://github.com/pselamy/polymarket-insider-tracker/issues
+- **Agent skill landing** (follow-on): selamy-labs/agent-skills