@oracle-agent/oracle 0.1.0

package/skills/oracle-best-execution/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: oracle-best-execution
+description: Use whenever swapping or bridging. The rule that the highest quote is not the cheapest trade, and how to compare routes honestly.
+---
+
+# Best execution
+
+The biggest `amountOut` is not the best route. Rank on **net received after gas and
+fees**, every time.
+
+## Get the comparison
+
+```
+best_swap_route   { chainId, tokenIn, tokenOut, amountIn, decimalsIn, decimalsOut }
+best_bridge_route { fromChainId, toChainId, tokenIn, tokenOut, amountIn }
+```
+
+Or at a shell:
+
+```bash
+oracle-route swap   base <tokenIn> <tokenOut> [amountIn]
+oracle-route bridge arbitrum base [token] [amountIn]
+```
+
+## Read the result properly
+
+Report the winner **and** the runners-up. A user who sees only the winner cannot tell
+whether it won by 0.01% or 3%, and that difference decides whether the route is worth
+any extra risk.
+
+Three fields carry most of the meaning:
+
+- **`rankedOn`** — `net-of-cost` means gas was accounted for. `gross` means it was
+  **not**, and the ordering may be wrong.
+- **`costAccounted`** (per route) — `false` means that route's gas is unknown. It is
+  ranked on gross, which **flatters it**. Say so.
+- **`improvementBps`** — `null` means no honest spread exists, usually because the
+  top two routes measure cost differently. Do not invent one.
+
+## What to say
+
+Good: *"ParaSwap nets 1903.88 USDC after $0.01 gas. CoW is 0.01% behind but gasless,
+so on a larger size it likely wins. LI.FI quotes competitively but $4.78 of gas puts
+it 0.5% down."*
+
+Bad: *"Best route: LI.FI, 1899 USDC."* — that is the gross number, and it lost.
+
+## Preparing the winner
+
+`prepare_best_route` compares, then builds the signable artifact for the winner:
+
+```
+prepare_best_route { chainId, tokenIn, tokenOut, amountIn, taker }
+```
+
+`taker` must be the **real wallet that will sign**. Quoting is anonymous; preparing
+is not. Placeholder and burn addresses are rejected.
+
+**Check `artifactKind` before telling the user what to do.** They are not
+interchangeable:
+
+- `unsigned-transaction` (LI.FI, ParaSwap, 0x) — sign and **broadcast** it.
+- `typed-data-order` (CoW) — sign the data and **submit it to the CoW API**. There is
+  nothing to broadcast. Signing authorizes a solver to settle on your behalf.
+
+**Approval comes first, and the spender is not always the destination.** For CoW the
+approval goes to the *vault relayer*, not the settlement contract — approving the
+wrong one produces an order that silently never fills. Read `requiresApproval.spender`
+rather than assuming it equals `destination`.
+
+Some venues refuse to build calldata until the approval already exists on-chain
+(ParaSwap does). That surfaces as `failureKind: "approval-required-first"`, which is
+a real ordering constraint, not a bug: approve, then prepare again.
+
+If the winner has no prepare path, the result names an `alternative`. Say that the
+winner could not be prepared and what you used instead — do not silently substitute.
+
+**Read `driftBps`.** Prepare re-quotes, so this is how far the route moved since the
+comparison. A large negative number means the ranking may no longer hold.
+
+## Preparing a bridge
+
+`prepare_best_bridge_route` — same idea, different hazards.
+
+**`transactions` is always a list.** Some routes need an approval *and* a deposit,
+signed in order. Tell the user how many and that order matters: signing only the
+first leaves funds approved but not bridged.
+
+**Two chains are in play.** Every transaction executes on `fromChainId`; the value
+lands on `toChainId`. Report both. A prepared artifact whose transaction chain does
+not match the origin is refused outright (`failureKind: "chain-mismatch"`).
+
+**Bridging is not atomic — say so unprompted.** The origin transaction confirming does
+**not** mean funds arrived. Give the `durationSeconds` estimate and tell the user not
+to re-send while pending. This is the single most common bridging panic, and silence
+here causes double-sends.
+
+**Across quotes but cannot be prepared** in this build. It often wins on gross because
+its gas is unreported, so expect `failureKind: "no-prepare-path"` with an
+`alternative`. Say the winner could not be prepared and name what you used instead.
+
+## Rules
+
+**One answer is not a comparison.** If only one source responded, say the route is
+unbenchmarked. `sourcesAnswered` vs `sourcesTried` tells you.
+
+**Never present an unknown cost as zero.** A route missing gas data is not free; it
+is unmeasured. Those are different claims and only one of them is true.
+
+**Duration is a cost on bridges.** A route saving $2 that takes 30 minutes is not
+strictly better than one costing $2 more that lands in 20 seconds. Surface both and
+let the user choose — do not silently pick for them.
+
+**Quotes decay.** Every number here is from a past block. Re-quote immediately before
+preparing, and never carry a minOut computed from a stale quote into a signature.
+
+**A comparison is not an execution.** Ranking a route does not prepare, sign, or send
+it. Preparing is a separate step, and signing belongs to the user.
+
+## When sources fail
+
+Aggregators go down, rate-limit, and get sunset (Odos sunset its public API in
+July 2026). Individual failures are expected and appear in `failed[]`. Two things
+follow:
+
+1. Fewer sources means a weaker comparison. Report `sourcesAnswered`, do not hide it.
+2. A failing source is **not** a bad price. Never rank it last — it did not answer.

