feat: multi-agent Polymarket opportunity scanner + dashboard artifact

.gitignore

@@ -1,7 +1,15 @@
+docs/superpowers/
+.superpowers/
+
 # macOS
 .DS_Store
 
 # Editor/OS cruft
 *.swp
 .idea/
 .vscode/
+
+# Python
+__pycache__/
+*.pyc
+.pytest_cache/

CLAUDE.md

@@ -0,0 +1,57 @@
+# CLAUDE.md
+
+Context for developing **this repo** — the `polymarket` agent skill.
+(To *use* the skill, start at [SKILL.md](SKILL.md).)
+
+## What this is
+
+An **instruction-only** Claude/OpenClaw skill driving the `poly` CLI + a Polymarket MCP to
+query, trade, and run a multi-agent opportunity scan. Strategy logic lives in Markdown specs,
+**not code**. The only executable code is three thin helpers:
+- `assets/risk_gate.py` — money-guarding decision core (config + Opportunity validation + `decide()` + CLI).
+- `assets/poly-mcp.sh` — MCP-over-HTTP transport (handshake → `tools/call`).
+- `assets/build_data.py` — orchestration→artifact bridge: maps the scan's universe + gated opportunities (+ account) into the dashboard `DATA` and injects `assets/dashboard-template.html` (pure/stdlib, `tests/test_build_data.py`).
+
+## Commands
+
+```bash
+# Tests — no pyproject/venv; uv pulls deps inline:
+uv run --with pytest --with jsonschema pytest tests/ -v
+
+# Risk gate (reads an Opportunity JSON on stdin):
+echo '<opportunity-json>' | python3 assets/risk_gate.py decide --run-total <usd>
+echo '<opportunity-json>' | python3 assets/risk_gate.py validate
+
+# Polymarket MCP (read-only market data):
+assets/poly-mcp.sh screen_markets '{"sort_by":"volume_spike","interval":"24h","limit":10}'
+
+# Build the dashboard artifact (maps a scan run -> DATA -> injects template):
+python3 assets/build_data.py --inject assets/dashboard-template.html < run.json > dashboard.html
+```
+
+## Layout
+
+- `SKILL.md` — skill entry + activation triggers.
+- `reference/orchestration.md` — multi-agent scan playbook (scout → 6 strategy agents → gate → report).
+- `reference/strategies/*.md` — the six strategy specs (the "logic", as prose).
+- `reference/config.md` + `config.example.json` — risk-gate limits (`~/.config/polymarket/agent.json`).
+- `reference/commands.md` / `recipes.md` / `mcp.md` — poly catalog, workflows, MCP guide.
+- `assets/risk_gate.py` + `assets/poly-mcp.sh` + `assets/build_data.py` — the only code.
+- `assets/dashboard-template.html` + `reference/artifacts.md` — the dashboard **artifact** (self-contained HTML + `DATA` schema). Orchestration Step 7 builds it via `build_data.py`.
+- `docs/superpowers/specs|plans/` — design spec + implementation plan.
+
+## Gotchas
+
+- **Use `assets/poly-mcp.sh`, not native `mcp__polymarket__*`.** The ECC `mcp-health-check` hook
+  sends an incomplete `Accept` header, gets a 406, and wrongly blocks the (healthy) MCP. The helper
+  sends `Accept: application/json, text/event-stream`.
+- **`risk_gate.decide()` is the only thing that authorizes real money.** Keep it stdlib-only
+  (`jsonschema` is imported lazily, inside `validate_opportunity` only). Any change to its 8 ordered
+  checks or comparison operators must update the boundary tests in `tests/test_risk_gate.py`.
+- **Auto-execute is allowlisted to structural arbs** (`risk-free-arb`, `multi-outcome-arb`) in
+  `risk_gate.DEFAULTS` — the single enforcement point. Directional strategies always escalate.
+- **Conservative limit defaults live in `risk_gate.DEFAULTS`**; a user `agent.json` overrides them.
+  Keep the code defaults conservative — they're the safety floor.
+- **`build_data.py` never fetches.** The orchestration step hands it the universe, gated opportunities,
+  enrichment, and (only when a wallet is set up) account — a null `account` makes the dashboard render
+  wallet-setup steps. Keep it pure/stdlib so `tests/test_build_data.py` stays hermetic.

