@vike-io/cli 0.15.0 → 0.16.1

package/skills/vike-hl-builder-intel/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: vike-hl-builder-intel
+description: Hyperliquid builder codes - which front-ends and bots earn the most fees, how concentrated their users are, their symbols and fee series, and which builders one wallet routes through. Use when the user asks "which Hyperliquid builder codes earn the most" / "who runs builder X and how big is it" / "builder fee revenue" / "how much of Hyperliquid volume is routed through builders".
+allowed-tools: Bash(vike-data:*)
+---
+
+# vike-hl-builder-intel
+
+A builder code lets a front-end or bot attach its address to an order and keep a slice of the fee. About 5 calls, 1 credit each.
+
+## Chain
+
+```bash
+vike-data hl builders --view leaderboard --window 30d --sort fee --limit 10 --json     # who earns
+vike-data hl builders --view stats --window 30d --json                                  # venue totals, routed share of volume
+B=0x5af1b5f44207784dcb850bbb4143c5dcd1885f71
+vike-data hl builders --view profile --builder $B --window 30d --json                   # by symbol, by dex, user deciles, lifetime
+vike-data hl builders --view users --builder $B --window 30d --limit 10 --json
+vike-data hl builders --view series --builder $B --bucket 1d --limit 30 --json
+```
+
+`search <name>` finds a builder by name (its `builders` section). Other views: `fills` (the raw routed fills, `--symbol`, `--side`). One wallet's builders: `vike-data hl wallet-activity <wallet> --view builders --window 30d`. `--window` is `1d|7d|30d|all`; page with `nextCursor` -> `--cursor`. `profile`, `users`, `fills` and `series` require `--builder`; a flag a view does not take is refused, not ignored.
+
+## Reading
+
+- `leaderboard` rows: `rank`, `builder`, `fee_usd`, `volume_usd`, `fills`, `users`, `revenue_per_user`, `fee_rate_bps`, `taker_pct`, `market_share_pct`, `active_days`. `--sort fee` ranks the builder's own cut, not what traders paid; the order differs from `--sort volume`.
+- **Three fee columns are not interchangeable**: `fee_usd` is the builder's revenue, `trader_fee_usd` what traders paid in total, `builder_routed_deployer_fee_usd` the deployer's cut on builder-routed flow only. On `fills`, `fee` is in its own `fee_token`.
+- `stats.totals.builder_routed_share_pct` is the share of all fill notional carrying a builder code.
+- `profile` adds `by_symbol`, `by_dex`, `user_volume_distribution` (users split into volume deciles: separates "19k users" from "one whale plus a tail") and `lifetime`. In `users`, `closed_pnl_usd` (and `--sort pnl`) is the TRADERS' realized PnL, not the builder's.
+- `series` `users` is a distinct count per bucket and not additive across days; take a period total from `profile`. Builder history starts at different dates: compare `active_days` and the resolved `window` first.
+
+## Anti-patterns
+
+- Don't call a builder profitable or its users winners from `closed_pnl_usd`.
+- Don't add daily `users` together, or compare two windows of unequal `active_days`.
+
+## Pairs well with
+
+- `vike-hl-top-traders`, `vike-hl-trader-profile` (one wallet's routing)

package/skills/vike-hl-cohort-backtest/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: vike-hl-cohort-backtest
+description: Method for testing whether a Hyperliquid wallet cohort's positioning led or lagged price, with point-in-time labels and without look-ahead - which axes are honest, how to pull and align the hours, the seams and controls, how to report. Describes a method on this data; it does not claim a tradable edge. Use when the user asks "did whale / smart money positioning predict BTC" / "backtest the cohort signal" / "does the smart-minus-rekt spread lead price" / "lead or lag of Hyperliquid cohorts".
+allowed-tools: Bash(vike-data:*)
+---
+
+# vike-hl-cohort-backtest
+
+Cohort positioning against price over history. A single `--hours` call returns `hours x rungs` rows (2160 hours of the 13-rung `pnl` axis is about 28,000 rows, 13 MB), so **write each pull to a file and analyse it with code; never print it into the conversation.** 1 credit per call.
+
+## Pull
+
+```bash
+vike-data hl cohort-metrics BTC --axis pnl --label-basis point_in_time --hours 2160 --json > btc_pnl_pit.json
+vike-data hl cohort-metrics BTC --axis size --hours 2160 --json > btc_size.json
+vike-data candles hl BTC --view export --interval 1h --start 2026-08-01T00:00:00Z --json > btc_1h.json   # up to 5000 bars a call
+```
+
+Rows: `ts` (hour, UTC), `cohort`, `total_position_value`, `total_position_value_long` (USD notional), `bias` (fraction -1..+1). Newest hour first; page older hours with `nextCursor` -> `--cursor`. Candles: `ts` is epoch ms, left-aligned, the window half-open `[start, end)`.
+
+Whole-venue alternative (all symbols summed): `vike-data hl segments --view history --cohort "3x smart" --axis pnl --hours 2160 --json` (axis `size` or `pnl`; hours before 2026-04-07 are never returned; page back with `--end` = the oldest `ts` minus 1 second). Position-level history: `hl market --view positions --symbol BTC --start ...` rows carry `label_causal`, the previous hour's label.
+
+## Which labels are honest
+
+| Axis / option | Look-ahead? |
+|---|---|
+| `pnl` with `--label-basis point_in_time` | No. Point-in-time history starts 2026-04-07 (earlier hours return nothing). |
+| `size`, `tier` | No by construction: account value or position size at that hour |
+| `pnl` default (`current`) | **Yes**: today's grading applied to old hours |
+| `pnl_abs` | **Yes** always: dollar bands of today's PnL |
+| `pnl_unrealized` | No, but it grades POSITIONING (who is currently onside), not skill, and turns over far faster than the realized ladder |
+| `--grading realized-pit` | A frozen control that stops growing: a recent window comes back short; `freshness.behind_hours` says by how much |
+
+`--opened-within` is refused with `point_in_time`, `realized-pit` and `pnl_unrealized`. With `point_in_time` the rows leave out `position_count*`, `total_unrealized_pnl` and `total_position_size*`: use only the notional columns and `bias`, and never read a missing value as 0. Read `label_computed` on every response: it names the source and the seam. **Label resolution changes at 2026-08-06**: daily labels before (constant across that day's 24 hours), hourly after. A turnover count or a difference taken across the seam shows an artefact that looks like a regime change; split the sample there or use `realized-pit` as the control.
+
+## Signal definitions
+
+- Group several rungs by summing notional: `bias_g = (2*sum(L) - sum(V)) / sum(V)` with `L = total_position_value_long`, `V = total_position_value`. Never average the biases.
+- Level (`bias_g`), change (`bias_g[t] - bias_g[t-k]`), or the spread between a top group (`3x smart`, `2x smart`, `smart`) and a bottom group (`rekt`, `2x rekt`, `3x rekt`). Leave `unknown` out.
+
+## Alignment and statistics
+
+1. The in-progress hour is never returned, so a row stamped `T` is only knowable once hour `T` has closed. Measure forward returns from the OPEN of candle `T+1h`, never from candle `T`. Check the alignment on your own sample before trusting a lag of one or two hours.
+2. Forward returns at several horizons (1h, 4h, 24h) and lead/lag correlations over lags in both directions. If the cohort moves AFTER the return, that is positioning chasing price, not a lead.
+3. Neighbouring hours overlap and positions are autocorrelated: report the number of independent observations, not the number of hours, and a confidence interval. Count the cohorts, lags and horizons you tried and correct for it.
+4. Split the sample (before / after 2026-08-06, or first half / second half) and say which half the result lives in.
+5. Add a placebo: the same test on the `size` axis, or on a shuffled cohort assignment.
+
+## What to report
+
+> On `<symbol>`, `<axis>` with point-in-time labels, `<start>` to `<end>` (`N` hours, about `M` independent): `<signal>` vs the `<h>`-hour forward return from the next candle's open: correlation `<r>` (CI `<lo, hi>`); first half `<r1>`, second half `<r2>`; placebo `<r0>`. Labels change resolution on 2026-08-06. This describes this sample; it is not an out-of-sample test or a trading rule, and costs, funding and slippage are not included.
+
+## Anti-patterns
+
+- Don't use the default `pnl` labels or `pnl_abs` for anything backtest-like.
+- Don't quote a hit rate without the sample size and the placebo; don't call a lag "alpha".
+- Don't extrapolate: the point-in-time history starts 2026-04-07, one regime.
+
+## Pairs well with
+
+- `vike-hl-cohort-positioning` for the current read, `vike-candles` for the price series, `vike-hl-asset-briefing` for context

package/skills/vike-hl-cohort-positioning/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: vike-hl-cohort-positioning
+description: Are whales, profitable wallets or losing wallets net long or short a Hyperliquid symbol right now - long/short notional per wallet cohort on the size and pnl ladders, the smart-money and whale indices, and the biggest individual positions, plus live feeds of the cohort lean, cohort leverage and the top-10 positions per coin. Use when the user asks "are whales long or short BTC" / "what are profitable Hyperliquid wallets doing on ETH" / "who is long SOL on Hyperliquid" / "Hyperliquid positioning" / "net long or short by wallet size".
+allowed-tools: Bash(vike-data:*)
+---
+
+# vike-hl-cohort-positioning
+
+A current read of how each wallet cohort is positioned in ONE symbol. 1 credit per call, about 6. For history and anything backtest-like use `vike-hl-cohort-backtest`: this skill's `pnl` labels are today's.
+
+## Chain
+
+```bash
+vike-data hl segments --view cohorts --json                       # the exact cohort labels per ladder
+vike-data hl cohort-metrics BTC --axis size --hours 1 --json      # whales: one row per size rung
+vike-data hl cohort-metrics BTC --axis pnl  --hours 1 --json      # profitable vs losing wallets (today's grading)
+vike-data hl market --view indices --symbol BTC --hours 24 --json # series: smi, wsi per hour; latest: also smart_bias, whale_bias
+vike-data hl segments --view summary --axis pnl --cohort smart --json     # that cohort across ALL symbols
+vike-data hl market --view positions --symbol BTC --sort size --limit 20 --json   # the biggest open positions, largest first
+```
+
+`--hours 1..24` is a current read; the newest SETTLED hour comes back (the hour in progress never does). Symbols are upper case; a HIP-3 market is `dex:TICKER`. Read `freshness`: `stale: true` means do not call it "now" (`behind_hours` says how far behind).
+
+## Units and the ladders
+
+- `bias` = (long - short) / (long + short) of NOTIONAL, a **fraction** from -1 (all short) to +1 (all long). Long share = (1 + bias) / 2. `total_position_value` and `total_position_value_long` are USD; `position_count` counts positions.
+- **Several rungs as one group: sum the notional, never average the biases.** `bias_group = (2 * sum(total_position_value_long) - sum(total_position_value)) / sum(total_position_value)`.
+- `size` ladder = account value: `shrimp` from $0, `fish` $10k, `dolphin` $50k, `shark` $250k, `whale` $1M, `2x whale` $2.5M, `3x whale` $5M, `4x whale` $10M and up. `pnl` ladder = percentile of cumulative realized PnL with at least 10 closed trades, from `3x smart` (top) through `winner` / `loser` to `3x rekt`; `unknown` = too few trades. `hl segments --view segments` gives each rung's bounds.
+- The indices are ratios from -1 to +1: `smi` = long share of the smart cohorts minus that of the rekt cohorts, `wsi` = long share of whales minus shrimp, `smart_bias` / `whale_bias` = (long - short) / (long + short) of those groups. `hl market --view indices` returns `series` (settled hours, `smi` and `wsi` only, pnl rungs graded as of their hour) and `latest` (the newest snapshot, today's grading, with `smart_bias` and `whale_bias` too). `smi_wsi_gap` exists only on the `hl.indices` stream and in `hl_cohort_bias` alerts.
+
+## Reading
+
+- Check `position_count` and the rung's notional before saying a cohort "is short": 20 wallets, or one wallet, can set a rung's bias. Compare rungs, not just totals: whales net short while `smart` is net long is a disagreement worth stating as such.
+- `--opened-within 24h|7d|30d` (on `cohort-metrics` and `segments summary`) restricts to recently opened positions: how much of the lean is new.
+- `hl market --view positions --sort size` needs `--symbol` and at most `--limit 500`, and takes no cursor; each row has `size_usd`, `leverage`, `liquidation_price`, `unrealized_pnl`, `opened_at` and the wallet's `account_value`. Without `--sort size` rows come in key order, not by size. Never run `positions` without `--symbol` or `--wallet`.
+
+## Live
+
+```bash
+vike-data stream hl-cohorts --channel hl.cohort_bias --filter coin=BTC --filter axis=pnl     # every cohort's long/short, each position capture (~12 min)
+vike-data stream hl-cohorts --channel hl.indices --filter coin=BTC,ETH --filter index=smi,wsi   # only when an index crosses -0.10 / +0.10
+```
+
+`hl.cohort_bias` covers the 50 coins with the most open value; a `cohort` belongs to one axis (`3x smart` with `axis=size` matches nothing).
+
+```bash
+vike-data stream hl-cohorts --channel hl.cohort_leverage --filter axis=size --filter cohort=whale,shark   # leverage per cohort, once an hour
+vike-data stream hl --channel hl.top_positions --filter coin=BTC --filter event=entered                  # who enters the BTC top 10
+```
+
+- **`hl.cohort_leverage`** is the hourly leverage of each cohort on its own money: `perp_bias` = (long - short) / account value, `equity_exposure` = (long + short) / account value (`null` when no wallet of the cohort has a positive account value), with `equity_covered_share` saying how much of the cohort's notional the counted wallets hold. Main-dex positions of native perp accounts, no coin and no wallet; the newest hour arrives at once, then one an hour (hour 08:00 at about 09:03). The same numbers as history: `hl segments --view history --axis size --cohort whale --include leverage`.
+- **`hl.top_positions`**: per coin of the top 50, a position that `entered`, `left` or `moved` within the top 10, at each capture (about 12 minutes), with `rank`, `prev_rank`, `direction`, `size_usd`, `leverage`, `liquidation_price`. The first capture sends the whole top 10 of every coin as `entered` (with a `coin` filter: 10 events). The ranking is that of `hl market --view positions --sort size`, live.
+- The three `stream hl-cohorts` lines above are alternatives: one key holds one connection per path, so a second `stream hl-cohorts` replaces the first (`4410`). Put channels in one command only when each takes every `--filter` key (`hl.cohort_leverage` has no `coin`), or give each its own key.
+
+For a stored rule: `vike-data alerts create --type hl_cohort_bias --index smi ...` (see `vike-alerts-setup`).
+
+## Answer template
+
+> BTC on Hyperliquid, hour `<ts>` UTC (`freshness.stale: false`): whales (`4x`..`whale`) are `<bias_group>` (`$L` long / `$S` short across `N` positions); `smart` wallets are `<bias>`; `rekt` wallets `<bias>`; `smi` `<v>`. Positioning is notional-weighted, today's cohort labels, Hyperliquid only: a position can be a hedge held elsewhere.
+
+## Anti-patterns
+
+- Don't turn a lean into a price forecast, and don't say "smart money is short" when the group is one rung of 20 positions.
+- Don't use these default labels on history: the `pnl` ladder is graded today (look-ahead).
+- Don't write `bias` or an index as a percent: they are fractions.
+
+## Pairs well with
+
+- `vike-hl-asset-briefing` (adds funding, OI, liquidations), `vike-hl-cohort-backtest` (history), `vike-hl-trader-profile` (one wallet from the positions list)

package/skills/vike-hl-liquidation-radar/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: vike-hl-liquidation-radar
+description: Where Hyperliquid liquidations are likely - which liquid symbols have the most open interest near liquidation, where one symbol's liquidation clusters sit around the mark, which liquidations just happened, and a live feed of positions entering the liquidation zone, of liquidations as they print and of leveraged position changes. Use when the user asks "which coins are closest to a liquidation cascade" / "where are ETH liquidations clustered" / "liquidation heatmap" / "who just got liquidated on Hyperliquid" / "alert me to big liquidations".
+allowed-tools: Bash(vike-data:*)
+---
+
+# vike-hl-liquidation-radar
+
+Three reads of the same idea and a live feed, 1 credit per call. Risk and the heatmap come from 5-minute position snapshots, so they are inferred; the liquidation events are read from the liquidated accounts' own fills since 2026-08-03 (inferred from snapshots before).
+
+## Chain
+
+```bash
+vike-data hl liquidations --view risk --min-value-usd 50000000 --json       # symbols with $50M+ open, ranked by percent_risk
+vike-data hl liquidations --view heatmap --symbol ETH --bins 20 --json      # liquidation value per price bin
+vike-data hl liquidations --view fills --symbol ETH --direction long --limit 50 --json   # recent long liquidations
+vike-data candles hl ETH --interval 1h --limit 48 --json                    # distance from the mark to the clusters
+```
+
+## Reading
+
+- **`risk`**: rows `symbol`, `total_value_usd`, `risk_value_usd`, `percent_risk` (a **fraction**, 0.234 = 23.4%), `positions_count`, `at_risk_count`. A position is at risk when it sits within half of its liquidation buffer. The ranking is by `percent_risk`, so without `--min-value-usd` thin HIP-3 and micro-cap markets lead. Add `--axis size|pnl|pnl_abs --cohort <label>` to ask the same of one cohort.
+- **`heatmap`** (`--symbol` required, `--bins` 5-500): bins are equal-width over +-50% of `mark_price`, each with `liquidation_value_usd`, `positions_count`, `long_value_usd`, `short_value_usd`, `most_impacted_cohort`. **Long liquidations sit below the mark** (price falling), shorts above. `coverage` says what the map leaves out (positions beyond +-50% and those with no liquidation price), so a cluster is a floor.
+- **`fills`**: `--direction` is the side of the position that was CLOSED (`long` = longs liquidated = price falling). `--wallet <addr>` asks whether one wallet was liquidated. Most rows are small: sort by size before quoting.
+- Liquidation prices move with margin, price and funding; a cluster is a snapshot, not a level that will be hit.
+
+## Live
+
+```bash
+vike-data stream hl --channel hl.liq_risk hl.liquidations --filter coin=BTC,ETH,HYPE --filter min_usd=1000000
+```
+
+- **`hl.liq_risk`**: a position of $100,000 or more announced once as its `liq_ratio` reaches 0.80 (0 = at entry, 1 = at the liquidation price), not again until it drops below 0.70 or closes. It comes with each position capture, about every 12 minutes. The first capture after the channel starts sends every position already in the zone with `prev: null` (about 300 on 2026-11-02); after that `prev: "out"` = just entered. `data` has `direction`, `liq_ratio`, `mark_price`, `entry_price`, `liquidation_price`, `size_usd`, `leverage`.
+- **`hl.liquidations`**: each liquidation from the account's own fill, typically within a minute or two, `data.direction` the closed side, `size_usd`, `mark_price`; no size floor of its own.
+- `min_usd` is the position size on `hl.liq_risk` and the liquidation size on `hl.liquidations`. A stored rule for one wallet: `vike-data alerts create --type hl_liq_proximity --wallet 0x... ...` (see `vike-alerts-setup`).
+- **`hl.positions`**: the fills that change a big position (a wallet of $250,000 or more, or a position that size before or after the fill), each with `data.leverage` and `data.liquidation_px` of the wallet's position BEFORE the fill (the last capture, up to about 25 minutes old; `null` for an `open`; a `liquidation_px` of 0 means none) and `labels.tags`. `min_leverage=20` keeps the fills of positions at 20x or more (a `null` never matches); `tag` filters the wallet's trader tags; `min_usd` is the FILL's size (a floor of $1,000 you cannot lower). `hl.liq_risk` and `hl.liquidations` refuse `min_leverage` and `tag`, so it cannot share the command above:
+
+```bash
+# instead of the line above (one connection per key and path: a second `stream hl` replaces the first with 4410), or under its own key
+vike-data stream hl --channel hl.positions --filter coin=BTC,ETH,HYPE --filter min_leverage=20
+```
+
+## Answer template
+
+> Closest to a cascade among symbols with at least $50M open: `<symbol>` `<percent_risk>` (`$risk` of `$total`). `<ETH>`: `$V` of long notional liquidates between `<p1>` and `<p2>` (`<x%>` below the mark), `$W` of shorts above `<p3>`; the map covers `<c>` of open notional. Last hour: `<n>` long liquidations, largest `$M`.
+
+## Anti-patterns
+
+- Don't rank micro-cap or HIP-3 markets next to BTC without the notional floor.
+- Don't write `percent_risk` as a percent without multiplying, or treat the heatmap as complete.
+- Don't predict a cascade: say where open interest is exposed.
+
+## Pairs well with
+
+- `vike-hl-asset-briefing`, `vike-hl-cohort-positioning` (who holds the exposed side), `vike-candles`, `vike-stream`

package/skills/vike-hl-position-match/SKILL.md

@@ -78,9 +78,10 @@ The response includes `tolerance_used` so the caller knows which band matched (`
 
 - Don't fabricate matches when the tool returns `match_count: 0`. Say "no open position matches that share card" — closed positions, post-card adds, or non-HL cards all produce empty results.
 - Don't strip the address when displaying — share-card investigations always want the full 0x...40hex (users copy-paste it).
-- Don't infer trader skill from a single share-card match. Use `vike-data perp top-traders` for leaderboard context (see `vike-hl-top-traders` for what it can and cannot say about one address).
+- Don't infer trader skill from a single share-card match. Profile the wallet with `vike-hl-trader-profile` (`vike-data hl wallet <address>`).
 
 ## Pairs well with
 
-- `vike-hl-top-traders` — check if the matched wallet is on a leaderboard. (`vike-data wallet summary` has no Hyperliquid data: it shows on-chain transfer activity on one chain only.)
+- `vike-hl-trader-profile` — track record, equity, open positions, funding and deposits of the matched wallet.
+- `vike-hl-top-traders` — where the wallet ranks. (`vike-data wallet summary` has no Hyperliquid data: it shows on-chain transfer activity on one chain only.)
 - `vike-wallet-label-provenance` — find out if the wallet is a known CEX/fund/MM rather than a retail trader.

package/skills/vike-hl-top-traders/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vike-hl-top-traders
-description: Rank top Hyperliquid perp traders by PnL / ROI / win rate / volume / trade count / drawdown across a window, and check whether one HL address is on that leaderboard. Use when the user asks "top HL traders" / "best Hyperliquid wallets" / "HL leaderboard" / "is this trader any good" / "profile this address" / "what's this wallet's HL track record".
+description: Rank Hyperliquid perp traders by PnL / ROI / win rate / volume / trade count / drawdown over a window - the quick top list, or the full leaderboard with Calmar, profit factor, streaks, cohort filters, paging and PnL net of deposits - and see where one address ranks. Use when the user asks "top HL traders" / "best Hyperliquid wallets" / "HL leaderboard" / "who made the most on Hyperliquid this week" / "top traders net of deposits".
 allowed-tools: Bash(vike-data:*)
 ---
 
@@ -36,21 +36,35 @@ An object `{ "traders": [...], "total": N }`; each trader:
 
 `address`, `total_realized_pnl` (USD), `roi_pct`, `win_rate_pct`, `long_win_rate_pct`, `short_win_rate_pct`, `win_count`, `loss_count`, `trade_count`, `total_volume` (USD), `long_pnl`, `short_pnl`, `max_drawdown_pct`, `account_value` (USD), `avg_leverage`.
 
-All `*_pct` fields are percents: `12.5` means 12.5%. (Before 2026-10-19 `roi_pct` and `max_drawdown_pct` came back 100× too large; a transcript showing a 1,750% ROI is from that period.) `avg_leverage` is not populated (reads 0): ignore it. There is no `pnl_usd` and no `max_drawdown_usd`.
+All `*_pct` fields are percents: `12.5` means 12.5%. (Before 2026-10-19 `roi_pct` and `max_drawdown_pct` came back 100× too large; a transcript showing a 1,750% ROI is from that period.) `avg_leverage` is the notional-weighted leverage of the open positions (real since 2026-10-25); 0 = no open position. There is no `pnl_usd` and no `max_drawdown_usd`.
 
 ## Reading
 
 - **`roi_pct` is realized only.** It is the window's realized PnL divided by the wallet's CURRENT account value. Open positions are not counted, and a wallet that has since withdrawn most of its equity looks better than it was (and a recent deposit makes it look worse).
-- **`max_drawdown_pct` is account-level and all-time**, built from the account's hourly equity history. It does not change with `--window`.
+- **`max_drawdown_pct` is account-level and all-time** here, a percent from 0 to 100 built from the account's equity history; `null` = too little equity history to say. It does not change with `--window`.
 - **Windows are UTC days:** `1d`, `7d`, `30d` mean today plus the previous 1, 7 or 30 days; `all` is the last 365 days.
-- **`trade_count` counts completed trades only**, filed under the UTC day the position opened. A trade still open, or opened before the window and closed inside it, is not counted, so a wallet's count here differs from a per-wallet trade summary (which counts both).
+- **`trade_count` counts the trades CLOSED in the window** (filed under the UTC day they closed, whenever they opened). A trade still open is not counted, so a wallet's count here differs from a per-wallet trade summary (which counts open trades too).
 - A wallet with 90% win rate on 4 trades is statistical noise. Min trades 10–20 for any "skill" claim.
 - Top by PnL ≠ top by ROI. Whales win big in $ but small in % terms; ROI sort surfaces smaller-account discretionary skill.
 - The leaderboard rewards survivors: wallets that blew up don't appear, so the PnL distribution is right-skewed.
 
+## `hl leaderboard`: the full board
+
+```bash
+vike-data hl leaderboard
+  [--view ranking|flow_adjusted] [--window 1d|7d|30d|all]
+  [--sort pnl|realized_pnl|roi|volume|trades|win_rate|profit_factor|expectancy|calmar|max_drawdown|current_drawdown|fees|win_streak|...]   # an unknown key is refused
+  [--order asc|desc] [--cohort <label> --axis size|pnl|pnl_abs]
+  [--min-trades N] [--min-win-rate F] [--min-volume USD]   # win rate is a FRACTION here: 0.6 = 60%
+  [--limit N]            # default 25, max 500; page with nextCursor -> --cursor (resend the same filters)
+  [--json]
+```
+
+Rows are keyed `wallet` (not `address`) with `account_value`, `total_realized_pnl`, `pnl_pct`, `roi`, `win_rate` (a fraction), `profit_factor`, `expectancy`, `max_drawdown_pct`, `current_drawdown_pct`, `calmar_ratio`, streaks, `size_cohort`, `pnl_cohort`. Prefer `pnl_pct` to `roi` (`roi` is unguarded on a near-empty account). Here the drawdown fields are computed over the window's equity (0-100; `null` = too little equity history), unlike `perp top-traders`. `--view flow_adjusted` ranks fills-derived trading PnL, which excludes deposits, and takes only `--window`, `--min-trades`, `--limit`, `--cursor`; when its `flow_unbalanced` is true the flow figures are unreliable.
+
 ## Is this specific address any good?
 
-Ask the wallet directly: `vike-data hl wallet <address> --json` (equity, open positions, cohort labels, risk metrics, lifetime flow) and `vike-data hl wallet <address> --view trades_summary --window 30d --json` (closed-trade statistics). `top-traders` cannot filter by address; to see where it ranks, scan the leaderboard for it:
+Profile the wallet itself: `vike-hl-trader-profile` (`vike-data hl wallet <address>`). To see where it ranks, scan a leaderboard for it:
 
 ```bash
 vike-data perp top-traders --window 30d --sort pnl --size 20 --json
@@ -60,9 +74,8 @@ vike-data perp top-traders --window 30d --sort win_rate --min-trades 10 --size 2
 ```
 
 - **Found** → report that row for that window and sort (all columns above). That is the whole profile you can give.
-- **Not found** → say "not in the top 20 for this window and sort". Only the top 20 of thousands of wallets ever shows, so absence says nothing about quality.
+- **Not found** → say "not in the top N for this window and sort". Absence says nothing about quality; `hl leaderboard --limit 500` pages deeper.
 - `vike-data wallet summary` has **no Hyperliquid data** (it reads on-chain transfers on one chain): don't present it as the HL profile. `vike-data labels <addr>` shows whether the address is a known entity.
-- The REST API has per-wallet Hyperliquid routes (`/v1/hyperliquid/wallets/{address}`, `.../trades/summary`), but no CLI command or MCP tool exposes them yet. Say so if the user needs fills, funding or per-trade history.
 
 Classification of a found wallet:
 
@@ -82,6 +95,6 @@ Classification of a found wallet:
 
 ## Pairs well with
 
-- `vike-hl-position-match` to find the wallet behind a share card first
+- `vike-hl-trader-profile` for one wallet's full record; `vike-hl-position-match` to find the wallet behind a share card first
 - `vike-perp-funding` to see whether the leaders are positioned against funding
 - `vike-candles` for the price action behind a period of PnL

package/skills/vike-hl-trader-profile/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: vike-hl-trader-profile
+description: Full profile of one Hyperliquid wallet - equity, open positions, cohort labels, lifetime PnL against deposits, win rate and risk metrics, per-symbol record, closed trades, funding paid, deposits and withdrawals, orders, TWAPs, leverage changes, liquidations, builder routing, and a live feed of its fills and closed trades. Use when the user gives a Hyperliquid address and asks "is this trader any good" / "profile this HL wallet" / "what is this wallet's track record" / "show the fills, funding or deposits of 0x..." / "watch this trader".
+allowed-tools: Bash(vike-data:*)
+---
+
+# vike-hl-trader-profile
+
+One address, answered from the wallet's own data (not from scanning a leaderboard). 1 credit per call. Get the address from `vike-hl-top-traders`, `vike-hl-position-match`, `hl market --view positions` or `vike-data search <name>` (its `traders` section).
+
+## Chain
+
+```bash
+W=0xfc667adba8d4837586078f4fdcdc29804337ca06
+vike-data hl wallet $W --window 30d --json                         # equity, open_positions, cohorts, lifetime, ledger_by_type, metrics
+vike-data hl wallet $W --view trades_summary --window 30d --json   # closed/open trades, medians, per-symbol record
+vike-data hl wallet-trades $W --limit 50 --json                    # closed round trips, newest close first
+vike-data hl wallet-activity $W --view funding --limit 50 --json   # funding paid or received
+vike-data hl wallet-activity $W --view ledger --limit 50 --json    # deposits, withdrawals, sends, vault events
+vike-data hl liquidations --wallet $W --json                       # has it been liquidated
+```
+
+Optional, by question: `hl wallet-activity $W --view fills --symbol BTC` (raw fills), `--view builders` (which front-ends it routes through), `hl orders --view wallet --address $W` (what became of its orders, 7 days by default, at most 30), `hl twaps --wallet $W`, `hl leverage-changes --wallet $W`, `hl market --view positions --wallet $W` (open positions with liquidation price). `--window` is `1d|7d|30d|all` (default `all`); page with `nextCursor` -> `--cursor`.
+
+## Reading
+
+- **A wallet we hold nothing for is an error**, not zeros: `hl wallet` exits 1 with "no Hyperliquid data for wallet 0x...". Say "no Hyperliquid history for this address", not "a flat trader" or "the tool failed". `last_fill_ts` is `null` for a wallet with no fill; `has_metrics: false` on an active wallet means no trades in the window, which is not zero skill.
+- `equity.account_value` is the live account; `cash_balance_usd` can be hugely negative on a cross-margin account next to a healthy account value: don't quote it as cash.
+- **Units**: `*_usd` and `account_value` are USD. `win_rate`, `long_win_rate` are FRACTIONS (0.49 = 49%); `pnl_pct`, `roi`, `*_drawdown_pct` are percents. `perp top-traders` returns `win_rate_pct` as a percent: never mix the two in one table.
+- **`max_drawdown_pct`** is a percent from 0 to 100 of the wallet's own equity (deposits and withdrawals taken out) over the window; `null` means too little equity history to say, not 0. `calmar_ratio` and `recovery_factor` derive from it and are `null` with it.
+- **Lifetime vs ledger**: compare `lifetime.cum_realized_pnl` with `net_deposit_usd` before praising PnL. The ledger records `send` one-sided and signed, so net-flow sums from it lean negative; trust `deposit` and `withdraw`, treat `send` as movement to or from other accounts.
+- **Mean vs median** (`trades_summary`): a few large trades drive the mean (a live 30-day record: `avg_gain` $73.6k against `median_gain` $4.5k). Report medians beside means, with `payoff_ratio`, `profit_factor`, `expectancy`.
+- `trade_count` here counts open and closed trades; the leaderboard counts only completed trades, so the two never match.
+- **Funding**: `payment_usd` is signed from the wallet's side, negative = the wallet PAID. **Fees**: a negative `fee` on a fill is a maker rebate.
+- Cohorts (`size`, `pnl`, style tags) are today's labels. `avg_leverage` is the notional-weighted leverage of the open positions (real since 2026-10-25); 0 = no open position, not unlevered.
+- Identity: a Hyperliquid address is an EVM address; `vike-data labels <addr>` may name it. Sub-accounts and vaults are separate addresses with no merge.
+
+## Watch it live
+
+```bash
+vike-data stream hl --channel hl.fills hl.liquidations hl.ledger hl.closed_trades --filter wallet=$W --filter min_usd=0
+```
+
+`hl.fills` alone defaults to fills of $1,000 or more; `min_usd=0` is every fill. `hl.closed_trades` sends each round trip once, when it is written as closed, in batches every 30 minutes (a trade that closed at 08:12 arrives around 08:35); its `data` is the item of `hl wallet-trades` (`realized_pnl`, `entry_price`, `exit_price`, `duration_seconds`, `max_size_usd`) and `min_usd` on it is the trade's largest size. A close shows at once as an `hl.fills` event whose `data.action` is `close`. One key holds one `stream hl` connection: add channels to this command, never start a second one. A stored rule instead: `vike-data alerts create --type hl_wallet --wallet $W ...` (see `vike-alerts-setup`).
+
+## Verdict rubric (rules of thumb, not tool output)
+
+| Pattern | Label |
+|---|---|
+| positive `lifetime.cum_realized_pnl` AND window `profit_factor` above 1.5 AND 50+ closed trades AND positive median gain | **Consistent** |
+| big PnL, `win_rate` near 0.5, mean far above median | **Few large winners** (size matters more than hit rate) |
+| high win rate on fewer than 10 closed trades | **Unverified** |
+| `net_deposit_usd` much larger than `cum_realized_pnl` | **Equity driven by deposits**, not trading |
+| realized PnL positive but `total_unrealized_pnl` very negative on a large open book | **Open risk** |
+
+## Anti-patterns
+
+- Don't call a wallet "the best trader" from a 1d or 7d window, or from one number.
+- Don't give copy-trade advice. The record is past, one venue, labels as of today.
+- Don't read a `null` drawdown as 0.
+
+## Pairs well with
+
+- `vike-hl-top-traders` (rankings), `vike-hl-position-match` (find the wallet), `vike-wallet-who-is` (on-chain identity)
+- `vike-hl-cohort-positioning` for how that cohort is positioned

package/skills/vike-perp-crowding/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: vike-perp-crowding
+description: Is a perpetual-futures symbol crowded one way - funding paid, open interest net of the price move and the long/short lean on each venue, compared with the symbol's own last week, plus the Hyperliquid funding history and wallet-cohort lean. Use when the user asks "is BTC long crowded" / "is ETH positioning stretched across exchanges" / "is open interest rising with price" / "are traders over-leveraged long on SOL".
+allowed-tools: Bash(vike-data:*)
+---
+
+# vike-perp-crowding
+
+Three lenses on one symbol, about 6 credits. No lens has a validated threshold: judge each against the symbol's OWN last week and report what agrees, never a score. Base asset only (`BTC`, not `BTCUSDT`). Open interest and long/short have no command of their own: they are `vike-data call`.
+
+## Chain
+
+```bash
+S=BTC
+vike-data perp funding --symbol $S --json                                   # funding on every venue now
+vike-data hl market --view hourly --symbols $S --days 7 --json              # Hyperliquid funding, open interest and close per hour
+vike-data call perp_open_interest --args '{"symbol":"BTC","hours":168}'     # hourly oi_usd per venue
+vike-data call perp_long_short --args '{"symbol":"BTC","hours":168}'        # hourly long_short_ratio per venue, with `basis`
+vike-data candles hl $S --interval 1h --limit 169 --json                    # price over the same hours, to net it out of OI
+vike-data hl cohort-metrics $S --axis size --hours 1 --json                 # optional: whales on Hyperliquid
+```
+
+Without `hours` both `call`s return the newest print per venue; `"exchange":"binance"` narrows to one venue.
+
+## Lens 1: funding
+
+Raw `funding_rate` is per interval and `interval_h` differs (Hyperliquid 1h, most CEXs 8h): `daily_pct = funding_rate x 24 / interval_h x 100`. Positive = longs pay. `perp funding` is a snapshot, so for the CEXs say "above/below the other venues"; Hyperliquid's own funding history is in the hourly panel, so judge it against its week.
+
+## Lens 2: open interest net of price
+
+`oi_usd` is USD notional = contracts x mark price, so it rises with price on its own. Over the same hours: `contracts_change% ~ oi_change% - price_change%`. OI rising faster than price = new positions; falling while price rises = positions closing. Venues in `stale_venues` are not in `venues` and never in a total. The series is `[hour, oi_usd]` pairs, `hours + 1` points, the first hour partial.
+
+## Lens 3: who leans
+
+`long_share` / `short_share` are fractions of 1; `long_short_ratio` = long / short, above 1 long-heavy. **Each venue counts something different** and the row says so in `basis`: binance = top traders by positions, okx and gate = top traders by accounts, bybit = all accounts. Never average across venues; compare each venue with its own 7-day range. About 40 major symbols per venue; other symbols return empty lists and a `note`, not zeros. Hyperliquid cohorts (`bias` -1..+1 of notional, sum rungs by notional) are wallets, not accounts counted by a venue.
+
+## Verdict
+
+State which lenses point the same way and which do not. Illustrative wording, not live data: "funding positive on most venues, contracts rising on binance but falling on hyperliquid, long ratio at its 7-day high on binance only: mixed, not crowded". Name "crowded long" only when funding, net OI and at least two bases agree and sit at the top of their own week.
+
+## Anti-patterns
+
+- Don't read `oi_usd` growth as new longs, or a long/short ratio as dollars.
+- Don't average ratios across venues or compare bases; don't forecast a squeeze.
+- Don't leave stale venues in the comparison.
+
+## Pairs well with
+
+- `vike-perp-funding`, `vike-perp-overview`, `vike-hl-cohort-positioning`, `vike-hl-asset-briefing`, `vike-candles`

package/skills/vike-perp-funding/SKILL.md

@@ -75,8 +75,11 @@ A funding arb at 0.4–1% daily is real. Anything much higher on a liquid pair i
 - Don't blindly pick the lowest-funding venue without checking `vol_24h_usd` — Hyperliquid funding looks great on small alts but the book can be thin.
 - Don't read `funding_rate` of an 8h venue against a 1h venue without normalising.
 - Don't promise a price comparison from this tool: for price gaps across venues use `vike-perp-overview` (`perp spreads`).
+- The arb list often leads with thin tokens: run mode B and read `vol_24h_usd` on both legs before calling a row a trade.
+- Funding is the cost of carrying a position, not how crowded it is: for open interest and long/short per venue see `vike-perp-overview`, and `vike-perp-crowding` for the combined read.
 
 ## Pairs well with
 
-- `vike-perp-overview` for cross-venue price gaps and the market snapshot
+- `vike-perp-overview` for cross-venue price gaps, open interest, long/short and the market snapshot
+- `vike-perp-crowding` to put a funding number next to open interest and positioning; `vike-hl-asset-briefing` for one Hyperliquid symbol
 - `vike-hl-top-traders` to see how Hyperliquid's best traders are doing

package/skills/vike-perp-overview/SKILL.md

@@ -1,12 +1,30 @@
 ---
 name: vike-perp-overview
-description: Perp-market snapshot and cross-venue price spreads — the top funding arbs, the widest perp price gaps between venues, and the Hyperliquid leaderboard in one read. Use when the user asks "what's happening in perps today" / "perp market overview" / "any perp arb today" / "price differences across exchanges" / "where's X cheapest".
+description: Perp-market snapshot and the venue-level reads of one symbol — the top funding arbs, the widest perp price gaps between venues, the Hyperliquid leaderboard, open interest per venue and each venue's long/short lean. Use when the user asks "what's happening in perps today" / "perp market overview" / "any perp arb today" / "price differences across exchanges" / "where's X cheapest" / "open interest of X" / "long short ratio of X".
 allowed-tools: Bash(vike-data:*)
 ---
 
 # vike-perp-overview
 
-One-shot market overview for perpetuals, plus the cross-venue price-gap tool. The overview is exactly what these three tools return: funding arbs, price gaps and the HL leaderboard. There is **no CEX open-interest, market-wide volume or per-venue mark-price command** in the CLI; say so if asked (Hyperliquid open interest is `vike-data hl market --json`).
+One-shot market overview for perpetuals, plus the cross-venue price-gap, open-interest and long/short tools. There is **no market-wide volume or per-venue mark-price tool**; say so if asked (Hyperliquid's own open interest is `vike-data hl market --json`).
+
+## Open interest and long/short (one symbol, per venue)
+
+These two tools have no command of their own; `vike-data call` prints their raw JSON (1 credit each):
+
+```bash
+vike-data call perp_open_interest --args '{"symbol":"BTC"}'                                # newest print per venue
+vike-data call perp_open_interest --args '{"symbol":"BTC","exchange":"binance","hours":48}' # hourly series, 1-168
+vike-data call perp_long_short --args '{"symbol":"ETH"}'
+vike-data call perp_long_short --args '{"symbol":"ETH","exchange":"okx","hours":24}'
+```
+
+Pass the base asset (`BTC`, not `BTCUSDT`); `exchange` is lower case.
+
+- **`oi_usd` is USD notional** (open contracts x mark price when polled): not a contract count, so venues add up, and it moves with price even when no position opens or closes. Venues: aster, binance, bitget, bybit, hyperliquid, kucoin, okx. A venue silent for over an hour is under `stale_venues` and NOT in `venues`: never add it into a total.
+- **`long_share` / `short_share` are fractions of 1**; `long_short_ratio` = long / short, above 1 = long-heavy. **Each venue counts something different, named in the row's `basis`**: binance top traders by positions; okx and gate top traders by accounts; bybit all accounts. Never average across venues; compare a venue with its own history.
+- About 40 major symbols per venue: any other symbol returns empty lists and a `note`, never zeros.
+- Whether a symbol is crowded: `vike-perp-crowding`.
 
 ## Price spreads
 
@@ -52,7 +70,7 @@ wait
 ## When to skip the 3-call snapshot
 
 - User asked about one symbol's funding or venues → `vike-perp-funding`.
-- User asked about one HL trader → `vike-hl-top-traders`.
+- User asked about one HL trader → `vike-hl-trader-profile` (or `vike-hl-top-traders` for a ranking).
 - User only wants price gaps → run `perp spreads` alone.
 
 ## Anti-patterns
@@ -66,4 +84,6 @@ wait
 ## Pairs well with
 
 - `vike-perp-funding` for the funding deep dive and one-symbol venue comparison
+- `vike-perp-crowding` for funding + open interest net of price + long/short on one symbol
 - `vike-hl-top-traders` for the leaderboard filters and how to read its columns
+- `vike-daily-brief` for the perp section inside a cross-market brief

package/skills/vike-pm-l2-archive/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: vike-pm-l2-archive
+description: Find and fetch the free Polymarket L2 archive - daily Parquet files of the full order-book events, the trade tape and top-of-book quotes, whole or cut per market family such as BTC 5-minute up/down - with their sizes, a 7-day download link, and the on-chain outcomes to join them to. Says when the API tape is enough instead. Use when the user asks "get me Polymarket order book history" / "BTC 5m up/down L2 data for last week" / "download the Polymarket trades for a day" / "data to backtest a Polymarket strategy".
+allowed-tools: Bash(vike-data:*)
+---
+
+# vike-pm-l2-archive
+
+The archive is one Parquet file per UTC day and stream, recorded since 2026-07-25, free under CC BY 4.0 (credit "Polymarket L2 archive (c) Vike (vike.io/data), CC BY 4.0"). `vike-data` lists files and resolves links; **it never downloads.** 1 credit per call.
+
+## Chain
+
+```bash
+vike-data polymarket archive --view datasets --asset btc --tenor 5m --stream trades --date-from 2026-10-15 --date-to 2026-10-17 --json
+vike-data polymarket archive --view url --stream trades --date 2026-10-16 --json                         # multi-asset file, one day
+vike-data polymarket archive --view url --stream trades --asset btc --tenor 5m --date 2026-10-16 --json  # family file
+vike-data polymarket settlements --slug-prefix btc-updown-5m- --from-ms <start> --to-ms <end> --limit 1000 --json   # how each market resolved
+```
+
+Streams: `book_events` (full L2: snapshots, `price_change` deltas, trades, tick-size and status markers), `trades` (taker tape), `l1_quotes` (derived top of book). A row carries `date`, `stream`, `layout` (`flat` = every market, `family` = one asset and tenor), `bytes`, `rows`, `url`. `datasets` pages with `--limit` (max 1000) and `--offset` against `total`.
+
+## Pick the right file
+
+- `--asset` and `--tenor` go together or not at all, and either one hides every flat file. Without them `datasets` mixes both layouts: filter on `layout`, or the same day appears twice.
+- **Check `bytes` first.** Measured 2026-10-19: one day of `trades` about 12 MB; a BTC 5m family `trades` day 3-5 MB; one day of `book_events` **8.5 GB (532 million rows)**. Tell the user before any `book_events` download, and prefer the family file for one asset.
+- A few hours or one token: use the API, not a bulk file: `vike-data polymarket tape --token-id <id> --from-ms ... --to-ms ... --event-type trade` (at most 24 h a call, no wallets), `vike-data polymarket market-trades <condition_id>` (with wallets) or `vike-data candles polymarket <token_id>`.
+
+## Fetch (outside this skill's tool grant; hand the user the command)
+
+```bash
+curl -C - -o trades-2026-10-16.parquet "<url from the row>"
+```
+
+The link needs no API key and is valid for 7 days (`expires_at`): treat it as a secret, don't paste it anywhere shared. **Download the file whole and read the local copy** with DuckDB, polars or pyarrow: pointing a reader at the URL turns one file into thousands of range requests. The manifest and a small sample need no key at all: `https://data.vike.io/archive/manifest.json`, `https://data.vike.io/archive/samples/`.
+
+## Reading the files
+
+- The L2 tape carries no wallet addresses, only size and time. Prices are probabilities, sizes are shares.
+- On the API tape a `0` in `best_bid`, `best_ask`, `price` or `size` on a row type that does not populate it means absent, not zero; check the schema in the manifest before assuming the same of a Parquet column.
+- Join across files on the outcome token id; `settlements` rows carry `token_ids` and `winning_token_id` for the join to outcomes.
+
+## Anti-patterns
+
+- Don't promise a download from the CLI, and don't fetch `book_events` days to answer a question the API tape can.
+- Don't redistribute without the attribution above.
+
+## Pairs well with
+
+- `vike-pm-market-diligence` (ids and one market live), `vike-candles` (probability bars), `vike-polymarket-markets`
+- The Hyperliquid twin: `vike-data hl archive --view url --dataset fills --date 2026-10-16` (daily fills and positions files)