package/skills/oracle-bitcoin/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: oracle-bitcoin
+description: Use for Bitcoin L1, Ordinals/runes research, and inscription PSBT preparation. User-wallet signing only.
+---
+
+# Bitcoin L1 / Ordinals
+
+Bitcoin is a separate signing plane. Do not route it through EVM grants, EVM
+signers, or EVM calldata policy.
+
+## What this skill owns
+
+- Bitcoin L1 reads through Esplora: tip height, fee rates, address state, UTXOs,
+  transactions.
+- Ordinals/runes reads through the Bitcoin metaprotocol data providers.
+- Satflow marketplace research and unsigned PSBT intents for ordinals/runes market
+  actions when a Satflow key is configured.
+- Inscription planning and **PSBT preparation** for user-wallet signing.
+
+## Inscription flow
+
+Default path is self-custodial:
+
+1. Collect the inscription content, MIME type, destination address, change address,
+   and fee preference.
+2. Check Bitcoin health, fee rates, and the inscription body-size cap.
+3. Estimate commit/reveal cost and UTXO needs before preparing.
+4. Prepare commit/reveal PSBTs or unsigned artifacts.
+5. User signs in Xverse, UniSat, Leather, OKX, Phantom, Magic Eden wallet, or a
+   compatible injected Bitcoin wallet.
+6. Broadcast only after explicit user confirmation.
+7. Report commit txid, reveal txid, inscription id when known, and mempool/receipt
+   status.
+
+## Hard rules
+
+- Never request or print a seed, WIF, xprv, or wallet export.
+- Operator WIF/local signing is not part of the public default. If a deployment
+  has it, it must be separately armed and still explicit-confirm gated.
+- Inscribe is Bitcoin L1 commit/reveal. Satflow is marketplace inventory/listing,
+  not the inscription path.
+- Fee facts are live facts. Re-read fees immediately before prepare.
+- If content exceeds the current cap, refuse and offer compression/splitting.
+- Never claim an inscription landed without a real reveal txid or inscription id.
+
+## Review checklist
+
+- Content hash and byte length shown before signing.
+- MIME type shown in plain language.
+- Destination and change addresses displayed and user-confirmed.
+- Fee rate, estimated vbytes, and worst-case spend shown.
+- Commit/reveal sequence explained as non-atomic.
+- Mempool status checked after broadcast.

