@dev.sail.money/sailor 1.3.0-224 → 1.3.0-225

package/templates/default/.agents/skills/sail-token-resolve/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: sail-token-resolve
+description: Resolve the tokens a user names by symbol or address into on-chain metadata (address, decimals) AND a cross-chain, cross-DEX liquidity map — which Sail chain and which protocol (Uniswap V3/V4, Sushiswap, PancakeSwap, Aerodrome…) actually hold liquidity, how deep each pool is, and whether the leg is swap-ready. Use BEFORE building any swap/DCA/LP/lending mandate, or whenever a user says "a portfolio of X and Y" / "DCA into A, B, C" / "can I swap X here?". Pass every symbol at once. Resolves ANY symbol — curated registry → keyless GeckoTerminal DEX index → on-chain symbol()+decimals() — and recommends which chain to act on. Runs the bundled `scripts/resolve-token.mjs` (no dependencies, no gas, no API key).
+---
+
+# sail-token-resolve — tokens → addresses + where the liquidity lives
+
+Users name tokens by symbol ("WETH", "UNI", "HYPE", "MORPHO") far more often than by
+address, and they think in *portfolios* ("a DCA of USDC, UNI and MORPHO"), not single
+legs. This skill takes **one or many** symbols and, for each, returns: the verified
+on-chain **address + decimals** per chain, a **liquidity venue map** (which chain, which
+DEX/protocol, which pool, how deep), whether it is **swap-ready**, and a **recommendation**
+when there's a discrepancy — liquidity split across chains, no pool on your chain but a deep
+one elsewhere, or no pool on any Sail chain at all.
+
+**"token exists" ≠ "token is swap-ready."** A token can have a valid contract with zero
+routable liquidity. Swap-ready (on-chain confirmed) means Uniswap V3 QuoterV2 returns a
+non-zero USDC→token quote — Sail's executable fast-path route.
+
+## When to load
+
+- The user names one or more tokens and you need addresses/decimals for a mandate.
+- A user describes a **portfolio / DCA / basket** — resolve every symbol in one call.
+- Before `sail-swap-quote` or `sail-template-swap` — both consume this skill's output.
+- Whenever the user asks "can I swap X here?", "where's the best liquidity for X?", or
+  "which chain should I use for this strategy?"
+
+## Run it
+
+```bash
+# From the project root (reads .sail/.env.local for RPCs + chain):
+node scripts/resolve-token.mjs WETH                    # single token, configured chain(s)
+node scripts/resolve-token.mjs LINK --chain unichain   # force one chain
+node scripts/resolve-token.mjs 0x4200…0006 --chain base # address input
+node scripts/resolve-token.mjs USDC UNI HYPE MORPHO    # PORTFOLIO → rich JSON
+node scripts/resolve-token.mjs UNI --all-chains --json # scan every Sail mainnet
+```
+
+Flags: `--chain <ethereum|unichain|base|arbitrum>` forces one chain; `--rpc <url>` overrides
+the endpoint; `--all-chains` maps every Sail mainnet (even ones without an RPC configured —
+those use GeckoTerminal-only data) so you can recommend "put your SMA on chain Y"; `--json`
+forces the rich per-token map for a single token.
+
+## Output shapes (pick the right consumer)
+
+| Invocation | stdout shape |
+|---|---|
+| 1 symbol, single configured chain / `--chain` | **bare object** — `{address, decimals, feeTier, swapReady, quote, venues[], …}` (the shape `sail-swap-quote` / `sail-template-swap` expect) |
+| 1 symbol, ≥2 configured chains | **array** of bare objects (one per chain) |
+| ≥2 symbols | **portfolio**: `{ tokens: [tokenWrapper…], summary }` |
+| 1 symbol + `--json`/`--all-chains` | **token wrapper** (see below) |
+
+A **token wrapper** is:
+
+```jsonc
+{
+  "query": "UNI",
+  "chains": {                       // keyed by chain name; each value is a bare per-chain object
+    "base":     { "address": "0x…", "decimals": 18, "swapReady": true, "feeTier": 10000,
+                  "venues": [ … ], "bestVenue": { … }, "onchainVerified": true, … },
+    "unichain": { … }
+  },
+  "chainsWithLiquidity": ["unichain","base","arbitrum"],
+  "onSailChain": true,
+  "crossChain": { "action": "route", "deepestChain": "base", "note": "…human guidance…" }
+}
+```
+
+A **venue** (inside `venues[]`, sorted deepest-first, capped at 8; `venuesTotal` is the full
+count) is:
+
+```jsonc
+{ "protocol": "uniswap-v3",      // uniswap-v3 | uniswap-v4 | uniswap-v2 | sushiswap | pancakeswap | aerodrome | other
+  "dexId": "uniswap-v3-base",    // raw GeckoTerminal id
+  "pool": "0x…", "feeTier": 500, // basis points (500 = 0.05%); null if the pool has no fee in its name
+  "pairedSymbol": "USDC", "pairedToken": "0x…",
+  "liquidityUsd": 8645941, "volume24hUsd": 22333927,
+  "sailRoutable": true,          // Sail's fast path can route it (see below)
+  "quoteVerified": true }        // a live on-chain QuoterV2 quote confirmed THIS venue
+```
+
+## How it works
+
+1. **Symbol → address** (two layers): curated registry (instant, offline) → GeckoTerminal
+   search (keyless CoinGecko DEX index) for anything not curated. Candidates are ranked by
+   pool liquidity; the on-chain `symbol()` check is the final authority (a wrong DEX-side
+   match is rejected, not trusted).
+2. **On-chain verify** — `symbol()` + `decimals()` via eth_call on every chain that has an
+   RPC. This is the source of truth (`decimalsSource: "onchain"`). On an `--all-chains` scan
+   of a chain with no RPC, metadata falls back to GeckoTerminal (`decimalsSource:
+   "geckoterminal-unverified"`) — flag this to the user before wiring it into a mandate.
+3. **Liquidity venue map** — `GET /networks/{net}/tokens/{addr}/pools` returns every pool
+   GeckoTerminal indexes, across **all DEXes** (Uniswap V3/V4, Sushiswap, PancakeSwap,
+   Aerodrome, …), with the protocol, pool address, fee tier and USD depth. One call per token
+   per chain.
+4. **Swap-readiness (on-chain confirmed)** — quotes USDC→token across fee tiers 500/3000/10000
+   via Uniswap V3 QuoterV2 and marks the matching venue `quoteVerified: true`. This is the only
+   *executable* signal; everything else in `venues[]` is informational.
+
+## `sailRoutable` — what Sail's fast path can actually swap
+
+Sail's `sail-template-swap` fast path routes through **Uniswap V3** (everywhere) and the
+**Uniswap V4** Universal Router (on Unichain). Those venues are marked `sailRoutable: true`.
+Sushiswap, PancakeSwap, Aerodrome (and Uniswap V2) are detected and surfaced so you can see
+*where the liquidity really is*, but they're `sailRoutable: false` — Sail can't route them via
+the fast path. If the only liquidity is on a non-routable DEX, the token needs a custom mandate
+(`sail-mandates`) or should be held. (Pools with absurd fees — >10% — are spam and are never
+marked routable.)
+
+## How to present results to the user
+
+Read `crossChain.action` (per token) and the portfolio `summary`, then advise:
+
+- **`route`** — swap-ready on a configured chain. If it's routable on **more than one**
+  configured chain, surface both with their depths and ask which to use (or pick by where the
+  rest of the basket lives). Hand the chosen chain's bare object to `sail-swap-quote`.
+- **`suggest-sma`** — no routable pool on the configured chain(s), but a deep one on another
+  Sail chain. Tell the user and **recommend deploying an SMA on that chain** for this leg
+  (e.g. "MORPHO has no Uniswap pool on Base; the deep pool is Uniswap V3 on Unichain — consider
+  an SMA on Unichain"). Don't silently drop it.
+- **`manual-address`** — liquidity exists but only on a DEX Sail can't fast-route (e.g. only on
+  Aerodrome). Offer a custom mandate via `sail-mandates`, or hold the leg.
+- **`hold-skip`** — no pool on any scanned Sail chain (the token may live on a non-Sail chain,
+  e.g. a HyperEVM-only asset). Recommend holding/dropping it from the strategy.
+
+Always show the resolved **address + decimals + the chain/protocol/depth** you're acting on, so
+the user can sanity-check before anything is signed.
+
+## Worked example — "create a DCA strategy of USDC, UNI, HYPE and MORPHO"
+
+```bash
+node scripts/resolve-token.mjs USDC UNI HYPE MORPHO --all-chains
+```
+
+A typical read of the result:
+- **USDC** — the quote asset; swap-ready everywhere (`feeTier: null`, it *is* USDC).
+- **UNI** — `route`; routable on Unichain/Base/Arbitrum. Pick by depth or by where the basket
+  concentrates.
+- **HYPE** — `route` only on **Unichain** (a real ~$4M Uniswap V3 USDC pool); absent/illiquid
+  elsewhere. Tell the user HYPE is a Unichain-only leg here.
+- **MORPHO** — `route` on **Base** (Uniswap V3 USDC pool); on other chains it exists but has no
+  routable USDC pool. If the project is configured for Base, good; if not, `suggest-sma`.
+
+Then, for each `route`/chosen-chain leg, hand `(address, decimals, feeTier)` to
+[`sail-swap-quote`](../sail-swap-quote/SKILL.md) → [`sail-template-swap`](../sail-template-swap/SKILL.md).
+
+## Important
+
+- **Decimals are critical** — 25 USDC = `25_000_000` (6 dec); 1 WETH =
+  `1_000_000_000_000_000_000` (18 dec). Every cap in a mandate is base units. Trust
+  `decimalsSource: "onchain"`; treat `geckoterminal-unverified` as provisional.
+- **Addresses are per-chain** — WETH on Unichain ≠ WETH on Base ≠ WETH on Arbitrum. Resolve and
+  verify separately per chain; never copy an address across chains.
+- **`getPool` is unreliable** on some forks — swap-readiness trusts a non-zero QuoterV2 quote,
+  never the V3 factory's `getPool`.
+- **Symbol ambiguity / scam collisions.** When a symbol isn't curated, the deepest-pool
+  candidate whose on-chain `symbol()` matches is used. A scam token can share a real symbol; the
+  liquidity ranking favours the canonical one, but for an obscure symbol glance at the resolved
+  `address` and `source` before wiring it in — or pass the intended contract's `0x` address
+  directly (address-input bypasses the DEX lookup). Also sanity-check a venue's `volume24hUsd`
+  against its `liquidityUsd`: a huge pool with near-zero volume is inflated/non-trading, and a
+  big pool whose `pairedSymbol` is a look-alike (e.g. a "HYPE/BASEDHYPE" pool) is a *different*
+  asset — depth there does not make *your* token swap-ready.
+- **`bestVenue` is USDC-relevant, not the biggest pool.** It's the deepest *Sail-routable,
+  USDC-paired* pool (the one a USDC DCA would route through), so it can be smaller than the
+  largest pool in `venues[]` (which may be a WETH or look-alike pair).
+- **Missing venues ≠ no liquidity.** A chain can be `swapReady: true` (from the on-chain
+  QuoterV2 probe) yet show empty `venues[]` with `venuesError` set if GeckoTerminal rate-limited
+  that call. Trust `swapReady`; to repopulate the venue map for one chain, re-run
+  `node scripts/resolve-token.mjs <SYM> --chain <name> --json`.
+- **Rate limits** — GeckoTerminal is keyless and rate-limited; the script throttles and caches
+  calls. A big `--all-chains` portfolio takes a moment. Set `GECKO_MIN_SPACING_MS` to tune the
+  spacing. A transient GeckoTerminal failure on one chain sets `venuesError` and leaves
+  `swapReady` intact (it's from the on-chain probe) — it never aborts the whole run.

package/templates/default/AGENTS.md

@@ -40,7 +40,7 @@ During **setup**, always ask before anything that costs gas. Once the **mandate
 
 ## First contact
 
-When the user says start (or any first message), present the welcome above in full — definition, stage list, handoff line — before doing anything else. Do not launch the UI yet. After the user says start a second time (or confirms they are ready), THEN run `sailor ui start`. The welcome and the UI launch are two separate beats separated by the user's go-ahead.
+When the user says start (or any first message), present the welcome above in full — definition, stage list, handoff line — before doing anything else. Do not launch the UI yet. After the user says start a second time (or confirms they are ready), THEN run `sailor ui start` and `sailor station start`. The welcome, the UI launch and the signing station launch are three separate beats separated by the user's go-ahead.
 
 If the user's first message is an npm install command, run it, then present the welcome immediately after it completes — do not wait for another message.
 
@@ -80,11 +80,28 @@ Detailed procedures live in skills. If your tooling does not auto-discover skill
 | sail-onboarding | New project setup, or resuming a partially set-up project, documentation of sailor commands | `.agents/skills/sail-onboarding/SKILL.md` |
 | sail-project-info | Any question about project, account, mandate, chain, or environment state | `.agents/skills/sail-project-info/SKILL.md` |
 | sail-servers | Starting, stopping, or health-checking the dashboard or signing station | `.agents/skills/sail-servers/SKILL.md` |
+| sail-token-resolve | Resolving a token symbol/address to its on-chain address + decimals, and checking whether a Uniswap V3 pool exists (swap-readiness) | `.agents/skills/sail-token-resolve/SKILL.md` |
+| sail-swap-quote | Fetching a live Uniswap V3 quote and the slippage-adjusted amountOutMinimum floor | `.agents/skills/sail-swap-quote/SKILL.md` |
+| sail-templates | Registry + reuse guide for Sail's shared permission singletons — which primitives exist as templates, per-chain deployment status (`deployed.json`), and the register→configure reuse flow. Start here before any template mandate | `.agents/skills/sail-templates/SKILL.md` |
+| sail-template-swap | Bounded DEX swap / DCA mandate via the shared SwapPermission singleton (oracle-gated slippage band) — register + configure, no Solidity. The fast path for a swap/DCA strategy | `.agents/skills/sail-template-swap/SKILL.md` |
+| sail-template-swap-no-oracle | Bounded swap for tokens with NO oracle via SwapPermissionNoOracle (single-pool hallucination guard, NOT manipulation-resistant) — reference-only, not yet deployed on any chain | `.agents/skills/sail-template-swap-no-oracle/SKILL.md` |
+| sail-template-transfer | Bounded ERC-20 transfer to a mutable recipient allowlist via TransferPermission | `.agents/skills/sail-template-transfer/SKILL.md` |
+| sail-template-withdraw | Bounded ERC-20 withdraw to ONE fixed recipient (owner-Safe consolidation) via WithdrawPermission | `.agents/skills/sail-template-withdraw/SKILL.md` |
+| sail-template-deposit | Bounded deposit into ERC-4626 vaults / Aave v2–v3 via DepositPermission | `.agents/skills/sail-template-deposit/SKILL.md` |
+| sail-template-borrow | Bounded lending borrow against Aave / Morpho / Compound with an on-chain LTV check via BorrowPermission | `.agents/skills/sail-template-borrow/SKILL.md` |
+| sail-template-approve-batch | Atomic approve → call → reset (allowance bracket) in one batch via ApproveAndCallBatchPermission | `.agents/skills/sail-template-approve-batch/SKILL.md` |
 | sail-transactions | Building dispatches or any EVM transaction for the agent | `.agents/skills/sail-transactions/SKILL.md` |
-| sail-mandates | Designing, authoring, testing, deploying, or authorizing permission contracts | `.agents/skills/sail-mandates/SKILL.md` |
+| sail-mandates | Designing, authoring, testing, deploying, or authorizing permission contracts (the bespoke-Solidity escape hatch) | `.agents/skills/sail-mandates/SKILL.md` |
 | sail-automation | Automating the agent — GitHub Actions, self-hosted runner, Docker, or local daemon | `.agents/skills/sail-automation/SKILL.md` |
 | sail-extend | Notifications or a custom dashboard, once the agent is live | `.agents/skills/sail-extend/SKILL.md` |
 
+**Shared singletons are the default for the common DeFi primitives.** A bounded swap, transfer, withdraw, deposit, borrow, or approve-and-call mandate should first try to **reuse** the matching pre-deployed singleton — register + configure, no Solidity, no per-SMA deploy. Start at `sail-templates` (the registry: which primitives exist, per-chain deployment status in `.agents/skills/sail-templates/deployed.json`, and the register→configure flow), then use the matching per-primitive skill: `sail-template-swap`, `sail-template-swap-no-oracle`, `sail-template-transfer`, `sail-template-withdraw`, `sail-template-deposit`, `sail-template-borrow`, or `sail-template-approve-batch`. Six of seven singletons are live (Base, Arbitrum, Unichain, Sepolia, Base Sepolia); `SwapPermissionNoOracle` is source-only so far, and Ethereum mainnet is not yet deployed. Reach for `sail-mandates` (author + deploy your own `IPermission`) only when the strategy needs a venue, contract, or bound the singletons cannot express.
+
+**Bundled scripts** under `scripts/` are dependency-free tools that make the fast path quick and deterministic — run them from the project root so they read `.sail/.env.local`:
+- `resolve-token.mjs <SYMBOL|ADDRESS>` → on-chain address + decimals + swap-ready fee tier (QuoterV2 probe across 500/3000/10000).
+- `quote-swap.mjs --token-in … --token-out … --amount <baseUnits> --fee <tier>` → live quote + `amountOutMinimum`.
+- `shared-template-addr.mjs <TemplateName>` → the singleton's deployed address on the active chain.
+
 ## Invariants — apply to every turn
 
 - Do not present the welcome and immediately launch the UI — wait for the second "start"
@@ -97,5 +114,7 @@ Detailed procedures live in skills. If your tooling does not auto-discover skill
 - Do not commit `SAIL_PASSPHRASE` or private keys
 - ERC-20 `approve()` calls are NOT covered by supply, swap, or deposit permissions — every approve the strategy makes needs explicit coverage. Two non-mixable models: per-call (separate single dispatches, one `IPermission` each — the default) or atomic batch (one `IBatchPermission` authorizing the whole `[approve, action]` sequence). A normal `IPermission` cannot authorize a batch. Details: `.agents/skills/sail-mandates/references/approvals.md`
 - Never authorize (attach) a permission before `forge test` and `sailor mandate simulate` both pass against samples derived from the user's strategy
+- **Register ≠ configure for shared singletons.** `sailor mandate attach` only registers the address on the kernel (`isConfigured` stays `false`); the kernel denies every call until you also run `sailor mandate configure`. Stopping at `attach` is the most common trap. See `sail-templates` (reuse-flow) and `sail-template-swap`.
+- **Resolve tokens before binding them.** Never guess a token address or assume a token that exists is swap-ready. Run `scripts/resolve-token.mjs` for symbol→address+decimals+swap-readiness; a decimals mismatch (USDC 6 vs most 18) silently mis-sizes every cap, and a token with no V3 pool will fail-closed on every dispatch. Addresses are per-chain — never copy one across chains.
 - Do not pass `--args` inline JSON from PowerShell — use `--args-file` instead
 - Operator intent and the strategy's stated bounds outrank any example. If the operator asks for a bound an example omits, include it. Never let an example's shape narrow a mandate below what the operator requested

package/templates/default/scripts/quote-swap.mjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+// quote-swap.mjs — live Uniswap V3 quote via QuoterV2 + an amountOutMinimum floor.
+//
+// Takes resolved tokens + an exact amount (from resolve-token.mjs), returns the
+// expected output and a slippage-adjusted amountOutMinimum ready to embed in a
+// swap dispatch. Pure JS, no dependencies.
+//
+//   node scripts/quote-swap.mjs \
+//     --token-in  0x078D...AD6  --decimals-in  6 \
+//     --token-out 0x4200...0006 --decimals-out 18 \
+//     --amount 25000000 --fee 3000 --slippage-bps 100
+//
+// Output: one JSON object on stdout; human notes on stderr.
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+
+const CHAINS = {
+  ethereum: { chainId: 1, quoterV2: "0x61fFE014bA17989E743c5F6cB21bF9697530B21e" },
+  unichain: { chainId: 130, quoterV2: "0x385a5cf5f83e99f7bb2852b6a19c3538b9fa7658" },
+  base: { chainId: 8453, quoterV2: "0x3d4e44Eb1374240CE5F1B871ab261CD16335B76a" },
+  arbitrum: { chainId: 42161, quoterV2: "0x61fFE014bA17989E743c5F6cB21bF9697530B21e" },
+};
+
+const SEL_QUOTE = "0xc6a5026a"; // quoteExactInputSingle((address,address,uint256,uint24,uint160))
+const ADDR_ZERO = "0x" + "0".repeat(40);
+
+// ── minimal ABI encode/decode (mirrors resolve-token.mjs) ───────────────────────
+function pad32(h) {
+  h = h.toLowerCase().replace(/^0x/, "");
+  if (h.length < 64) h = "0".repeat(64 - h.length) + h;
+  return h;
+}
+function uintToHex(n) {
+  let h = n.toString(16);
+  if (h.length % 2) h = "0" + h;
+  return pad32(h);
+}
+function encodeQuoteCall(tokenIn, tokenOut, amountIn, fee) {
+  return SEL_QUOTE + pad32(tokenIn) + pad32(tokenOut) + uintToHex(amountIn) + uintToHex(BigInt(fee)) + uintToHex(0n);
+}
+function decodeUint(hex, word = 0) {
+  const h = hex.toLowerCase().replace(/^0x/, "");
+  const w = h.slice(word * 64, word * 64 + 64);
+  return w ? BigInt("0x" + w) : 0n;
+}
+
+async function ethCall(rpc, to, data, from = ADDR_ZERO) {
+  const res = await fetch(rpc, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_call", params: [{ to, data, from }, "latest"] }),
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!res.ok) throw new Error(`eth_call HTTP ${res.status}`);
+  const json = await res.json();
+  if (json.error) throw new Error(`QuoterV2 reverted: ${JSON.stringify(json.error)}`);
+  if (!json.result) throw new Error("eth_call returned no result");
+  return json.result;
+}
+
+function readSailEnv() {
+  const p = resolvePath(process.cwd(), ".sail", ".env.local");
+  const out = {};
+  if (existsSync(p)) {
+    for (const line of readFileSync(p, "utf8").split("\n")) {
+      const m = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/);
+      if (m) out[m[1]] = m[2].replace(/^["']|["']$/g, "");
+    }
+  }
+  return out;
+}
+function readSailConfig() {
+  const p = resolvePath(process.cwd(), ".sail", "config.json");
+  if (!existsSync(p)) return {};
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function resolveChain(chainFlag) {
+  if (chainFlag) {
+    const c = CHAINS[chainFlag.toLowerCase()];
+    if (c) return { name: chainFlag.toLowerCase(), ...c };
+    for (const [name, cfg] of Object.entries(CHAINS)) if (String(cfg.chainId) === String(chainFlag)) return { name, ...cfg };
+    throw new Error(`Unknown chain "${chainFlag}". Known: ${Object.keys(CHAINS).join(", ")}`);
+  }
+  const env = readSailEnv();
+  const cfg = readSailConfig();
+  const id = env.CHAIN_ID ?? cfg.chainId;
+  if (id) for (const [name, c] of Object.entries(CHAINS)) if (String(c.chainId) === String(id)) return { name, ...c };
+  throw new Error(`Could not resolve chain. Pass --chain <${Object.keys(CHAINS).join("|")}>.`);
+}
+function resolveRpc(chain, rpcFlag) {
+  if (rpcFlag) return rpcFlag;
+  const env = readSailEnv();
+  // Mirror resolve-token.mjs / packages/cli getRpcUrl(): named var, then chainId-keyed
+  // var (RPC_URL_8453 — written by the UI / used by multi-chain projects), then generic.
+  const nameVar = `${chain.name.toUpperCase().replace("-", "_")}_RPC_URL`;
+  const idVar = `RPC_URL_${chain.chainId}`;
+  return env[nameVar] ?? env[idVar] ?? env.RPC_URL ?? null;
+}
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.replace(/^--/, "").replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+      out[key] = argv[++i];
+    }
+  }
+  return out;
+}
+
+function fmtUnits(valueBI, decimals) {
+  // bigint base units → human string, preserving precision
+  const neg = valueBI < 0n;
+  let s = (neg ? -valueBI : valueBI).toString().padStart(decimals + 1, "0");
+  const intPart = s.slice(0, s.length - decimals);
+  const fracPart = decimals > 0 ? s.slice(s.length - decimals) : "";
+  const trimmedFrac = fracPart.replace(/0+$/, "");
+  let out = trimmedFrac.length ? `${intPart}.${trimmedFrac}` : intPart;
+  if (decimals > 0 && !trimmedFrac) out = `${intPart}.0`;
+  return (neg ? "-" : "") + out;
+}
+
+function errMsg(e) {
+  return e && typeof e.message === "string" ? e.message : String(e);
+}
+
+async function main() {
+  const a = parseArgs(process.argv.slice(2));
+  if (process.argv.length <= 2 || a.help) {
+    process.stderr.write(
+      "Usage: quote-swap.mjs --token-in <addr> --token-out <addr> --amount <baseUnits>\n" +
+        "  --decimals-in <n> --decimals-out <n> --fee <tier> [--slippage-bps <n>] [--chain <>] [--rpc URL]\n",
+    );
+    process.exit(process.argv.length <= 2 ? 1 : 0);
+  }
+
+  const need = ["tokenIn", "tokenOut", "amount", "decimalsIn", "decimalsOut", "fee"];
+  for (const k of need) if (a[k] === undefined) throw new Error(`Missing --${k.replace(/([A-Z])/g, "-$1").toLowerCase()}`);
+
+  const chain = resolveChain(a.chain);
+  const rpc = resolveRpc(chain, a.rpc);
+  if (!rpc) throw new Error(`No RPC for ${chain.name}. Pass --rpc or set RPC_URL in .sail/.env.local.`);
+
+  const tokenIn = a.tokenIn;
+  const tokenOut = a.tokenOut;
+  const amountIn = BigInt(a.amount);
+  const fee = Number(a.fee);
+  const decimalsIn = Number(a.decimalsIn);
+  const decimalsOut = Number(a.decimalsOut);
+  const slippageBps = a.slippageBps !== undefined ? Number(a.slippageBps) : 100; // default 1%
+  if (!Number.isInteger(slippageBps) || slippageBps < 0 || slippageBps > 10_000) {
+    throw new Error(`--slippage-bps must be an integer in [0, 10000], got "${a.slippageBps}".`);
+  }
+
+  const data = encodeQuoteCall(tokenIn, tokenOut, amountIn, fee);
+  const ret = await ethCall(rpc, chain.quoterV2, data);
+  const amountOut = decodeUint(ret, 0); // word 0
+  const gasEstimate = decodeUint(ret, 3); // word 3
+
+  if (amountOut === 0n) {
+    throw new Error(
+      `QuoterV2 returned 0 for ${amountIn} (tokenIn) → tokenOut at fee ${fee}. The pool is empty or does not exist at this tier.`,
+    );
+  }
+
+  const amountOutMinimum = (amountOut * BigInt(10_000 - slippageBps)) / 10_000n;
+  // price = (amountOut / 10^decOut) / (amountIn / 10^decIn) → units of tokenOut per tokenIn
+  const humanIn = fmtUnits(amountIn, decimalsIn);
+  const humanOut = fmtUnits(amountOut, decimalsOut);
+  const humanMin = fmtUnits(amountOutMinimum, decimalsOut);
+
+  const out = {
+    tokenIn,
+    tokenOut,
+    decimalsIn,
+    decimalsOut,
+    amountIn: amountIn.toString(),
+    amountOut: amountOut.toString(),
+    amountOutMinimum: amountOutMinimum.toString(),
+    slippageBps,
+    fee,
+    chain: chain.name,
+    chainId: chain.chainId,
+    gasEstimate: gasEstimate.toString(),
+    human: {
+      amountIn: humanIn,
+      amountOut: humanOut,
+      amountOutMinimum: humanMin,
+      price: `${humanOut} out per ${humanIn} in`,
+    },
+    note: "amountOutMinimum is the slippage floor — embed it in the swap calldata the agent dispatches.",
+  };
+
+  process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+  process.stderr.write(
+    `\nQuote: ${humanIn} in → ${humanOut} out  (fee ${fee})\n` +
+      `  amountOutMinimum (${slippageBps / 100}% slip): ${humanMin}\n` +
+      `  gas estimate: ${gasEstimate}\n`,
+  );
+}
+
+main().catch((err) => {
+  process.stderr.write(`\nquote-swap failed: ${errMsg(err)}\n`);
+  process.exit(1);
+});