@vike-io/cli 0.7.3 → 0.8.1

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes are documented here. Entries follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## 0.8.0 — HL share-card reverse-lookup + multi-IDE installer + SKILL.md hardening
+
+- **`vike perp find-position`** (new command, alias for the new `hl_position_match` MCP tool). Reverse-lookup a Hyperliquid open position from share-card details: paste `coin + side + leverage + entry` and get the wallet(s) holding a matching open position back. Walks widening entry tolerance bands (tight 0.05% → loose 0.5% → fallback 1.0%) with leverage tolerance ±0.5; tie-break by closest mark price. Returns `tolerance_used` so callers can flag low-confidence matches. Backed by `position_snapshots_latest` — near-real-time, no new schema.
+- **`vike install`** (new command). One-shot multi-IDE skill drop: `--claude` writes `~/.claude/skills/vike/SKILL.md`; `--cursor` / `--copilot` / `--agents` update marker-fenced blocks in `.cursorrules` / `.github/copilot-instructions.md` / `AGENTS.md` (idempotent — re-running replaces the block, never clobbers surrounding user content). `--all` writes every target at once.
+- **Root `SKILL.md` hardening**: added a "Critical Rules" block (8 hard rules agents most often violate), per-service "Historical Data Availability" tables (transfers per chain, prices per venue, HL perps, CEX perps, Polymarket — so agents stop over-promising data we don't have), and UTM-tagged signup links for attribution.
+- New skill playbook: `vike-hl-position-match`. Total: 40 skills (was 39), 35 MCP tools (was 34).
+
 ## 0.7.3 — agent-discoverable SKILL.md + auto GH releases
 
 - **Root-level `SKILL.md`** — single agent-discoverable entry point covering all 34 MCP tools, auth flow, intent → tool routing table, and per-service tool reference. Ships in the npm package so installing `@vike-io/cli` also installs the skill. Existing per-tool playbooks under `skills/` are unchanged and cross-linked from the root.

package/README.md

@@ -5,13 +5,26 @@
 [![npm version](https://img.shields.io/npm/v/@vike-io/cli.svg)](https://www.npmjs.com/package/@vike-io/cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
+[![skills.sh](https://skills.sh/b/vike-io/vike-cli)](https://skills.sh/vike-io/vike-cli)
 
 > **Command-line interface for the [vike.io](https://vike.io) API.** On-chain analytics, perpetuals, options flow, and prediction-market data across 11 chains — designed to be driven by AI agents (Claude Code, OpenClaw) as well as humans.
 
 ## Install
 
 ```bash
+# Standard install — gives you the `vike` binary
 npm install -g @vike-io/cli
+
+# OR install just the skill playbooks into your AI agent (Claude Code, Cursor,
+# Codex, Copilot, OpenCode and 50+ more — auto-detected):
+npx skills add vike-io/vike-cli
+```
+
+After `npm install`, you can also drop the skill into AI agents from the CLI itself:
+
+```bash
+vike install --all          # writes to ~/.claude/skills/vike/, .cursorrules,
+                            # .github/copilot-instructions.md, AGENTS.md
 ```
 
 ## Quick start
@@ -22,7 +35,7 @@ vike doctor                    # confirm everything works
 vike token search BTC          # your first query
 ```
 
-Get an API key at [vike.io/api/keys](https://vike.io/api/keys).
+Get an API key at [vike.io/account?tab=api-keys](https://vike.io/account?tab=api-keys).
 
 ## Commands at a glance
 
@@ -50,15 +63,24 @@ Run `vike schema --pretty` for the full command + flag reference.
 
 ## For AI agents
 
-This package ships **skill playbooks** under [`skills/`](skills/) — markdown files designed to be loaded by AI coding agents (Claude Code, OpenClaw, Cursor) so they know when and how to invoke each command.
+This package ships **41 skill playbooks** under [`skills/`](skills/) — markdown files designed to be loaded by AI coding agents (Claude Code, Cursor, Codex, Copilot, OpenCode, …) so they know when and how to invoke each command. They are grouped in [`skills.sh.json`](skills.sh.json) by domain (Tokens / Wallets / CEX perps / Hyperliquid / Options / Polymarket / Alerts / Web research).
 
-Skill entry points:
-- `vike-core` — install + auth + conventions (read first)
-- `vike-router` — decide which skill applies
-- `vike-token-research`, `vike-smart-money-discovery`, `vike-perp-funding-arb`, `vike-perp-screener`, `vike-hl-top-traders`, `vike-hl-trader-profile`, `vike-cross-venue-perps`, `vike-options-flow`, `vike-alerts-setup` — task playbooks
-- Per-tool skills for each command
+Three install paths, pick whichever fits your stack:
+
+```bash
+# 1. Install just the skill files for your agent (no Node binary needed):
+npx skills add vike-io/vike-cli                # auto-detects the agent
+npx skills add vike-io/vike-cli -a claude-code # explicit target
+npx skills add vike-io/vike-cli --list          # list all 41 first
+
+# 2. Use the CLI itself to install the umbrella skill into multiple agents:
+vike install --claude --cursor --copilot --agents
+
+# 3. Manual: point your agent at the skills/ folder of this npm package
+#    (lives at node_modules/@vike-io/cli/skills/ after install).
+```
 
-In Claude Code, the bundled skills are auto-discovered after `npm install -g @vike-io/cli`. In other harnesses, point the agent at the `skills/` folder of this package.
+Entry-point skill: `vike` (the umbrella) — auto-routes the user's question to the right specialized skill below. Bypass it and pick a specialized one if you know exactly which you need (e.g. `vike-hl-position-match` for reverse-lookup of an HL share card).
 
 ## Auth
 

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.7.3",
+  "version": "0.8.1",
   "description": "AI-agent CLI for vike.io on-chain analytics, perps, options, and prediction markets across 11 chains",
   "type": "module",
   "main": "src/index.js",
@@ -14,7 +14,7 @@
     "src/**/*.js",
     "scripts/postinstall.js",
     "skills/**",
-    "SKILL.md",
+    "skills.sh.json",
     "CHANGELOG.md"
   ],
   "scripts": {

package/{SKILL.md → skills/vike/SKILL.md}

@@ -12,6 +12,21 @@ Answer on-chain questions using the vike.io platform: 11 chains (ETH, BSC, Base,
 
 ---
 
+## Critical Rules
+
+Hard rules — agents that violate these produce wrong answers. Read once, apply always.
+
+1. **Addresses are always full 0x-hex (42 chars).** Never truncate when querying. Never display truncated when the user asks for the address — they'll copy-paste it.
+2. **Symbols are case-insensitive in queries, but display as the user typed.** `btc` and `BTC` both resolve; echo back what they wrote.
+3. **Time windows are UTC, day-boundaries cut at 00:00 UTC.** "Today" = since 00:00 UTC today, not local-time today.
+4. **Default page size is 50, max 500.** Don't request `--limit 10000` to "get everything" — paginate or use a screener tool instead.
+5. **Refresh cadence varies by tool.** Wallet PnL, HL positions: ≤2 min. Transfer-derived metrics: 5 min. Token price history: 1 min. Always assume <5 min unless a tool says otherwise.
+6. **USD amounts are floats in dollars.** `--min-usd 10000` = ten thousand dollars, not micro-USD.
+7. **`--json` flag is always available** on CLI commands and gives stable machine-readable output. Default (human) format may change; `--json` will not.
+8. **Resolve a token before asking transfer/holder questions.** `token_search` → take the canonical address → pass to `token_transfers` / `token_holders`. Symbol-only queries lose precision on tickers that collide across chains (e.g. FUN, BEAM, USDC).
+
+---
+
 ## Step 1: Confirm Authentication
 
 Follow this decision tree **before every session**. Do not skip to Step 2 until auth is confirmed.
@@ -32,7 +47,7 @@ If the user has no API key yet, tell them:
 
 > **To use vike, you'll need a free API key:**
 >
-> 1. Visit https://vike.io/api/keys, sign in, and copy a key (starts with `vk_`).
+> 1. Visit https://vike.io/account?tab=api-keys&utm_source=skill&utm_medium=ai&utm_campaign=cli_skill, sign in, and copy a key (starts with `vk_`).
 > 2. Save it: `vike login --api-key vk_...` (or `export VIKE_API_KEY=vk_...`).
 > 3. Verify: `vike doctor`.
 >
@@ -68,6 +83,7 @@ X-API-KEY: vk_...
 | Funding rates across CEX perps (Binance/Bybit/OKX/Aster/HL) | **CEX Perps** | `vike perp funding` / `perp_funding` |
 | Price spreads of same symbol across CEX perp venues | **CEX Perps** | `vike perp spreads` / `perp_spreads` |
 | Top Hyperliquid perp traders by PnL / volume | **HL Perps** | `vike perp top-traders` / `hl_perp_top_traders` |
+| Reverse-lookup an HL share card → which wallet holds it | **HL Perps** | `vike perp find-position` / `hl_position_match` |
 | Deribit options flow, put/call ratios, IV | **Options** | `vike options flow` / `options_flow` |
 | Active Polymarket markets, volume, odds | **Polymarket** | `vike polymarket markets` / `polymarket_markets` |
 | Single Polymarket market detail | **Polymarket** | `vike polymarket detail` / `polymarket_market_detail` |
@@ -195,6 +211,7 @@ On-chain perps data: snapshots, fills, ledger, funding, attribution.
 | Tool | Description | Skill |
 |---|---|---|
 | `hl_perp_top_traders` | Top HL traders by PnL/volume over a window | [vike-hl-top-traders](skills/vike-hl-top-traders/SKILL.md), [vike-hl-trader-profile](skills/vike-hl-trader-profile/SKILL.md) |
+| `hl_position_match` | Reverse-lookup: share-card details (coin/side/lev/entry) → wallet holding that open position | [vike-hl-position-match](skills/vike-hl-position-match/SKILL.md) |
 
 For per-symbol HL screening / individual trader deep-dive, use [vike-perp-screener](skills/vike-perp-screener/SKILL.md) and [vike-hl-trader-profile](skills/vike-hl-trader-profile/SKILL.md).
 
@@ -260,6 +277,67 @@ General web search + AI-summarized fetch for off-chain context (news, docs, soci
 
 ---
 
+## Historical data availability
+
+Coverage windows per dataset. Don't ask for data older than the window — the tool will return empty or 503.
+
+### Transfers & on-chain (per chain)
+
+| Chain | Earliest block / date | Notes |
+|---|---|---|
+| Ethereum | 2018-01 (block ~4.85M) | Full history; ETH + ERC-20 |
+| BSC | 2021-01 | Full history; BNB + BEP-20 |
+| Base | 2023-08 (chain launch) | Full history |
+| Arbitrum | 2024-Q3 onward | Backfill in progress; pre-2024 sparse |
+| HyperEVM | 2025-Q1 (chain launch) | Full history |
+| Bitcoin | 2024-01 | Recent windows only — full-history backfill not active |
+| Solana | 2026-Q1 onward | Recent only — see `vike-cli` chain-coverage notes |
+| Tron/XMR/ZEC/Dash | 2024 onward | Recent only |
+
+### Prices (data_history, spot)
+
+| Venue | Earliest | Notes |
+|---|---|---|
+| Binance | 2017-08 | Full minute-level OHLCV |
+| Bybit | 2020-03 | Full minute-level OHLCV |
+| OKX | 2019-04 | Full minute-level OHLCV |
+| Gate | 2017 (CSV) → 2024-05 (CSV ends) | After 2024-05 use API; capped 10k minutes/request |
+| Coinbase | 2015 | Full history (recently added) |
+| KuCoin | 2018 | Full history (recently added) |
+| Pyth | 2023 | On-chain price feed; sparse pre-2023 |
+| Deribit options | 2020 onward | BTC + ETH only |
+
+### Hyperliquid perps (hl_perps DB)
+
+| Dataset | Window | Notes |
+|---|---|---|
+| Snapshots (positions / equity) | 30 days | TTL — older snapshots dropped |
+| Fills | 30 days | TTL |
+| Ledger (deposits/withdrawals) | 30 days | TTL |
+| Funding payments | 90 days | API-backed since 2026-04-22 |
+| Daily attributed PnL | All-time | `wallet_pnl_attributed_daily` is the long-history view |
+| Daily flows | All-time | `wallet_flows_daily` |
+| Top-trader leaderboards | rolling 24h / 7d / 30d | derived on-the-fly |
+
+### CEX perps (data_perp DB)
+
+| Dataset | Window |
+|---|---|
+| `tickers_1m` (ticker snapshots) | rolling 24h |
+| Funding rates | 90 days |
+| Trades (ws_trades) | rolling 7-30 days per venue |
+
+### Polymarket
+
+| Dataset | Window | Notes |
+|---|---|---|
+| Active markets | live | scraper paused 2026-05-24 (CF block); historical snapshots still queryable |
+| Wallet positions | last known snapshot | not real-time until scraper resumes |
+
+If your query needs older data than what's listed: say so clearly and offer the nearest in-range window. Don't silently return empty.
+
+---
+
 ## Cost & rate-limit awareness
 
 - **Cheap (counts as 1 credit):** `token_search`, `wallet_summary`, `alerts_list`, `wallet_ens`, `perp_funding`.

package/skills/vike-core/SKILL.md

@@ -32,7 +32,7 @@ vike login --api-key vk_...        # non-interactive
 export VIKE_API_KEY=vk_...         # env (wins over saved config)
 ```
 
-Get an API key at https://vike.io/api/keys
+Get an API key at https://vike.io/account?tab=api-keys
 
 ## Verify
 

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

@@ -0,0 +1,86 @@
+---
+name: vike-hl-position-match
+description: Reverse-lookup a Hyperliquid open position from share-card details (coin + side + leverage + entry price). Use when the user pastes or describes a HL share card and asks "whose card is this?", "find this trader", or "who has a 25x ETH long open at $3,200?". Returns matching wallet(s) ranked by entry-price proximity.
+allowed-tools: Bash(vike:*)
+---
+
+# vike-hl-position-match
+
+Find the wallet(s) holding an open Hyperliquid perp position that match a share card.
+
+## Command
+
+```bash
+vike perp find-position
+  --coin <SYM>         # e.g. BTC, ETH, SOL
+  --side long|short
+  --leverage <X>       # e.g. 25
+  --entry <PRICE>      # entry price from the card
+  [--mark <PRICE>]     # current mark price — sharpens tie-break when multiple wallets share entry
+  [--limit N]          # max matches, default 10, max 50
+  [--json]
+```
+
+## How matching works
+
+The tool walks three widening entry-price tolerance bands until it finds at least one match:
+
+| Band | Tolerance | When it's used |
+|---|---|---|
+| tight | ±0.05% | First pass — most share cards round-trip exactly |
+| loose | ±0.5% | Fallback if no tight matches |
+| fallback | ±1.0% | Last resort — anything wider is noise |
+
+Leverage must be within **±0.5** of the queried value (so `--leverage 5` matches positions at 4.5×–5.5×). Tie-breaking inside a band is by closest live `mark_price` to the queried `--mark` (or to `--entry` if `--mark` is not given).
+
+The response includes `tolerance_used` so the caller knows which band matched (`tight` / `loose` / `fallback` / `no_match`).
+
+## Common queries
+
+| User says | Flags |
+|---|---|
+| "Find this share card: 25x ETH long, entry $3,210" | `--coin ETH --side long --leverage 25 --entry 3210` |
+| "Whose 10x BTC short is open at $58,400? Current mark $57,900" | `--coin BTC --side short --leverage 10 --entry 58400 --mark 57900` |
+| "Top 5 matches for 50x SOL long around $145" | `--coin SOL --side long --leverage 50 --entry 145 --limit 5` |
+
+## Output schema
+
+```jsonc
+{
+  "match_count": 3,
+  "tolerance_used": "tight",          // tight | loose | fallback | no_match
+  "query": { "coin": "ETH", "side": "long", "leverage": 25, "entry_price": 3210, "mark_price_hint": 3215 },
+  "matches": [
+    {
+      "address": "0x...",
+      "coin": "ETH", "side": "long",
+      "snapshot_ts": 1716700000,       // unix seconds — how fresh the snapshot is
+      "size_token": 12.5, "size_usd": 40250,
+      "entry_price": 3209.8, "mark_price": 3215.3,
+      "leverage": 25.0,
+      "liquidation_price": 3082.1,
+      "unrealized_pnl": 68.75,
+      "entry_dist_pct": 0.0062         // |query.entry - match.entry| / query.entry × 100
+    }
+  ]
+}
+```
+
+## Reading the result
+
+- **Multiple matches at the exact same entry** (e.g. five wallets long ETH at 3210.00) — popular round-number entries collide. Treat as ambiguous; surface all and let the user disambiguate by size or address. Don't claim "this is the wallet" when `match_count > 1` in the tight band.
+- **`tolerance_used: fallback`** — the closest match is >0.5% off the queried entry. The card might be from a previous fill that's since been added to (size-weighted entry moves on add) or from a different exchange. Treat as low-confidence.
+- **`tolerance_used: no_match`** — the position is closed, the entry was from a margin-changing event, or the wallet was outside our HL coverage. Don't suggest a wallet anyway.
+- **`snapshot_ts`** is the snapshot time of that position row. The pipeline refreshes <5 min behind live; older `snapshot_ts` doesn't mean the position is stale, just that the wallet hasn't transacted since.
+
+## Anti-patterns
+
+- 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 perp top-traders` or `vike wallet summary` for profile context.
+
+## Pairs well with
+
+- [vike-wallet-summary](../vike-wallet-summary/SKILL.md) — once you have the address, get the trader's HL profile + multi-chain identity.
+- [vike-hl-top-traders](../vike-hl-top-traders/SKILL.md) — check if the matched wallet is on a leaderboard.
+- [vike-wallet-label-provenance](../vike-wallet-label-provenance/SKILL.md) — find out if the wallet is a known CEX/fund/MM rather than a retail trader.

package/skills/vike-router/SKILL.md

@@ -22,6 +22,7 @@ Route the user's question to the right `vike-*` skill.
 | Perp funding rates / arb opportunities | `vike-perp-funding-arb` |
 | Cross-venue perp price spreads | `vike-perp-spread-arb` |
 | Top Hyperliquid perp traders | `vike-hl-top-traders` |
+| Match an HL share card → wallet (reverse-lookup) | `vike-hl-position-match` |
 | Profile a single HL perp trader | `vike-hl-trader-profile` |
 | HL market overview (vol/OI/funding) | `vike-perp-screener` |
 | Compare a symbol across all perp venues | `vike-cross-venue-perps` |

package/skills/vike-wallet-trace/SKILL.md

@@ -68,6 +68,16 @@ Tool credits = 4 per call (heavier than other graph-less tools). Graph explodes
 - Don't depth-5 by default. Graph blows up; results become noise.
 - Don't ignore `min_usd` — without it, dust transfers create false-positive edges.
 
+## Visual graph (web UI)
+
+When the user wants to *see* the network rather than read JSON, surface the URL:
+
+```
+https://vike.io/spot/wallet/<address>
+```
+
+Tell them to click the **Graph** tab. It renders the same trace data as a force-directed graph (nodes coloured by hop depth, sized by USD volume, animated directional particles on edges). Clicking any non-root node navigates to that wallet's graph. Use this in chat replies when the user says "show me", "visualize", or pastes a wallet address asking for an exploration view — JSON is for downstream pipelines, the URL is for humans.
+
 ## Pairs well with
 
 - `vike labels <addr>` — identify any interesting node

package/skills.sh.json

@@ -0,0 +1,101 @@
+{
+  "$schema": "https://skills.sh/schemas/skills.sh.schema.json",
+  "notGrouped": "bottom",
+  "groupings": [
+    {
+      "title": "Quick start",
+      "description": "Start here. The umbrella skill auto-routes user questions to the right specialized skill below.",
+      "skills": [
+        "vike",
+        "vike-router",
+        "vike-core"
+      ]
+    },
+    {
+      "title": "Tokens",
+      "description": "Resolve, screen, and research tokens across 11 chains. Smart-money inflow, holders, recent transfers, OHLCV.",
+      "skills": [
+        "vike-token-search",
+        "vike-token-research",
+        "vike-token-transfers",
+        "vike-token-holders",
+        "vike-token-screener",
+        "vike-smart-money-discovery"
+      ]
+    },
+    {
+      "title": "Wallets",
+      "description": "Per-wallet profile, PnL, counterparty graphs, ENS, batch labelling, fund affiliation, DeFi positions.",
+      "skills": [
+        "vike-wallet-summary",
+        "vike-wallet-portfolio",
+        "vike-wallet-discover",
+        "vike-wallet-transactions",
+        "vike-wallet-counterparties",
+        "vike-wallet-trace",
+        "vike-wallet-compare",
+        "vike-wallet-batch",
+        "vike-wallet-pnl-history",
+        "vike-wallet-balances",
+        "vike-wallet-ens",
+        "vike-wallet-label-provenance",
+        "vike-fund-holdings",
+        "vike-defi-positions"
+      ]
+    },
+    {
+      "title": "CEX perps",
+      "description": "Funding-rate arb + cross-venue mark-price spreads across Binance, Bybit, OKX, Aster, Hyperliquid.",
+      "skills": [
+        "vike-perp-funding-arb",
+        "vike-perp-spread-arb",
+        "vike-perp-screener",
+        "vike-cross-venue-perps"
+      ]
+    },
+    {
+      "title": "Hyperliquid perps",
+      "description": "Deep on-chain HL coverage: top traders, full trader profiles, and share-card reverse-lookup.",
+      "skills": [
+        "vike-hl-top-traders",
+        "vike-hl-trader-profile",
+        "vike-hl-position-match"
+      ]
+    },
+    {
+      "title": "Options",
+      "description": "Deribit BTC/ETH options flow + put-call ratios.",
+      "skills": [
+        "vike-options-flow"
+      ]
+    },
+    {
+      "title": "Polymarket",
+      "description": "Prediction-market discovery, single-market deep-dives, trader profiles, and smart-money leaderboards.",
+      "skills": [
+        "vike-polymarket-markets",
+        "vike-polymarket-market-detail",
+        "vike-polymarket-trader",
+        "vike-polymarket-smart-money",
+        "vike-polymarket-screener"
+      ]
+    },
+    {
+      "title": "Alerts",
+      "description": "Create, list, edit, delete price + flow alerts; register HTTPS webhooks with HMAC delivery.",
+      "skills": [
+        "vike-alerts-setup",
+        "vike-alerts-webhook"
+      ]
+    },
+    {
+      "title": "Web research",
+      "description": "Off-chain context: general web search and AI-summarized URL fetch for news, docs, and social.",
+      "skills": [
+        "vike-web-search",
+        "vike-web-fetch",
+        "vike-web-research"
+      ]
+    }
+  ]
+}

package/src/auth.js

@@ -48,7 +48,7 @@ export function requireApiKey() {
   if (!key) {
     throw new Error(
       'No API key. Run `vike login --api-key <key>` or set VIKE_API_KEY. ' +
-      'Get a key at https://vike.io/api/keys',
+      'Get a key at https://vike.io/account?tab=api-keys',
     );
   }
   return key;

package/src/commands/auth.js

@@ -8,7 +8,7 @@ export function registerLogin(program) {
     .option('--api-key <key>', 'API key (vk_...)')
     .action(async (opts) => {
       if (!opts.apiKey) {
-        console.error('Pass --api-key <vk_...>. Get a key at https://vike.io/api/keys');
+        console.error('Pass --api-key <vk_...>. Get a key at https://vike.io/account?tab=api-keys');
         process.exitCode = 1;
         return;
       }

package/src/commands/init.js

@@ -15,7 +15,7 @@ export function registerInit(program) {
       if (!key) {
         const rl = createInterface({ input: stdin, output: stdout });
         try {
-          console.log('Get your API key at https://vike.io/api/keys');
+          console.log('Get your API key at https://vike.io/account?tab=api-keys');
           key = (await rl.question('Paste your API key (vk_...): ')).trim();
         } finally {
           rl.close();

package/src/commands/install.js

@@ -0,0 +1,128 @@
+// `vike install` — copy SKILL.md into the agent-discoverable locations for
+// supported IDEs/agents so the skill loads without the user having to wire
+// it up manually.
+//
+// Targets:
+//   --claude    → ~/.claude/skills/vike/SKILL.md
+//   --cursor    → ./.cursorrules           (project root, joined under "## vike skill" header)
+//   --copilot   → ./.github/copilot-instructions.md  (same join pattern)
+//   --agents    → ./AGENTS.md              (same join pattern, project-root convention)
+//   --all       → all of the above
+//
+// Behaviour: idempotent. For files we don't own (project-root markdown), we
+// detect a fenced "<!-- vike-skill:begin -->...<!-- vike-skill:end -->" block
+// and replace just that block — never clobber the rest of the user's file.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const BEGIN = '<!-- vike-skill:begin -->';
+const END = '<!-- vike-skill:end -->';
+
+function readSkillSource() {
+  // Umbrella SKILL.md lives at skills/vike/SKILL.md (moved from the repo
+  // root so the skills-CLI auto-discovers all 40 nested skills instead of
+  // stopping at the root one). Fallback to the old root path keeps older
+  // installs working until they upgrade.
+  const here = fileURLToPath(import.meta.url);
+  const root = resolve(dirname(here), '..', '..');
+  for (const rel of ['skills/vike/SKILL.md', 'SKILL.md']) {
+    const candidate = resolve(root, rel);
+    if (existsSync(candidate)) return readFileSync(candidate, 'utf8');
+  }
+  throw new Error(`SKILL.md not found under ${root}. Reinstall @vike-io/cli.`);
+}
+
+function writeStandalone(path, skill) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, skill, { mode: 0o644 });
+  return { path, mode: 'replaced' };
+}
+
+function upsertBlock(path, skill, header) {
+  const wrapped = `${BEGIN}\n${header ? header + '\n\n' : ''}${skill}\n${END}`;
+  if (!existsSync(path)) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, wrapped + '\n', { mode: 0o644 });
+    return { path, mode: 'created' };
+  }
+  const current = readFileSync(path, 'utf8');
+  if (current.includes(BEGIN) && current.includes(END)) {
+    const before = current.slice(0, current.indexOf(BEGIN));
+    const after = current.slice(current.indexOf(END) + END.length);
+    writeFileSync(path, before + wrapped + after, { mode: 0o644 });
+    return { path, mode: 'updated' };
+  }
+  const sep = current.endsWith('\n') ? '\n' : '\n\n';
+  writeFileSync(path, current + sep + wrapped + '\n', { mode: 0o644 });
+  return { path, mode: 'appended' };
+}
+
+function installClaude(skill) {
+  return writeStandalone(join(homedir(), '.claude', 'skills', 'vike', 'SKILL.md'), skill);
+}
+function installCursor(skill, cwd) {
+  return upsertBlock(join(cwd, '.cursorrules'), skill, '# vike skill — on-chain analytics for AI agents');
+}
+function installCopilot(skill, cwd) {
+  return upsertBlock(
+    join(cwd, '.github', 'copilot-instructions.md'),
+    skill,
+    '# vike skill — on-chain analytics for AI agents'
+  );
+}
+function installAgents(skill, cwd) {
+  return upsertBlock(join(cwd, 'AGENTS.md'), skill, '# vike skill — on-chain analytics for AI agents');
+}
+
+export function registerInstall(program) {
+  program
+    .command('install')
+    .description('Copy vike SKILL.md into agent-discoverable locations (Claude, Cursor, Copilot, AGENTS.md)')
+    .option('--claude', 'Install to ~/.claude/skills/vike/SKILL.md')
+    .option('--cursor', 'Append/update vike block in ./.cursorrules')
+    .option('--copilot', 'Append/update vike block in ./.github/copilot-instructions.md')
+    .option('--agents', 'Append/update vike block in ./AGENTS.md')
+    .option('--all', 'Install to every supported target')
+    .option('--cwd <dir>', 'Project root (defaults to current directory)')
+    .action((opts) => {
+      const cwd = opts.cwd ? resolve(opts.cwd) : process.cwd();
+      const targets = opts.all
+        ? { claude: true, cursor: true, copilot: true, agents: true }
+        : opts;
+      if (!targets.claude && !targets.cursor && !targets.copilot && !targets.agents) {
+        console.error('No target selected. Use --claude / --cursor / --copilot / --agents / --all.');
+        console.error('Examples:');
+        console.error('  vike install --claude');
+        console.error('  vike install --all');
+        process.exitCode = 1;
+        return;
+      }
+      let skill;
+      try {
+        skill = readSkillSource();
+      } catch (e) {
+        console.error(`vike install: ${e.message}`);
+        process.exitCode = 1;
+        return;
+      }
+      const results = [];
+      try {
+        if (targets.claude) results.push(installClaude(skill));
+        if (targets.cursor) results.push(installCursor(skill, cwd));
+        if (targets.copilot) results.push(installCopilot(skill, cwd));
+        if (targets.agents) results.push(installAgents(skill, cwd));
+      } catch (e) {
+        console.error(`vike install: ${e.message}`);
+        process.exitCode = 1;
+        return;
+      }
+      for (const r of results) {
+        const size = (() => { try { return statSync(r.path).size; } catch { return 0; } })();
+        console.log(`${r.mode.padEnd(8)} ${r.path}  (${size} bytes)`);
+      }
+      console.log(`\nInstalled ${results.length} target(s). Restart your AI client to pick up the skill.`);
+    });
+}

package/src/commands/perp.js

@@ -31,6 +31,30 @@ export function registerPerp(program) {
       } catch (err) { emitError(err, opts); }
     });
 
+  cmd
+    .command('find-position')
+    .description('Reverse-lookup HL open positions matching a share-card (coin/side/lev/entry)')
+    .requiredOption('--coin <s>', 'Asset symbol (e.g. BTC, ETH)')
+    .requiredOption('--side <s>', 'long | short')
+    .requiredOption('--leverage <x>', 'Leverage from the share card (e.g. 25)')
+    .requiredOption('--entry <p>', 'Entry price from the share card')
+    .option('--mark <p>', 'Optional current mark price (sharpens tie-break)')
+    .option('--limit <n>', 'Max matches (default 10, max 50)', '10')
+    .option('--json', 'Emit JSON')
+    .action(async (opts) => {
+      try {
+        const r = await callTool('hl_position_match', {
+          coin: opts.coin,
+          side: opts.side,
+          leverage: Number(opts.leverage),
+          entry_price: Number(opts.entry),
+          mark_price: opts.mark != null ? Number(opts.mark) : undefined,
+          limit: parseInt10(opts.limit, 10),
+        });
+        emit(r, opts);
+      } catch (err) { emitError(err, opts); }
+    });
+
   cmd
     .command('top-traders')
     .description('Top Hyperliquid perp wallets by PnL / ROI / win rate / volume')

package/src/index.js

@@ -12,6 +12,7 @@ import { registerWeb } from './commands/web.js';
 // commands. New wallet subcommands (counterparties, pnl-history, balances,
 // ens) are added under registerWallet.
 import { registerInit } from './commands/init.js';
+import { registerInstall } from './commands/install.js';
 import { registerDoctor } from './commands/doctor.js';
 import { registerSchema } from './commands/schema.js';
 import { registerLogin, registerLogout } from './commands/auth.js';
@@ -55,6 +56,7 @@ program.hook('postAction', (_thisCmd, actionCmd) => {
 registerLogin(program);
 registerLogout(program);
 registerInit(program);
+registerInstall(program);
 registerDoctor(program);
 registerSchema(program);
 registerToken(program);