package/skills/oracle-chain-graphs-telegram-cards/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: oracle-chain-graphs-telegram-cards
+description: Render per-chain market graphs and Telegram cards for Oracle alerts, including meme launches, HL HIP-3/HIP-4, and Polymarket.
+---
+
+# Oracle chain graphs + Telegram cards
+
+Use when Oracle needs visual alerts: per-chain scanner cards, meme-token launch
+cards, route-comparison charts, Hyperliquid HIP-3/HIP-4 cards, or Polymarket
+cards.
+
+## Surfaces
+
+- Per-chain token charts: price, volume, liquidity, market cap, age, and venue.
+- Launch/sniper cards: token, chain, pool, route readiness, sellability, smart-wallet
+  overlap, risk status, and prepared-ticket status.
+- Hyperliquid HIP-3 builder-dex cards: dex, market, mark/oracle, funding, OI,
+  depth, liquidation/risk notes when account context is provided.
+- Hyperliquid HIP-4 outcome-market cards: event/outcome, bid/ask, depth, edge,
+  held-position context when API keys/account reads are configured.
+- Polymarket cards: event, market, Yes/No prices, volume, BBO, resolution-risk
+  notes, and prepared order intent only when user auth/API keys are configured.
+
+## Data rules
+
+- Public/keyless reads are allowed where the venue supports them.
+- API-key surfaces activate only when the user self-hosts and provides their own
+  keys. Never ship DEMI keys or assume hosted secrets.
+- A graph is evidence, not authorization. It can trigger a prepared ticket; it
+  must not bypass quote freshness, sell-sim, grant caps, or wallet signing.
+- Every card states chain/venue and confidence. Unknown data stays `UNKNOWN`.
+
+## Telegram card rules
+
+- Send text card and graph as separate messages when the card is long.
+- Avoid markdown traps: no unescaped underscore labels, avoid repeated `$` spans.
+- Keep full contracts/mints visible; never truncate the only identifier.
+- Chart rendering must soft-fail: card still sends if the image fails.
+- No buy/sell buttons unless the recipient has a valid local grant/session.
+
+## Graph schema
+
+A graph payload should include:
+
+- `chainId` / `cluster` / venue
+- token/market id
+- time window and candle interval
+- price/volume/liquidity series or order-book snapshots
+- source/provider and fetched timestamp
+- warnings for stale, sparse, or degraded data
+
+## HIP-3 / HIP-4 / Polymarket notes
+
+- HIP-3 builder perps require Hyperliquid `perpDexs` and `metaAndAssetCtxs` with
+  `dex` selected; core `meta` does not include all builder-dex markets.
+- HIP-4 outcome markets require the configured Hyperliquid/API-key path for user
+  account/order actions. Keyless cards can still show public market data.
+- Polymarket public reads work keyless; trading/order placement needs the user's
+  CLOB auth/API setup and stays prepared/user-signed.

package/skills/oracle-circuit-breaker/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: oracle-circuit-breaker
+description: Use before any repeated, automated, or loop-driven trading action. Mandatory guardrails so a broken loop cannot drain a wallet.
+---
+
+# Circuit breakers
+
+A loop that trades is a loop that can lose money at machine speed. Every automated
+or repeated action needs these before it runs once.
+
+## Mandatory guardrails
+
+1. **Max iterations.** A hard count, not a "should converge" argument. Loops that
+   cannot terminate on their own must be terminated by the harness.
+2. **Consecutive-failure stop.** N failures in a row halts the loop. A loop that
+   retries a failing action forever burns gas to no effect.
+3. **Cumulative spend ceiling** across the whole run, not per action. Twenty
+   trades at the per-trade cap can exceed the intended risk by 20x.
+4. **Cooldown between actions.** Prevents a same-block hammer and gives state time
+   to settle.
+5. **Kill switch checked immediately before each action**, not once at start. A
+   switch read at t=0 and acted on at t=60s is stale.
+6. **Halt on unexpected state.** Balance moved when it shouldn't have? Stop and
+   report. Do not "adapt."
+
+## Mid-run failure stops the run
+
+If a multi-part action fails partway — leg 2 of 3, slice 4 of 10 — **stop**. Do not
+continue to the remaining legs. The failure may mean the market moved, the route
+went stale, or an approval was consumed. Continuing turns one bad fill into
+several.
+
+Report: what completed (with hashes), what failed, and the current position.
+
+## Slippage is a cap, not a target
+
+A supplied tolerance is the **maximum acceptable**, not the value to use. Compute
+the guard from live depth and volatility per leg, immediately before broadcast. If
+the required guard exceeds the cap, **block** — requote or split. Never widen to
+force a fill.
+
+## Paper before live
+
+A strategy earns real size by producing a scorecard first. Shadow it, measure the
+markout, then size. "It looked right in backtest" is not a scorecard.
+
+## The bright line
+
+An automated loop may **prepare**. A human authorizes what moves value, or a
+narrowly scoped, short-TTL, spend-capped grant does. There is no third option
+where the loop decides it has permission.