README.md

@@ -35,6 +35,7 @@
 | *"Buy $5 of YES on `<market>` at 0.42."* | dry-run preview → submits with `--yes` |
 | *"Show my open positions and portfolio value."* | `data positions` · `data value` |
 | *"Cancel all my open orders."* | `clob cancel-all` |
+| *"Scan Polymarket for opportunities."* | runs the multi-agent scan → ranked opportunities, auto-fires structural arbs within limits, escalates the rest |
 
 ## 📦 What's inside
 
@@ -68,7 +69,19 @@ poly setup                     # hidden prompt → ~/.config/polymarket/config.j
 # or: export POLYMARKET_PRIVATE_KEY=0x...
 ```
 
-**3. Install the skill:**
+**3. Load the Polymarket MCP** (read-only market data — powers search, screening & the scanner):
+
+```bash
+claude mcp add --transport http --scope user polymarket \
+  https://polymarket.mcp.askcloud.ai/mcp \
+  --header "Authorization: Bearer <YOUR_BEARER_TOKEN>"
+claude mcp get polymarket      # verify → Status: ✔ Connected
+```
+
+> Swap in your own bearer token. The skill reaches the server through `assets/poly-mcp.sh`, which reads
+> the URL + token from `~/.claude.json` and never echoes it — more in [reference/mcp.md](reference/mcp.md).
+
+**4. Install the skill:**
 
 ```bash
 # Claude Code — drop it in so SKILL.md sits at the folder root
@@ -79,6 +92,14 @@ Restart Claude Code; it activates whenever you mention Polymarket, prediction-ma
 bet. **OpenClaw / clawhub** — the same folder installs as an OpenClaw skill; users just need `poly` on
 their `PATH` via the one-liner above.
 
+> **Developing the skill itself?** Symlink instead of copying, so edits to your working tree are reflected
+> in the installed skill with no re-copy:
+> ```bash
+> ln -s "$(pwd)/polymarket-skill" ~/.claude/skills/polymarket
+> ```
+> Restart Claude Code after edits to reload (skills load at session start). `rm ~/.claude/skills/polymarket`
+> removes only the symlink, never your repo.
+
 ## 🆕 New wallet? Activate it first
 
 Importing or creating a key only configures *signing*. A wallet that has **never been used on
@@ -93,9 +114,12 @@ agent will walk you through this — full steps in the
 
 ## 🔒 Safety
 
-Trades spend **real USDC on Polygon.** This skill ships an **autonomous** posture — the agent may submit
-live orders with `--yes` without per-order approval — and does **not** enforce spending limits (a
-deliberate, thin-by-design choice; the limits in [SKILL.md](SKILL.md) are guidance, not hard caps).
+Trades spend **real USDC on Polygon.** The base `buy`/`sell` flow ships an **autonomous** posture — the
+agent may submit live orders with `--yes` without per-order approval — and does **not** enforce spending
+limits there (a deliberate, thin-by-design choice; the limits in [SKILL.md](SKILL.md) are guidance). The
+**multi-agent scanner is different**: its risk gate enforces hard caps (per-order, per-run, liquidity,
+depth) and only auto-executes structural arbs — everything else escalates. Tune those caps in
+[reference/config.md](reference/config.md).
 
 ✅ Prefer a `--dry-run` preview before any live order &nbsp;·&nbsp; ✅ Tell the agent your per-order /
 per-day limits if you want them honored &nbsp;·&nbsp; ✅ A wallet must be funded **and** approved to fill.

SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: polymarket
-description: Query and trade on Polymarket prediction markets — search markets, check live odds/order books, view positions and balances, place and cancel orders. Use when the user mentions Polymarket, prediction-market odds, betting on an event/election/crypto outcome, or wants to check or trade a market's probability.
+description: Query and trade on Polymarket prediction markets — search markets, check live odds/order books, view positions and balances, place and cancel orders, and run a multi-agent opportunity scan that hunts mispricings and arbitrage across strategies. Use when the user mentions Polymarket, prediction-market odds, betting on an event/election/crypto outcome, wants to check or trade a market's probability, or asks to scan/find Polymarket opportunities.
 ---
 
 # Polymarket
@@ -111,3 +111,42 @@ following as obligations on the agent's behavior:
 
 Copy-pasteable multi-step workflows (find→price→preview→submit, check positions, cancel a market's
 orders, activate a new wallet): [reference/recipes.md](reference/recipes.md).
+
+## Opportunity scanning (multi-agent)
+
+When the user asks to **scan / find opportunities** (mispricings, arbitrage, movers worth
+trading), run the orchestration playbook in [reference/orchestration.md](reference/orchestration.md).
+In one on-demand pass it: scouts a shared candidate universe via the MCP, fans out six
+parallel strategy sub-agents (momentum, mean-reversion, multi-outcome-arb, spread-capture,
+risk-free-arb, smart-money — see [reference/strategies/](reference/strategies/)), synthesizes
+and ranks their Opportunity objects, then runs each through the deterministic risk gate
+(`assets/risk_gate.py`).
+
+**Semi-auto execution.** The risk gate decides per opportunity: **auto-execute** (only the
+structural arbs — `risk-free-arb`, `multi-outcome-arb` — when confident and within limits),
+**escalate** (everything else, incl. all directional strategies → ask the user), or **skip**.
+Auto-executed orders always run `--dry-run` and a preview match before `--yes`. Hard limits
+live in `~/.config/polymarket/agent.json` (every key explained in [reference/config.md](reference/config.md));
+conservative defaults apply if absent, and the user may override limits inline for a run.
+
+**MCP access.** Reach the polymarket MCP through [assets/poly-mcp.sh](assets/poly-mcp.sh)
+(see [reference/mcp.md](reference/mcp.md)); native `mcp__polymarket__*` calls may be blocked
+by a health-check hook false positive.
+
+## Dashboard artifact (visualize)
+
+When the user asks to **show / visualize / "make a dashboard" / "display my positions or markets"**,
+render the multi-tab HTML dashboard as an **Artifact** instead of printing JSON tables. The artifact is
+sandboxed — it **cannot** run `poly` or call the MCP — so you inject a data snapshot at generation time.
+Full procedure, `DATA` schema, and source map: [reference/artifacts.md](reference/artifacts.md).
+
+1. **Fetch** what they asked to see: Markets → `markets get/search` (+ MCP `get_order_book_depth`,
+   `get_price_history`, `get_market_stats` for depth / OHLC candles / flow); Recommendations → your own
+   analysis; Account → `clob balance`, `data value`, `data positions`, `clob orders`, `clob trades`,
+   `wallet show` (skip and set `account: null` if no key is configured).
+2. **Build** one `DATA` object (schema in artifacts.md). Keep numbers as the Decimal strings the sources
+   return; stamp `meta.generated_at` = now. Unfetched lists → `[]`, skipped objects → `null`.
+3. **Inject** — read [assets/dashboard-template.html](assets/dashboard-template.html), replace only the
+   `POLYMARKET_DATA_START…END` block with your `const DATA = {…}`, emit the file as the artifact.
+4. **Caveat**: the dashboard is a snapshot frozen at `generated_at`; tell the user to regenerate for
+   fresh data. Always render through this template — don't hand-roll one-off dashboard HTML.