@oracle-agent/oracle 0.24.1 → 0.24.2

package/dist/assets/skills/oracle-mcp-install/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: oracle-mcp-install
+description: Use when installing Oracle as an MCP server in AI clients.
+---
+
+> Oracle native tools: `oracle_cli` (read/prepare), `vault_status`, `signer_status`, `signer_execute` (needs human confirmationNonce), `skill_load`. No generic shell. No fleet SSH.
+
+
+# Oracle MCP install
+
+## Quick start
+
+```bash
+oracle bootstrap
+oracle init --apply              # generates wallet, starts services
+oracle mcp install claude-code --with-soul
+```
+
+Public MCP is **data + prepare** only:
+
+| Server | Purpose |
+|---|---|
+| `oracle-data` | Read prices, quotes, routes, prepare unsigned tx |
+
+Signing stays on the user's machine (`oracle sign` / loopback signer). Do not wire a remote control/exec MCP from this public skill.
+
+`--with-soul` injects the Oracle SOUL.md as system instructions so Claude/Cursor/etc.
+think like Oracle — same routing logic, chain laws, safety gates.
+
+**Target-specific behavior:**
+
+| Target | Method | File written |
+|---|---|---|
+| `claude-code` | Prepends SOUL before existing CLAUDE.md | `./CLAUDE.md` |
+| `claude-desktop` | Prepends SOUL to customInstructions in config | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| `cursor` | Prepends SOUL before existing .cursorrules | `./.cursorrules` |
+| `vscode` | Writes SOUL to Copilot instructions | `./.vscode/instructions.md` |
+| `codex` / `copilot` | Writes SOUL to Copilot instructions | `./.github/copilot-instructions.md` |
+| `chatgpt` | Not supported (returns ok:false) | — |
+
+All paths prepend the SOUL before existing content (preserves user's existing rules).
+On dry-run (`--print`), shows the first 500 chars of what would be written.
+
+## Standalone gateway (no Hermes)
+
+```bash
+oracle setup telegram    # bot token → Grammy poller
+oracle setup discord     # bot token → discord.js
+oracle setup whatsapp    # QR code scan → whatsapp-web.js (auto-installs deps)
+oracle setup signal      # signal-cli (stub)
+```
+
+Oracle polls messaging APIs directly — no Hermes gateway required. All platforms
+share one process (`oracle gateway` on port 9270), using Oracle's own agent runtime.
+Auto-detects Hermes/OpenClaw and uses whichever is available; falls back to
+Oracle standalone polling if neither is present.
+
+For WhatsApp: first run auto-installs `whatsapp-web.js` + `qrcode-terminal`,
+shows a QR code for pairing. Session persists in `~/.config/oracle/.wwebjs_auth`.
+
+## Supported targets
+
+| Command | Target config | Method |
+|---|---|---|
+| `oracle mcp install claude-code` | `~/.claude.json` | `claude mcp add-json` CLI, fallback: mergeMcpServers |
+| `oracle mcp install claude-desktop` | Claude Desktop config | mergeMcpServers |
+| `oracle mcp install chatgpt` | ChatGPT connector | Custom installer |
+| `oracle mcp install codex` | OpenAI Codex CLI | Config file merge |
+| `oracle mcp install copilot` | *(alias for codex)* | Same as codex |
+| `oracle mcp install cursor` | `~/.config/cursor/mcp.json` | mergeMcpServers (Linux), platform-aware path |
+| `oracle mcp install vscode` | `.vscode/mcp.json` or global | mergeMcpServers (`--project` for workspace) |
+
+## Flags
+
+| Flag | Effect |
+|---|---|
+| `--with-soul` | Injects Oracle SOUL.md into the harness as system instructions |
+| `--project` | VS Code: writes to workspace `.vscode/mcp.json` instead of global |
+| `--print` | Dry-run: shows what would be written, makes no changes |
+| `--json` | Machine-readable output for install results |
+
+## Watchdog
+
+```bash
+oracle mcp watchdog          # background: checks every 2m, warns if MCP servers down
+oracle mcp watchdog --once   # one-shot health check
+```
+
+## Wallet setup
+
+```bash
+oracle init --apply                     # generates fresh wallet at ~/.config/oracle/keys/evm.json (0600)
+oracle sign import                      # interactive: paste existing private key (hidden input)
+oracle sign import --keyfile <path>     # import from file (auto-shreds temp file after import)
+```
+
+Both `oracle sign import` paths **auto-arm** — importing a key sets `ORACLE_EXEC_ENABLED=1`
+in `~/.config/oracle/exec.env`. No separate `oracle exec arm` step needed.
+The intent is the signal: pasting a private key means the user wants to trade immediately.
+
+**Rationale:** The user explicitly chose to import their private key and wire the exec MCP.
+Adding a mandatory \"arm\" step on top is unnecessary friction. Import = armed.
+
+**Safety boundary:** The key never leaves the local machine. Oracle's wallet is like a
+CLI-native MetaMask — key on disk at 0600, MCP process local to the machine, same trust model.
+
+The interactive prompt reassures users:
+```
+Your key stays local — Oracle never sends it anywhere.
+Paste your EVM private key (0x...):
+> 
+```
+Key goes to stdin, never to shell history. Saved at 0600 permissions.
+
+Never use `echo "0xKEY"` or `--key 0x...` — private keys must never hit shell history.
+
+## Print mode
+```
+oracle mcp print claude-code     → shows JSON without writing
+oracle mcp print --target cursor → same for any target
+```
+
+## Autofill behavior
+Every target auto-detects the user's config, merges Oracle's MCP server specs
+(`oracle-data`), backs up the original with
+`.bak-oracle-<timestamp>`, and reports the result. No manual JSON required.
+
+## Adding a new target
+1. Create `src/cli/mcp-targets/<name>.mjs`
+2. Export `install<Name>({ oracleRoot, operator, withControl, project, printOnly, cwd })`
+3. Import `buildServerSpecs`, `mergeMcpServers`, `report` from `./shared.mjs`
+4. Import in `src/cli/commands/mcp.mjs`
+5. Add to the install switch and `usage()` text
+
+## Pitfalls
+- `ORACLE_DESK_URL` is not used for MCP — the spec points at the local binary
+- Cursor/VS Code paths differ by OS
+- VS Code `--project` writes workspace `.vscode/mcp.json`, not global
+- After adding a target, verify `oracle mcp print --target <name>` on the installed binary
+- Signing is local. Do not document a remote control/exec MCP in the public pack

package/dist/assets/skills/oracle-multichain-convert/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: oracle-multichain-convert
+description: "Use for Oracle any-asset convert (ChangeNOW/deBridge)."
+---
+
+> Oracle native tools: `oracle_cli` (read/prepare), `vault_status`, `signer_status`, `signer_execute` (needs human confirmationNonce), `skill_load`. No generic shell. No fleet SSH.
+
+
+# Oracle multichain convert
+
+User-facing and desk convert across **any asset** without agent custody.
+
+## When to load
+- BTC → ETH / any CEXy pair
+- SOL ↔ EVM
+- “Is there an alternative to ChangeNOW?”
+- Public Oracle convert product
+- Wiring `CHANGENOW_API_KEY` or deBridge prepare
+
+## Rails (shipped in multiagent-desk)
+
+| Rail | Best for | Key | User action |
+|---|---|---|---|
+| **deBridge DLN** | SOL↔EVM, EVM↔EVM | None | Sign unsigned tx |
+| **ChangeNOW** | BTC L1, long-tail (~1.3k tickers) | Free partner key | Send to deposit address |
+| **Desk DEX/bridges** | EVM already covered | Usually none | Sign/prepare per venue |
+
+## Convert router (single entry)
+- Code: `src/router/convert-route.mjs`
+- Desk: `data.oracle.routing.convert` / `convertQuote` / `convertPrepare`
+- Prefer: BTC/long-tail → ChangeNOW; EVM/Sol → **deBridge**
+- Always `executionReady: false`, public-safe
+- Docs: `docs/CONVERT_ROUTER.md`
+- Tests: `test/convert-route.test.mjs`
+
+```js
+await data.oracle.routing.convertQuote({
+  from: { currency: "sol" },
+  to: { chainId: 8453, currency: "eth" },
+  amountBase: "100000000",
+  senderAddress: "<sol>",
+  toAddress: "0x...",
+});
+```
+
+## deBridge notes
+- Provider `debridge`; API `https://api.dln.trade/v1.0`
+- Solana DLN chainId **`7565164`**; SOL mint `11111111111111111111111111111111`
+- EVM native `0x0000…0000`
+- create-tx: EVM `{to,data,value}` or Solana serialized `tx.data`
+- Send real User-Agent (bare urllib may 403)
+- Docs: `docs/DEBRIDGE_CONVERT.md`
+
+## ChangeNOW notes
+- Provider `changenow`; prepare-only deposit exchange
+- Currencies public; estimate/create need `CHANGENOW_API_KEY` header `x-changenow-api-key`
+- **API key free** (partner signup, no monthly fee); fee in rate; optional ~0.4% partner cut
+- Agent **cannot** create the key for DEMI — he must sign up and install env (0600)
+- Never auto-fund deposit from agent without separate GO
+- Docs: `docs/CHANGENOW_CONVERT.md`
+
+## Public product rules
+- Server holds ChangeNOW key only
+- No public agent/exec hot path for convert spend
+- UI uses convert router, not a single hard-coded venue
+- Copy: user sends/signs — Oracle does not hold bags
+
+## Not this skill
+- Flash-loan MEV (Base/Arb shadows) → `oracle-mev-flashloan-plane`
+- Executor gas hops (Arb→Base Relay) → `cross-chain-executor-funding`
+- RH Chain 4663 trades → rhbot / RH skills
+
+## Pitfalls
+- Claiming ChangeNOW is BTC-only — it includes SOL and long-tail
+- Treating deBridge as BTC L1 solution — weak; use ChangeNOW
+- Pasting API keys in chat
+- Agent inventing a free anonymous key (estimate/create always 401 without partner key)
+- Auto-broadcasting deBridge txs from agent without GO
+- Confusing MEV “0 qualified opps” with convert product funding needs
+
+## Related
+- Desk ops: `multichain-exec-desk`
+- Keys: `protocol-api-key-integration`
+- Public UX: `oracle-public-product`
+
+## References
+- `references/pair-routing.md` — preference table and amounts

package/dist/assets/skills/oracle-native-harness/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: oracle-native-harness
+description: Use for Oracle's own agent loop. Crypto desk tools + skills, not Hermes.
+---
+
+# Oracle native harness
+
+Oracle is its own agent. Chat runs this loop, not `hermes -p oracle`.
+
+## Tools that exist here
+
+| Tool | Job |
+|---|---|
+| `oracle_cli` | Live read + prepare (`data`, `scan`, `route`, `prepare`) |
+| `skill_load` / `skill_list` | Packaged + `~/.config/oracle/skills/<name>/SKILL.md` |
+| `vault_status` | Local vault readiness. No key material. |
+| `signer_status` | Loopback signer ping |
+| `signer_execute` | One already-confirmed artifact. Needs human `confirmationNonce`. |
+| `trade_lifecycle` | Prepare-only fact chain |
+| `web_fetch` / `web_search` | Docs and announcements |
+
+No `terminal`. No fleet SSH. No computer-use.
+
+## Skills that belong here
+
+Crypto desk only: any shipped EVM chain (ETH, Base, Arb, OP, Polygon, BSC, Avalanche, HyperEVM, Abstract, Stable, RH), plus Sol/BTC, HL/Poly data, grants, RFQ, launches, circuit breaker, venue bounds.
+
+Not here: Hermes admin, fleet boxes, RH private ops, Kanban.
+
+## Confirm / arm
+
+Quote first. Human confirms on the local signer. Then `signer_execute`. Disarm kills everything. Autonomous needs `ORACLE_AUTONOMOUS_TRADING=1`.

package/dist/assets/skills/oracle-ownership-gate/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: oracle-ownership-gate
+description: Use when sender identity matters for access control.
+---
+
+> Oracle native tools: `oracle_cli` (read/prepare), `vault_status`, `signer_status`, `signer_execute` (needs human confirmationNonce), `skill_load`. No generic shell. No fleet SSH.
+
+
+# Oracle ownership gate
+
+## The rule
+
+**DEMI's instance is private.** Owner: Telegram ID `1426127634`. All other senders denied.
+No read access. No prepare access. No execution.
+
+## Refusal
+
+"Oracle is self-hostable. Install your own instance: npm install -g @oracle-agent/oracle"
+
+No exceptions. No negotiation. Do not explain the gate.
+
+## What non-owners get
+
+Nothing. Full stop. They must self-host.
+
+## How self-hosting works
+
+`@oracle-agent/oracle` ships an owner-agnostic SOUL. Self-hosters are their own owners.
+They bring their own wallet, keys, models, and Hermes (optional). Full capabilities.
+
+## Two SOUL model
+
+| SOUL | Location | Audience |
+|---|---|---|
+| Shipped | `packages/oracle/profiles/oracle/SOUL.md` | Self-hosters — "You are the owner" |
+| DEMI instance | `~/.hermes/profiles/oracle/SOUL.md` | DEMI only — hardcoded Telegram ID `1426127634` |
+
+## Pitfalls
+
+- Do NOT let non-owners read or prepare through DEMI's instance.
+- The self-host path (`npm install -g @oracle-agent/oracle`) must always be in the refusal message.
+- Sender display name/username is not authorization. Only numeric Telegram ID matters.

package/dist/assets/skills/oracle-public-product-ux/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: oracle-public-product-ux
+description: Use for Oracle onboarding, self-host C+B agent, desk, themes, NL swap UX.
+---
+
+> Oracle native tools: `oracle_cli` (read/prepare), `vault_status`, `signer_status`, `signer_execute` (needs human confirmationNonce), `skill_load`. No generic shell. No fleet SSH.
+
+
+# Oracle public product UX
+
+Class rules for how Oracle is presented and operated for DEMI + self-host downloaders.
+
+## Product law: C + B (decided 2026-08)
+
+**Downloaders interact like the Hermes desk — self-hosted and local.**
+
+| Layer | Meaning |
+|---|---|
+| **C · Custody** | Local agent key on **their** disk (`oracle sign init`). Never house cloud. **Never paste seed into app UI.** |
+| **B · Rails** | `~/.config/oracle/agent-policy.json` — max $/trade, $/day, chains, slippage bps, session TTL, arm/disarm, **noLimits** (armed + all EVM + no caps; Disarm is the only block; DEMI's Mac runs this) |
+
+- Chat: `swap 0.1 ETH to USDC on base` → quote → Confirm · agent (if policy ok) or Sign in wallet.
+- APIs: `/api/oracle/trade/quote`, `/api/oracle/agent/policy`, `/api/oracle/selfhost/{status,init}`.
+- Policy **before** agent sign. Block codes: `per_trade_cap`, `daily_cap`, `chain_blocked`, `disarmed`, `session_expired`.
+- Settings: `AgentPolicySettings`. Desk/exec default copy = `127.0.0.1` for downloaders.
+- Refs: `references/selfhost-c-plus-b-agent-policy.md`, `references/session-2026-08-c-plus-b-ship.md`.
+
+### Custody honesty (user correction)
+
+- Never ask users to paste private key/seed into the Oracle **app UI**.
+- Wallet path: injected provider → public address only → wallet popup signs.
+- Agent path: CLI `oracle sign init` on **their** machine (self-custody operator).
+- “Give Oracle your key” language is wrong for public product.
+
+## Onboarding (self-host local)
+
+```text
+npm i -g @oracle-agent/oracle
+oracle sign init              # key ON THIS MACHINE only
+oracle sign doctor
+# app: POST /api/oracle/selfhost/init  → 127.0.0.1 desk/data/exec
+oracle data serve && oracle signer
+```
+
+- App first-run `OnboardingGate`: checklist + local desk write + CLI steps + start with agent.
+- Prompt: **Your machine. Your agent. Your keys.**
+- Bare `oracle` opens the same chat as `oracle chat`.
+- Optional wallet connect for view / Sign in wallet — not the primary agentic path.
+
+## Demo ≠ arm
+
+| User says | Do |
+|---|---|
+| demo / show / prepare / what would this look like | Live reads + formatted card only |
+| arm | `oracle_control_arm` for exact legs **and/or** policy Arm in Settings |
+| confirm / execute / go | confirm pending ids / Confirm · agent inside policy |
+
+If armed and they say “demo only / don’t arm” → **cancel every pending action**. Never leave execute arms after a demo correction.
+
+## One Oracle — two attach modes
+
+| Who | Desk |
+|---|---|
+| **Downloaders (product default)** | Self-host `127.0.0.1` desk/data/exec on **their** machine |
+| **DEMI thin-client (ops)** | Mac → Arch Tailscale `:8799`/`:8792` — not the public default |
+
+Do not ship downloader copy that assumes Arch. DEMI fleet detail: `oracle-fleet-desk-wiring/references/mac-desktop-arch-desk.md`.
+
+After desktop code change: rebuild, stage runtime, install `/Applications/Oracle.app`.
+
+## App chrome / themes
+
+- Status chip: **Available** / **Unavailable** — never “Oracle available” next to the wordmark.
+- Themes: **Oracle** + **Signal** only.
+- **No CLI tab. No dedicated HL nav tab** — HL is a chain pick, not primary chrome.
+- Composer **one flush line**: model · effort · chain · context · compress. Chain = **box menu** with logos; default = **unset**. HL≡HEVM; no chainId labels. `references/flush-composer-chain-default.md`.
+- Shell: `references/chat-first-app-shell.md`. Config: `references/cli-app-config-sync.md`.
+- Older session notes: `references/session-2026-08-product-ship.md`.
+
+## Portfolio + coin list
+
+- Book headline = coins + NFT floors; **Partial total** when incomplete (`references/portfolio-unified-total.md`).
+- **Your coins** list is primary: USD sort; **Swap/Send** prefills Prepare (`references/portfolio-coin-list-actions.md`).
+- Stable ERC-20 (FEFER) often missing from native-only indexers — probe `watchTokens` + DexScreener (`references/stable-erc20-watch-probe.md`).
+- Agent wallet from `exec.env`; Electron must set `ORACLE_REAL_HOME` so fake-home does not hide config (`references/agent-wallet-balance-and-tx.md`).
+
+## NL swap (desktop = desk)
+
+- Unified `/api/oracle/trade/quote` (any taker). Agent execute: policy → prepare → sign → broadcast → spend ledger.
+- `references/owner-chat-swap-agent-wallet.md`, `references/selfhost-c-plus-b-agent-policy.md`.
+
+## Hyperliquid
+
+- Charts OK as evidence — not required primary tab. Not authorization.
+
+## Shipped / open
+
+Shipped ✅: coin list Swap/Send · flush composer · chain logos + unset default · no HL tab · FEFER watch-probe · trade NL · **C+B agent policy (incl. noLimits preset)** · self-host init/status · onboarding · agent balance path · **conversational confirm/arm** (quote → reply confirm|arm|cancel; new quote supersedes) · **`oracle eval desk`** harness · **obsidian-glass premium chrome** (`px-*` CSS layer → superseded by Fable 5) · **Fable 5 engraved-ledger** (warm bone ink, bronze accents, physical depth, signal discipline) · **swap celebration** (particle burst + checkmark) · token logos on balances.
+
+New refs: `references/agent-policy-rails-and-eval.md` (policy schema, enforcement point, eval command, parse grammar) · `references/premium-obsidian-glass.md` (px-* classes, deploy loop — superseded by Fable 5) · `references/fable-5-design-system.md` (CSS token system, color remap, theme triple-layer, celebration animation, chain logo sources, "looks like a website" fixes).
+
+Still open: gas-from-USDC (Gelato/top-up) · WalletConnect mobile · app-spawn local signer/data · Settings OAuth · ensure desktop self-host does not force `ORACLE_EXECUTE_ENABLED=0` via fake-home.
+
+## HIP-4 / multi-venue honesty
+
+- HIP-4 mainnet: price binaries live; multi-outcome stubs only.
+- Geopolitics → Polymarket until HIP-4 lists events.
+- `xyz:NVDA` = perp on TradeXYZ/HL HIP-3, not spot equity.
+
+## Related
+
+- `oracle-fleet-desk-wiring` — Tailscale desk (DEMI ops)
+- `oracle-agent-dev` — MCP install, publish
+- `oracle-action-semantics` — arm/watch vocabulary (if user-owned, recommend `hermes curator adopt`)

package/dist/assets/skills/oracle-tailscale/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: oracle-tailscale
+description: Use when exposing an Oracle desk across the user's own Tailscale tailnet.
+---
+
+> Oracle native tools: `oracle_cli`, `vault_status`, `signer_status`, `signer_execute`. Use YOUR tailnet only.
+
+# Tailscale (your tailnet)
+
+Use Tailscale so **your** machines reach **your** Oracle desk. Do not publish the desk to the public internet. Do not bind exec/signer to `0.0.0.0`.
+
+## Rules
+
+1. Use a MagicDNS name or the 100.x address of **this install's** node. Never paste a third-party 100.x.
+2. Data/public plane may listen on the tailnet IP if you want remote `oracle` reads.
+3. Local signer stays `127.0.0.1`. Vault keys do not ride the tailnet.
+4. Confirm `tailscale status` shows only nodes you own before opening ports.
+
+## Client env (placeholders)
+
+```bash
+# ~/.config/oracle/env  (0600)
+ORACLE_DESK_URL=http://YOUR_NODE:8799
+ORACLE_DATA_URL=http://YOUR_NODE:8799
+ORACLE_PUBLIC_URL=http://YOUR_NODE:8799
+```
+
+Replace `YOUR_NODE` with your MagicDNS hostname. Verify with `oracle doctor` / `oracle scan chains`.
+
+## Not this skill
+
+Fleet boxes, someone else's Arch, shared operator wallets, GitHub admin packs.

package/dist/assets/skills/oracle-thin-client/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: oracle-thin-client
+description: Use when a laptop or desktop should attach to an Oracle desk the user hosts on their own network.
+---
+
+> Oracle native tools: `oracle_cli`, `vault_status`, `signer_status`, `signer_execute`. No fleet SSH. No one else's box.
+
+# Thin client (your desk, your machines)
+
+A thin client is **your** laptop talking to **your** Oracle desk. It is not a shared house server and not someone else's Tailnet.
+
+## Default (no thin client)
+
+```text
+oracle setup model
+oracle chat
+```
+
+Desk, vault, and signer stay on this machine (`127.0.0.1`).
+
+## Optional: desk on machine A, chat on machine B
+
+Both machines must be yours. Keys stay on the signer host.
+
+On the desk host, bind data/public only as far as you intend (loopback, LAN, or your tailnet). Never `0.0.0.0` for exec/signer.
+
+On the client, point at **your** desk URLs — placeholders only:
+
+```json
+{
+  "deskUrl": "http://YOUR_DESK_HOST:8799",
+  "dataUrl": "http://YOUR_DESK_HOST:8799",
+  "publicUrl": "http://YOUR_DESK_HOST:8799"
+}
+```
+
+Write that to `~/.config/oracle/desk.json` (mode 0600). Do not commit it. Do not copy another person's file.
+
+`oracle doctor` must probe `/health` and `/public/health` on those URLs.
+
+## Signer
+
+The loopback signer (`oracle signer`) stays on `127.0.0.1` on the machine that holds the vault. A thin client does not get a remote private key.
+
+## Related
+
+`oracle-tailscale` · `oracle-native-harness` · `setup`

package/dist/assets/skills/perp-venue-funding-research/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: perp-venue-funding-research
+description: Validate a perp venue's funding before sizing a carry trade.
+category: research
+triggers:
+  - "funding rate"
+  - "funding arb"
+  - "basis trade"
+  - "carry vault"
+  - "new perp venue"
+  - "what's funding on"
+  - "perp market list"
+  - "is this strategy viable"
+---
+
+> Oracle native tools: `oracle_cli` (read/prepare), `vault_status`, `signer_status`, `signer_execute` (needs human confirmationNonce), `skill_load`. No generic shell. No fleet SSH.
+
+
+# Perp venue funding research
+
+Task class: a venue (often brand new, often barely documented) is proposed as the home for a
+carry / funding-basis / cash-and-carry strategy. Discover its public API from scratch, pull the
+**real** market list with funding, and answer whether the edge actually exists.
+
+The deliverable is never "here are the markets." It is **does the money-making mechanism the
+thesis assumes actually operate on this venue.** Those are different questions, and the second
+one is the one that protects capital.
+
+## When NOT to use
+- Hyperliquid specifically → `hyperliquid` (its keyless recipes are already written)
+- Chain-wide TVL / protocol census → `chain-defi-ecosystem-profiling`
+- Enumerating a read-only analytics dashboard → `analytics-dashboard-recon`
+- Actually executing/sizing once validated → `trade-loop-circuit-breaker`, `oracle-best-execution`
+
+## Step 1 — Find the real API (do not trust the given domain)
+
+**Verify the domain resolves before anything else.** Task briefs routinely carry a wrong or dead
+domain. A `curl` status of `000` means DNS failure, not a bad path — no amount of path-guessing fixes it.
+
+```bash
+for h in example.com api.example.com indexer.example.com app.example.com; do
+  echo "=== $h"; getent hosts $h || echo "DNS FAIL"; done
+```
+
+Then, cheapest-probe-first:
+
+1. `curl -s https://api.<domain>/` — a bare root often returns `{"status":"running","docs":...}` and
+   confirms the gateway exists even when every guessed path 404s.
+2. **`docs.<domain>/llms.txt`** — Mintlify/Docusaurus ship this by default. Flat machine-readable
+   index of every doc page with descriptions; for API-reference sites it names every endpoint family
+   in ONE fetch. Also `<docpage>.md` — Mintlify serves a clean markdown twin of any HTML page, far
+   cheaper to grep than a 250KB rendered SPA. Fetching `.md` concept pages is how you get the funding
+   formula without rendering anything.
+3. `/openapi.json`, `/swagger.json`, `/docs`, `/health`.
+4. **Grep the app JS bundle — the highest-yield probe.** Marketing sites are usually Framer/Webflow
+   with zero API references; the *app* subdomain has everything:
+   ```bash
+   curl -s https://app.example.com/ -o app.html
+   grep -oE '(src|href)="[^"]*\.js"' app.html                                # bundle chunks
+   curl -s https://app.example.com/assets/index-XXXX.js -o idx.js
+   grep -oE 'https://[a-zA-Z0-9.-]*example[a-zA-Z0-9.-]*' idx.js | sort -u   # every API host
+   grep -oE '/v1/[a-zA-Z][a-zA-Z0-9/_-]*' idx.js | sort -u                   # every route path
+   ```
+   Surfaces hosts nothing links to — separate spot indexers, routers, staging/testnet — plus routes
+   absent from the docs.
+
+**Do not assume the dYdX v4 scheme.** "Built by the dYdX team" does NOT mean `/v4/perpetualMarkets`.
+Teams reuse people, not URL schemes. Probe, then read the bundle.
+
+## Step 2 — Pull the data
+
+Prefer the one endpoint returning full per-market state (prices + funding + OI + volume + trading-hours
+config) over stitching several. Note which params are mandatory — history endpoints commonly require an
+explicit market and 400 without it, which reads like "broken" if you only tried the bare path.
+
+Report raw strings from the response alongside derived figures. Never silently round a rate.
+
+## Step 3 — Nail the funding interval BEFORE quoting any APR
+
+**Highest-consequence detail in the task.** An 8x error either way turns a dead trade into a great
+one on paper.
+
+Confirm the interval **three independent ways** and say so in the writeup:
+1. The schema/spec field description (`"Hourly funding rate"`).
+2. The prose docs ("funding is charged once an hour").
+3. **Empirically** — diff consecutive timestamps in the funding history. 3600s apart = hourly. The
+   only check that cannot be stale or wrong.
+
+Beware the amortization convention: many venues quote an **hourly** rate that is 1/8th of a premium
+"paid off over 8 hours." The quoted number is still hourly. Annualize `rate * 24 * 365`.
+
+Sanity-check the base rate by reverse-solving it. If RWA funding sits at a constant, `rate * 360 * 24`
+(ACT/360, the TradFi money-market daycount) should land on a recognizable benchmark + spread — that
+confirms you understood the formula rather than pattern-matched a number.
+
+## Step 4 — Test the funding REGIME, not just the current spread ⚠️
+
+**The load-bearing step. A snapshot of current funding cannot validate a carry thesis.**
+
+Most carry theses assume funding *floats freely* and dislocates under some condition (weekends,
+off-hours, volatility). Many venues explicitly engineer that away. Read the funding concept page for
+regime language: *locked*, *fixed at the close*, *base rate*, *suspended*, *off-hours*, *dead-band*, *clamp*.
+
+Then **prove the regime from history** — do not stop at the docs:
+
+```bash
+# pull enough history to span the condition (a weekend, an overnight), then count distinct rates
+curl -s "https://api.example.com/v1/fundingRates?market=NVDA-USD&limit=200"
+```
+Bucket rows by the condition and count **distinct** values. Constant rate across the window = locked
+regime = **no dislocation to harvest**.
+
+**Always run a control.** Test crypto perps (or any market without the regime) over the *same* window.
+If crypto varies and RWA is flat, the flatness is a real mechanism. If *everything* is flat, suspect
+your query, the window, or a stale endpoint. Without the control you cannot distinguish "locked market"
+from "broken pull" — and that mistake runs in both directions.
+
+Run it across **all** markets in the class, not one sample — then you can state "28 of 28" rather than
+"NVDA looked flat."
+
+## Step 5 — Report so it can kill the trade
+
+Lead with the mechanism finding, not the market table. If the thesis is dead, say so in the first lines
+and show the evidence that killed it.
+
+Cover explicitly:
+- **Funding sign + interval**, with the annualization arithmetic shown.
+- **Regime**: when funding is live vs locked/fixed, with exact hours.
+- **What's left**: if the assumed window is dead, name the window where variance *does* exist.
+- **The other side of the trade**: locked funding usually coincides with *wider price bands and higher
+  margin requirements*. Directional gap risk with no funding compensation is strictly worse than the
+  thesis assumed — say that plainly.
+- **Capacity**: OI notional and trades/24h per market. A venue can have a real edge and still be
+  untradeable at size. Flag markets with single-digit daily trades.
+- **TVL ≠ OI.** Deposited collateral and position notional are different numbers; reconcile them
+  explicitly rather than letting a big TVL headline imply depth.
+
+## Pitfalls
+
+- **The brief's domain may not exist.** Check DNS first; `curl` `000` = DNS, not routing.
+- **Pedigree ≠ API shape.** Don't infer endpoints from who built it.
+- **Marketing root has no API strings** — it's a site builder. Go to `app.`.
+- **Bare history endpoints 400 without a required param.** Read the error body; it names the missing field.
+- **A snapshot cannot prove a regime.** Only bucketed history plus a control can.
+- **Fixed-rate off-hours is a *feature* venues advertise** as removing overnight/weekend funding
+  uncertainty. It is deliberately anti-dislocation. Assume it exists until history says otherwise.
+- **Zero-fee claims are checkable** — asset/fee endpoints often expose `maker_fee`/`taker_fee` literally.
+  Verify rather than repeating marketing.
+- **Markets listed but OFFLINE** return all-zero prices/OI. Filter on status before aggregating or your
+  totals and averages are silently wrong.
+- Report `null`/zero marks as-is; a market quoting mark `0` against a live oracle is a real state worth
+  flagging, not a number to clean up.
+
+## Worked example
+Arcus DEX on Robinhood Chain (4663) — full endpoint map, the RWA funding-lock finding that killed a
+weekend funding-arb thesis, and the base-rate arithmetic: `references/arcus-robinhood-chain.md`
+
+## Cross-skill
+- `hyperliquid` — equivalent recipes for HL, already keyless and written
+- `analytics-dashboard-recon` — schema/bundle discovery for read-only dashboards
+- `trade-loop-circuit-breaker` — guardrails before any of this touches capital