package/skills/oracle-contract-research/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: oracle-contract-research
+description: Use when verifying a contract, router, factory, or venue address before trusting it with value.
+---
+
+# Contract research
+
+The destination allowlist is the highest-leverage control on this desk. Allowlisting
+a spoofed router defeats every other protection. So verification is not a formality.
+
+## Never trust a name
+
+Explorer contract names are self-reported and clones reuse them. "UniswapV2Router02"
+on an explorer means someone deployed a contract and called it that.
+
+Verify instead:
+
+1. **Bytecode exists** — `eth_getCode` must return real code. `0x` means nothing is
+   deployed. A 2-byte result is an empty stub.
+2. **The protocol's own API or docs** name that address, on that chain, today. For
+   aggregators, query their API (e.g. LI.FI's `/chains` returns each chain's
+   official `diamondAddress`) rather than trusting a blog post.
+3. **Constructor-bound addresses match** — read `factory()`, `WETH9()`,
+   `quoter()` back off the deployed contract and confirm they are what you expect.
+4. **Per chain, separately.** An address verified on Arbitrum is not verified on
+   Ethereum, even when the canonical deployment happens to share an address.
+
+Record **how and when** you verified, in a comment next to the entry. The audit
+trail has to outlive your session.
+
+## Pools
+
+- `blockTimestampLast == 0` on `getReserves()` → not a live pool
+- a token's *own* reserves may be virtual or zero; the tradeable market is a
+  different pair address
+- confirm the advertised pool equals `factory.getPool(tokenA, tokenB, fee)`
+
+## Forks are not the original
+
+A fork may keep the pair interface while replacing the router entirely — for
+instance requiring an off-chain signed quote you cannot produce. Decode a recent
+real swap on the pool to find the router the market actually uses, and its selector.
+
+A non-standard selector is a signal, not a curiosity.
+
+## Approvals
+
+Approve the **exact amount**. Never default to unlimited. After an approve lands,
+read `allowance` back before firing the dependent transaction — an approve that
+reverted silently turns the next call into a confusing failure.
+
+## Fail closed
+
+An unverified chain or venue stays blocked. That is a safe state, not a gap to route
+around. Never allowlist an address you found only from a model's answer.

package/skills/oracle-desk/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: oracle-desk
+description: Use when routing a crypto request to the right lane or comparing options across chains. The router's operating manual.
+---
+
+# Routing the desk
+
+## Decide the lane before doing the work
+
+Every crypto request gets a routing decision first:
+
+1. **Which chain?** If the request names a token but not a chain, resolve the
+   token's home chain (DexScreener search via the data plane). Do not guess.
+2. **Which lane owns it?** Venue lanes own their venue. Cross-chain comparison is
+   yours.
+3. **Is it multi-chain?** Then quote each option yourself and synthesize. Do not
+   ask one venue lane to opine on another's chain.
+4. **Still ambiguous?** Ask. A wrong chain assumption produces confidently wrong
+   numbers.
+
+## Comparing chains honestly
+
+When asked "which is cheaper" or "where should this go," the comparison must be
+like-for-like:
+
+- quote the **same notional** on each chain, not the same token amount
+- include **gas in the same unit** (USD), because 0.001 ETH means different things
+  on mainnet and an L2
+- include **bridge cost and time** if the funds aren't already there
+- include **price impact at that size**, not the headline mid
+- note **liquidity depth** — the cheapest venue at $100 is often not cheapest at
+  $50k
+
+A comparison that ignores bridging or impact is a wrong answer dressed as a table.
+
+## Capability tiers are not interchangeable
+
+The data catalog labels each provider honestly. Respect the label:
+
+| Tier | Means |
+|---|---|
+| `read-only` | data only, no execution claim whatsoever |
+| `quote-only` | can price a route; no reviewed transaction builder |
+| `prepare` | returns a policy-bound unsigned transaction |
+| `intent` | returns a typed-data order to sign, not a transaction |
+
+**API coverage ≠ execution support ≠ live trading support.** When asked "can we
+trade X," answer with the tier, not yes/no.
+
+## Don't invent chain facts
+
+If a number did not come from a live read this turn, it is `unknown`. Not "roughly,"
+not "typically." Stale liquidity and stale gas are how people get filled badly.
+
+## Synthesis
+
+Lead with the recommendation and the number. Then the two or three facts that drove
+it. Then the risk that would change the answer. State confidence explicitly.

package/skills/oracle-dex-launch/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: oracle-dex-launch
+description: Use when designing, reviewing, or preparing a DEX, AMM pool, router/factory fork, token launch, or liquidity bootstrap.
+---
+
+# DEX / AMM launch builder
+
+Use this for launching or auditing token markets, DEX forks, pools, routing surfaces,
+liquidity bootstraps, and trading UIs.
+
+## Decide the AMM shape
+
+- V2 constant-product pair: factory, router, WETH/wrapped native, fee, LP token.
+- V3 concentrated liquidity: factory, position manager, quoter, router, fee tiers.
+- Stable-swap / Curve-like: pool invariant, amplification, coins, router.
+- Aggregator frontend: quote source, destination allowlist, minOut/deadline guard.
+
+Do not bend one adapter to fit another shape. V2, V3, stable-swap, and aggregator
+routes need separate encoders and tests.
+
+## Launch checklist
+
+1. Verify canonical factory/router/quoter addresses from official sources and live
+   functional probes, not names or codesize alone.
+2. Define initial liquidity, starting price, lock/burn policy, and treasury role.
+3. Simulate buy and sell, including exact approval path and round-trip retention.
+4. Enforce nonzero minOut, short deadlines, route attestation, and gas caps.
+5. Record per-chain provenance next to any allowlisted venue address.
+6. Publish honest risk labels: `LIVE`, `UNKNOWN`, `UNAVAILABLE`, or `FAIL`.
+
+## Hard rules
+
+- No fake TVL, wash-volume instructions, hidden tax switches, or owner-only sell
+  bypasses.
+- A successful buy quote does not prove sellability. Test exits first.
+- A router on one chain is not verified on another chain.
+- Preparing a pool deploy is not live support; live support needs simulation,
+  allowlist, signer-bound policy, receipt verification, and docs.

package/skills/oracle-grants/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: oracle-grants
+description: Use when arming, widening, or refusing an agent action against a bound grant. Defines what authorization means on this desk.
+---
+
+# Bound grants
+
+The model proposes. The owner authorizes. A grant is the authorization.
+
+## What a grant is
+
+An owner-signed permission with hard bounds:
+
+```
+chain        which chain id, exactly one
+actions      read:chain | simulate:tx | prepare:* — never "broadcast:*"
+targets      destination allowlist: the addresses value may reach
+maxValueWei  spend cap
+maxGasWei    gas cap — gas is separate money
+expiresAt    unix timestamp; after this the grant is dead
+```
+
+Your reasoning is not authorization. A convincing argument that an action is safe
+does not widen a grant.
+
+## Refusing correctly
+
+When an action falls outside the grant, refuse and **name the bound that broke**:
+
+> Refused. Grant covers chain 8453; this route settles on 42161.
+
+> Refused. Destination 0xabc… is not in the allowlist for chain 8453.
+
+> Refused. Grant expired 14 minutes ago.
+
+A vague "I can't do that" teaches the user nothing. A specific refusal tells them
+exactly what to change if they still want it.
+
+## Fail closed, always
+
+An **empty** destination allowlist means *refuse everything*. It never means
+"nothing specified, so allow anything." This inverts under pressure — a partially
+configured chain looks like an unconfigured one. Fail closed.
+
+## Gas is separate money
+
+A grant that caps `value` but not gas is not capped. Unbounded gas limit or fee
+drains the wallet outside the value ceiling. Both caps or neither is meaningful.
+
+## The caps are not negotiable mid-task
+
+If a route needs more slippage than the cap allows, the answer is block, requote,
+or split — **not** widen. A cap that yields under pressure is decoration.
+
+Likewise a hard ceiling stays hard: a caller-supplied tolerance is a *maximum*, not
+the selected value.
+
+## Authorization expires
+
+Prefer short TTLs. A permanent broad grant is a hot wallet with extra steps. When a
+grant lapses, the lane returns to reading — that is the system working, not a
+regression to route around.
+
+## Re-check at the boundary
+
+Validate the grant at **sign time and broadcast time**, not only when the plan was
+made. State can change between planning and execution: a stale check is not a
+check. Reject a guard that is missing, stale, wrong-chain, wrong-venue, or
+over-cap.

package/skills/oracle-hypercore-staking/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: oracle-hypercore-staking
+description: Stake, delegate, undelegate, and unstake HYPE on Hyperliquid HyperCore. Prepare-only, user wallet signs.
+---
+
+# HyperCore HYPE staking
+
+Use when someone asks Oracle to stake HYPE, delegate to a validator, undelegate,
+or unstake back to spot on Hyperliquid.
+
+## The four moves, in order
+
+HyperCore keeps staking in two buckets. Know which one holds the HYPE before
+preparing anything.
+
+| Move | Action | From -> To | Timing |
+|---|---|---|---|
+| Stake | `cDeposit` | spot -> staking balance | instant |
+| Delegate | `tokenDelegate` isUndelegate=false | staking balance -> validator | 1 day validator lockup |
+| Undelegate | `tokenDelegate` isUndelegate=true | validator -> staking balance | instant after lockup |
+| Unstake | `cWithdraw` | staking balance -> spot | 7 day queue |
+
+Staking balance earns nothing until it is delegated. "Unstake" almost always
+means two steps: undelegate first, then withdraw.
+
+## Flow
+
+1. `desk.hl.staking.preflight(user)` - read delegated, undelegated, and pending
+   withdrawal balances plus the queue and lockup constants.
+2. `desk.hl.staking.validators()` - pick a validator. Reject jailed ones and
+   surface commission before recommending.
+3. Prepare exactly one move:
+   - `desk.hl.staking.prepareStake({ amountHype, maxHype })`
+   - `desk.hl.staking.prepareDelegate({ validator, amountHype, isUndelegate })`
+   - `desk.hl.staking.prepareUnstake({ amountHype })`
+4. Hand back the EIP-712 typed data. The user's wallet signs and submits.
+
+## Rules
+
+- Amounts are decimal HYPE strings at 8 decimals. `hypeToWei("1.5")` is
+  `150000000`. More than 8 decimals is rejected, not rounded.
+- `maxHype` is a hard cap checked before anything is built. No cap, no size
+  discipline on an agent path.
+- Never claim a stake happened. These functions return `broadcastReady: false`
+  and `requiresUserSignature: true`. There is no submit function in the module
+  on purpose.
+- Warn about the 7 day unstaking queue every time you prepare a `cWithdraw`.
+  The HYPE is illiquid for the whole queue.
+- Warn about the 1 day validator lockup before a delegate.
+- Check `undelegated` balance before preparing a withdraw. Withdrawing more than
+  the undelegated bucket fails on chain, and the failure costs the user a round
+  trip.
+
+## Verification
+
+`npm run e2e:hypercore-staking` hits live validator/delegator reads and asserts
+every prepare path stays unsigned with caps enforced.

package/skills/oracle-hyperliquid/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: oracle-hyperliquid
+description: Use for Hyperliquid perps and spot — funding, books, positions, liquidation distance via the public info API.
+---
+
+# Hyperliquid
+
+Read through Oracle's data plane (`hl-info` provider, public `/info` endpoint). No
+key required for reads.
+
+## Ops worth knowing
+
+| Need | Op |
+|---|---|
+| all mids | `allMids` |
+| order book | `l2Book` |
+| perp metadata + live ctx | `metaAndAssetCtxs` |
+| spot metadata | `spotMeta` |
+| account state | `clearinghouse` / `userState` |
+| fills | `userFills` |
+| open orders | `openOrders` / `frontendOpenOrders` |
+| candles | `candleSnapshot` |
+
+`metaAndAssetCtxs` is the efficient one: it returns funding, open interest, mark and
+oracle price for every asset in a single call. Prefer it over per-asset loops.
+
+## The three numbers that matter
+
+**Liquidation distance.** In percent. Always state it for a leveraged position. A
+"20x position" is really "a 5% adverse move ends this."
+
+**Funding.** Annualize it. A position paying 40% annualized is losing steadily even
+when directionally right. Funding flips sign — check the current rate, not the
+average.
+
+**Depth at your size.** The mid is a fiction for anything but the smallest clip.
+Walk the `l2Book` to your notional and quote the real average fill.
+
+## Mark vs oracle price
+
+Liquidations reference the **oracle** price; PnL references the **mark**. They
+diverge during volatility, which is exactly when it matters. Say which one you used.
+
+## Spot and perps are different assets
+
+The same ticker exists in both with different liquidity and no automatic
+relationship. Never quote a perp book for a spot question.
+
+## Hard rules
+
+1. State liquidation distance for every leveraged position — not optional.
+2. Annualize funding, always.
+3. Quote fills from book depth, not the mid.
+4. Never size to "max leverage" without naming the wipeout move.
+5. You prepare; the user's wallet signs.
+6. Receipts or it didn't happen.