@dev.sail.money/sailor 1.3.0-98 → 1.4.0-242

package/templates/default/.agents/skills/sail-templates/references/config-schemas.md

@@ -0,0 +1,139 @@
+# Config schemas & enforced invariants — authoritative (from source)
+
+Each shared template stores per-account config under `mapping(address => …)` and decodes a
+`configure(...)` blob in `_applyConfig`. The tuples below are taken **directly from
+`Protocol/contracts/templates/*.sol`** and are the source of truth — encode with
+`abi.encode(...)` in that exact order. (The `@sail/sdk/templates` builders track a
+previously-deployed set; verify a builder's params match the tuple here before using it.)
+
+All caps/amounts are in the relevant token's **base units**. Every template runs under the
+kernel's `staticcall` + gas cap + fail-closed semantics: a revert ⇒ deny.
+
+---
+
+## SwapPermission
+```
+abi.encode(address[] routers, address[] tokensIn, address[] tokensOut,
+           uint256 maxAmountPerTx, uint256 maxSlippageBps,
+           address priceOracle, uint256 maxPriceAgeSec)
+```
+Selectors: `0x414bf389` (V3 `exactInputSingle` w/ deadline), `0x04e45aaf` (V3-02 no deadline),
+`0x38ed1739` (V2 `swapExactTokensForTokens`). Invariants: `value == 0` (native value rejected);
+`target ∈ routers`; **`tokenIn != tokenOut` / `path[0] != path[last]`** (self-routes denied — a
+round-trip would burn AMM fees while an oracle reporting base==quote clears the band);
+`tokenIn`/`path[0] ∈ tokensIn`; `tokenOut`/`path[last] ∈ tokensOut`;
+`recipient`/`to == account`; `amountIn ≤ maxAmountPerTx`; **oracle slippage band ALWAYS enforced**.
+The oracle is **mandatory** (contract `v2`): `_applyConfig` reverts `OracleRequired` if
+`priceOracle == 0`, `MissingPriceAge` if `maxPriceAgeSec == 0`, and `SlippageBpsTooLarge` if
+`maxSlippageBps > 9_999`. `maxSlippageBps == 0` ⇒ zero tolerance (strictest), NOT a bypass.
+`priceOracle` is an `IOracle` adapter (`getPrice(base,quote) → (price, dec, updatedAt)`), not a raw
+feed; dust trades whose floor truncates to 0 are denied. V2 intermediate hops are NOT checked.
+(For no-oracle tokens use `SwapPermissionNoOracle`.)
+
+## SwapPermissionNoOracle
+```
+abi.encode(address[] routers, address[] tokensIn, address[] tokensOut,
+           uint256 maxAmountPerTx, ReferencePool[] referencePools)
+
+struct ReferencePool { address tokenIn; address tokenOut; address pool;
+                       PoolKind kind /* 0=V2, 1=V3 */; uint256 toleranceBps; }
+```
+Same selectors and structural checks as `SwapPermission` (`0x414bf389`, `0x04e45aaf`,
+`0x38ed1739`): `target ∈ routers`; `tokenIn`/`path[0] ∈ tokensIn`; `tokenOut`/`path[last] ∈
+tokensOut`; `recipient`/`to == account`; `amountIn ≤ maxAmountPerTx`. **Differs** from
+`SwapPermission` in the price judgement: instead of an oracle band it enforces a **pool-referenced
+hallucination band** — `amountOutMin` must be ≥ the output implied by the live spot price of the
+operator-named `referencePool` for that directional pair, minus `toleranceBps`, and `amountOutMin
+> 0`. Config-time invariants (`_applyConfig` reverts ⇒ configure fails): `toleranceBps ≤ 5_000`
+(50% max); `pool != 0`; pool's `token0()`/`token1()` must match the pair (orientation precomputed);
+**strict coverage** — every non-self directional `(tokenIn, tokenOut)` combination MUST have a
+reference pool or configure reverts `MissingReferencePool`. Fail-closed at evaluate if the pool is
+missing/unreadable/illiquid or the floor truncates to zero.
+
+> ⚠️ **NOT manipulation-resistant.** The reference is a single pool's LIVE spot price, movable
+> within the same transaction (flash-loan / sandwich). This band only catches an *honest* mistake
+> (a confused agent quoting a wildly wrong price); it is NOT slippage protection. For
+> manipulation-resistant protection use the oracle-gated `SwapPermission`. Cap is per-tx, not
+> cumulative.
+
+## BorrowPermission
+```
+abi.encode(address[] protocols, address[] assets, uint256 maxAmountPerTx,
+           uint256 maxLtvBps, address collateralOracle, address borrowOracle,
+           uint256 maxPriceAgeSec)
+```
+Selectors: Aave `borrow(address,uint256,uint256,uint16,address)` (variable-rate only —
+`rateMode != 2` denies; stable-rate debt is rejected), Morpho **Optimizer/Morpho-Aave**
+`borrow(address,uint256,address,address)` (NOT Morpho Blue — its ABI differs and simply won't
+match, i.e. fails closed), Compound `borrow(uint256)` (target is the cToken; the underlying is
+resolved via `cToken.underlying()` and both the allowlist and LTV are underlying-denominated —
+targets with no `underlying()`, e.g. cETH, are denied). Invariants: `protocols`/`assets` must be
+non-empty with no zero addresses (`EmptyAllowlist`/`ZeroAddress` revert otherwise);
+`target ∈ protocols`; `asset ∈ assets`; `amount ≤ maxAmountPerTx`; `onBehalfOf`/`receiver ==
+account`. **Oracle modes:** zero oracles ⇒ amount-cap-only (no LTV ceiling applied at all, despite
+`maxLtvBps` being stored); both oracles set ⇒ `_ltvCheck` enforces the LTV bound. Exactly one
+oracle set reverts `OracleConfigInconsistent` at configure — it's an all-or-nothing pair.
+
+## TransferPermission
+```
+abi.encode(address[] allowedRecipients, address[] allowedTokens, uint256 maxAmountPerTx)
+```
+Selectors: `0xa9059cbb` `transfer`, `0x23b872dd` `transferFrom`. Invariants: `value == 0`;
+`allowedRecipients`/`allowedTokens` must be non-empty with no zero addresses
+(`EmptyAllowlist`/`ZeroAddress` revert at configure otherwise); `target (token) ∈ allowedTokens`;
+`to ∈ allowedRecipients`; `amount ≤ maxAmountPerTx`;
+**`transferFrom` requires `from == account`** (stricter than the old TransferTarget).
+Max 50 entries per allowlist.
+
+## DepositPermission
+```
+abi.encode(address[] targets, address[] tokens, uint256 maxAmountPerTx)
+```
+Selectors: `deposit(uint256,address)` (ERC-4626), `mint(uint256,address)`,
+`deposit(address,uint256,address,uint16)` (Aave v2), `supply(address,uint256,address,uint16)`
+(Aave v3). Invariants: `value == 0`; `targets`/`tokens` must be non-empty with no zero addresses
+(`EmptyAllowlist`/`ZeroAddress` revert at configure otherwise); `target ∈ targets`; token
+allowlist enforced (Aave: the `asset` arg; ERC-4626: `target` itself must be in `tokens`);
+`amount`/`shares ≤ maxAmountPerTx`; `receiver`/`onBehalfOf == account`. `mint` cap is in
+**shares** — account for share price.
+
+## WithdrawPermission
+```
+abi.encode(address[] tokens, address allowedRecipient, uint256 maxAmountPerTx)
+```
+Selectors: `0xa9059cbb` `transfer`, `0x23b872dd` `transferFrom`. Invariants: `value == 0`;
+`tokens` must be non-empty and `allowedRecipient` non-zero, with no zero-address tokens
+(`EmptyAllowlist`/`ZeroAddress` revert at configure otherwise); `target (token) ∈ tokens`;
+`to == allowedRecipient` (single address per config); `amount ≤ maxAmountPerTx`;
+**`transferFrom` requires `from == account`**. To change the recipient, `reconfigure` with a new
+blob.
+
+## ApproveAndCallBatchPermission
+```
+abi.encode(Config{
+  address[]       tokens; address[] spenders; ConsumingPair[] consumingPairs;
+  uint256[]       maxApprovalAmounts; bool requireAmountMatch; bool allowUnconstrainedRecipient;
+})
+struct ConsumingPair { address target; bytes4 selector; }
+```
+ABI tuple: `(address[],address[],(address,bytes4)[],uint256[],bool,bool)`. `consumingPairs` is a
+**struct array**, not two flat arrays — each `(target, selector)` is bound together, so a selector
+is authorised only on its paired target. Authorises exactly the 3-call batch:
+`approve(spender, amount)` → consuming call → `approve(spender, 0)`. Invariants: `tokens`,
+`spenders`, and `consumingPairs` must each be non-empty and contain no zero addresses/selectors
+(`EmptyAllowlist` reverts otherwise); token ∈ `tokens` with `amount ≤ maxApprovalAmount[token]`;
+`spender ∈ spenders`; `(target, selector)` ∈ `consumingPairs`; the pre-batch allowance on
+`(token, spender)` must be zero; the consuming call must target the approved `spender` and pull the
+approved `token`; allowance reset to zero in the same batch; if `requireAmountMatch`, the consuming
+call's leading `uint256` arg must equal the approve amount. `maxApprovalAmounts` is index-parallel
+with `tokens` (length mismatch reverts).
+
+> ⚠️ **Field name/polarity — `allowUnconstrainedRecipient`, NOT `requireRecipientIsAccount`.**
+> The field is an **opt-out**, default-safe: `false` (the default, i.e. an omitted/zero-value
+> bool) means the consuming call's output recipient is decoded and **must equal the account** —
+> the safe posture. `true` is a deliberate opt-out that leaves the recipient **unconstrained**.
+> Setting the bool `true` thinking it "requires/pins the recipient" gets the **opposite**
+> behaviour on-chain. Either way, the recipient (and the consumed asset) can only be decoded for
+> selectors in the fixed-offset set below — any other selector is denied under the default pin:
+> `swapExactTokensForTokens`, V3 `exactInputSingle` (both SwapRouter layouts), Aave V2/V3
+> `deposit`/`supply`, ERC-4626 `deposit`/`mint`.

package/templates/default/.agents/skills/sail-templates/references/reuse-flow.md

@@ -0,0 +1,139 @@
+# Reuse-first flow — register + configure a shared template
+
+The whole point of a **shared** template: the logic is already deployed, so you skip the
+deploy entirely. You give one SMA its own private config inside the singleton's
+`mapping(address => …)` and register it on the kernel.
+
+> **Two steps, not one (today).** The on-chain **intended** design is a single signed call —
+> `MandateFactory.attach(account, template, params, configureDeadline, configureSig, kernelSig)`
+> — that registers the template on the kernel AND writes its per-account config together.
+> **The shipped `sailor` CLI does not implement that combined call yet.** `sailor mandate
+> attach` performs **only the kernel registration** (`RegisterPermission` / the batch
+> `registerPermissions`); it never calls `configure`/`configureDirect`, carries no `--params`,
+> and builds no `Configure` EIP-712 signature. The SDK's `client.mandate.attach(...)` is a
+> `notImplemented()` stub.
+>
+> A registered-but-unconfigured singleton has `isConfigured == false`, so the kernel's
+> `evaluate()` **denies every call** — a registered-but-dead permission. You MUST configure
+> separately, with `sailor mandate configure` (step 4 below). The flow below describes what
+> actually works now.
+
+## On-chain mechanics (`MandateFactory` + `ConfigurablePermission`)
+
+These are the **on-chain** entry points — the contract truth for what the combined/intended
+flow does. The shipped CLI uses a subset of them today (registration only); the configure
+half is driven directly for now.
+
+Registration (kernel side — what `sailor mandate attach` does today):
+
+| Function | Use |
+|---|---|
+| kernel `registerPermission(account, permission, deadline, sig)` | Register one template address on an SMA |
+| kernel `registerPermissions(account, permissions[], deadline, sig)` | Register several in one signature (the `--address a,b,c` batch path) |
+| kernel `revokePermissions(account, permissions[], deadline, sig)` | Remove (`sailor mandate revoke`) |
+
+Configuration (singleton side — the half the CLI does NOT do today):
+
+| Function | Use |
+|---|---|
+| `configure(account, params, deadline, sig)` | Set per-account config, gated by an EIP-712 `Configure(account, paramsHash, nonce, deadline, epoch)` signature from the account's `permissionSigner` (ECDSA or ERC-1271). |
+| `configureDirect(account, params)` | Set per-account config, gated by `msg.sender == permissionSigner`. The working path when the owner IS the permissionSigner — a plain owner tx, no signature. |
+| `reconfigure(...)` | Intended batch re-config path (`MandateFactory.reconfigure`); functionally `configure` again with a new blob. |
+
+The intended combined call (`MandateFactory.attach`) and its batch/replace/detach siblings are
+defined on the factory contract; they are the target state for a future one-step CLI command,
+not something the current CLI drives.
+
+The kernel evaluates a registered permission via `staticcall` with a per-permission gas cap;
+a revert or over-gas is treated as `false` (fail-closed), never a kernel revert.
+
+## The steps (as they work today)
+
+### 1. Discover the address
+```bash
+node SKILLS/sail-templates/catalog.mjs --chain <id>
+```
+The address comes from [`deployed.json`](../deployed.json). **If the template isn't deployed on
+your chain yet** (e.g. `SwapPermissionNoOracle` is not deployed anywhere), that's the
+prerequisite: deploy the singleton once (Protocol team / `DeploySharedTemplates`) and record
+its address there. A template address is only meaningful paired with that chain's kernel.
+
+### 2. Build the config blob
+Encode the config tuple **exactly as the contract's `_applyConfig` decodes it** — the
+authoritative tuples are in [config-schemas.md](config-schemas.md). Use `abi.encode(...)` in
+that order, or the typed builder under `@sail/sdk/templates` **only after** verifying its param
+tuple equals the source tuple (the SDK builders track a previously-deployed set and may differ
+from these source contracts):
+```ts
+import { boundedSwapTemplate } from "@sail/sdk/templates"; // verify params vs config-schemas.md first
+
+const params = { routers, tokensIn, tokensOut, maxAmountPerTx, maxSlippageBps,
+                 priceOracle, maxPriceAgeSec };
+const blob = boundedSwapTemplate.encoder.encode(params);
+
+// Always surface the human-readable summary + warnings to the user first:
+const explanation = boundedSwapTemplate.explainer.explain(params);
+```
+
+> ⚠️ **Encoding gotcha (fails closed).** Templates do NOT all encode the same way.
+> `TransferPermission` / `WithdrawPermission` / `DepositPermission` decode **flat top-level
+> params** (`abi.encode(address[], address[], uint256)`). `ApproveAndCallBatchPermission`
+> decodes a **single wrapped struct** (`abi.encode(Config{…})`) — its blob starts with a `0x20`
+> tuple-offset word. Wrapping a flat-params blob (or vice-versa) reverts at configure. **Always
+> round-trip-decode the blob and `cast call`-simulate `configureDirect` before sending.**
+
+### 3. Register the singleton on the kernel (does NOT configure)
+```bash
+sailor mandate attach --address <SHARED_ADDRESS> --sma <SMA> --label "<primitive>"
+```
+This builds and submits the kernel `RegisterPermission` (or `registerPermissions` for a
+comma-separated `--address` list). It does NOT call `configure`. After this step the address is
+in `getPermissions(<SMA>)` but `isConfigured(<SMA>) == false`, so every dispatch is still
+denied. Proceed to step 4.
+
+### 4. Configure the per-account bounds (the half that makes it live)
+When the owner IS the SMA's `permissionSigner` (the default Sailor onboarding), drive
+`configureDirect(account, <config blob>)` as a plain owner transaction — `msg.sender ==
+permissionSigner` holds and no EIP-712 signature is needed — via the shipped command:
+```bash
+sailor mandate configure --address <SHARED_ADDRESS> --sma <SMA> \
+  --template <TemplateName> --args-file ./config.json
+# or with a pre-encoded blob:
+sailor mandate configure --address <SHARED_ADDRESS> --sma <SMA> --params <0x-blob>
+```
+It does, in order:
+1. **Pre-flight (no gas):** an `eth_call` simulation of `configureDirect` from `permissionSigner`. A revert here means the config is invalid before any gas is spent — fix the blob (see the encoding gotcha) and retry. Pass `--simulate-only` to stop here.
+2. **Send it:** pushes the `configureDirect` call to the owner wallet as an `arbitrary-tx` request through the signing station; the owner approves in the browser and the owner wallet sends the transaction.
+3. **Verify:** reads `isConfigured(<SMA>)` on the singleton and errors if it isn't `true`.
+
+If the owner is **not** the `permissionSigner` (e.g. a separate mandate-signer / multisig), use
+`configure(account, params, deadline, sig)` instead: construct the EIP-712 `Configure` digest
+(bound to the kernel's current `registrationEpoch`), have the `permissionSigner` sign it, and
+submit. `sailor mandate configure` does not build this signature for you — that path is still
+manual.
+
+### 5. Verify off-chain (no gas)
+Prove it accepts what you want and rejects what you don't, before trusting it:
+```bash
+sailor mandate simulate --address <SHARED_ADDRESS> --sma <SMA> \
+  --target <router> --calldata <hex> --expect pass
+# or a batch file:
+sailor mandate simulate --address <SHARED_ADDRESS> --sma <SMA> --calls ./probe.json
+```
+
+### 6. Reconfigure when bounds change
+New cap or allowlist? Re-encode the blob and repeat step 4 (`sailor mandate configure --force`,
+or the manual `configure` signature path) — the address stays registered, no re-attach. (On-chain
+`MandateFactory.reconfigure` is the intended batch path for this.)
+
+## Gotchas
+
+- **Unconfigured = deny.** A freshly-registered shared template with no `configure()` has
+  `isConfigured == false` and denies everything. Register AND configure — don't stop at
+  `sailor mandate attach`.
+- **`sailor mandate attach` is register-only.** It does not configure. This is the single most
+  common trap; see steps 3 and 4.
+- **Caps are in base units** of the relevant token (e.g. `25_000_000` = 25 USDC).
+- **permissionSigner is the trust anchor** for config. In production use a multisig / timelock
+  — whoever holds it can widen allowlists and caps on every account they signed for.
+- The shared singletons are **unaudited examples**. Simulate (Step 5) is not optional.

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/.env.example

@@ -18,3 +18,12 @@ CHAIN_ID=8453
 
 # Optional: non-interactive passphrase (CI, GitHub Actions, launchd, systemd)
 # SAIL_PASSPHRASE=change-me-to-a-strong-passphrase
+
+# Advanced — exposing the dashboard/API beyond localhost.
+# The UI server binds 127.0.0.1 (local only) by default. Its key-management
+# endpoints are UNAUTHENTICATED, so only expose them behind your own auth
+# (a reverse proxy with basic-auth, or a private tailnet — never the open internet).
+# SAILOR_HOST=0.0.0.0                                   # bind all interfaces (LAN / behind a domain)
+# SAILOR_TRUST_PROXY=1                                  # hop count (or IP allowlist) when behind a reverse proxy, so the rate limit keys on the real client IP (else it's a single global bucket)
+# SAILOR_CORS_ORIGINS=https://sail.example.ts.net       # extra allowed browser origins (comma-separated)
+# SAILOR_RATE_LIMIT_PER_MIN=100                         # throttle /api/signer + /api/onboard/generate-key (default 100; or set "rateLimitPerMin" in .sail/config.json)

package/templates/default/AGENTS.md

@@ -1,26 +1,120 @@
-This is **your** Sailor project — for defining and running your agent's strategy. It is yours to edit; `sailor update` will not overwrite it.
+This guide is for agents operating a scaffolded Sailor project. (Contributors to the Sailor codebase: see AGENTS.md at the monorepo root.)
 
-**How to operate Sailor** — set up the environment, onboard, build mandates, run the agent — lives in the skills below, not in this file. Start with `sail-overview`. The operating model, the onboarding flow, and the safety rules are there, so this file stays about *your* strategy.
+> **This is a standalone project, not a clone of the Sailor repo.** `sailor init` scaffolds an independent directory with its own (or no) git history — it does not share history with `github.com/sail-money/Sailor`. Do **not** add that repo as a remote or `git pull origin/main` from it: you'll hit "refusing to merge unrelated histories" and add/add conflicts on `AGENTS.md`, `README.md`, `package.json`, `.gitignore`, and `docs/`. To update the tooling, bump the `@sail.money/sailor` dependency (`npm i @sail.money/sailor@latest`), not by pulling the source repo.
 
-> Standalone project — not a clone of the Sailor repo. To update the tooling, bump the dependency (`npm i @sail.money/sailor@latest`); do not add that repo as a git remote.
+---
+
+Sail Protocol is infrastructure for onchain Separately Managed Accounts run by AI agents. You create an SMA, keep full custody, and define exactly what your agent can do — cryptographically bound permissions you approve and can always revoke. The agent executes within those bounds on every transaction. It cannot exceed them.
+
+I'm Sailor, the operator that sets this up. I'll help you create your SMA, build the permissions that bound your agent, and get your strategy running.
+
+Here's where we're headed:
+
+1. Deploy your SMA and create your agent wallet
+2. Define your strategy
+3. Build, test, and sign your mandate
+4. Run your agent — locally or on a schedule
+5. Extend with notifications and a custom dashboard
+
+Ready? Say **start** and I'll open the setup interface in your browser.
+
+---
+
+# Instructions for the assistant
+
+Everything below is for you, the assistant. The user sees the welcome above; you follow the flow below.
+
+## Your job in mandate design
+
+When designing a mandate, your job is to help the operator express the **tightest, most complete mandate that captures their strategy's intent** — not the smallest one that compiles. Enumerate every constraint the strategy implies *and* every one the protocol can express for the venues involved; explain what each protects against. Separate them into **safety bounds** (caps, allowlists, slippage floors — loss/theft surfaces, enforced on-chain by default) and **strategy parameters** (cadence, schedule, rebalance timing — how the strategy runs, not a safety surface, so they live in agent logic). A stated strategy parameter is still required: wire it as an agent-side guard and confirm it before go-live — don't try to force it on-chain. A minimal mandate that merely compiles is a failure mode; the goal is the tightest mandate that expresses the strategy.
+
+## Voice
+
+You are Sailor. Serious, precise, confident. No hype, no emojis, no exclamation marks. Explain *why*, not just *what* — the user is moving real funds. Use user-facing terms (SMA, mandate, permissions, agent wallet, owner). Assume crypto-native; teach the Sail-specific model.
+
+Never overstate safety: custody is protected, but a mandate is only as correct as its permission contracts.
+
+## Authorization rule
+
+During **setup**, always ask before anything that costs gas. Once the **mandate is signed and the agent is running**, the mandate is the authorization — the agent transacts autonomously. Do not ask per-dispatch.
+
+## 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` 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.
+
+## Stage flow — track to completion
+
+The five stages above are a checklist you drive to completion, not a list you mention once. Track which stages are done (read `.sail/` to infer progress) and lead the operator to the next incomplete stage. The flow is not finished when the agent goes live — it is finished when stage 5 has been offered.
+
+- [ ] 1. SMA + agent wallet deployed
+- [ ] 2. Strategy defined
+- [ ] 3. Mandate built, tested, signed
+- [ ] 4. Agent running (locally or scheduled)
+- [ ] 5. Extend — notifications and a custom dashboard
+
+After the agent is live (stage 4), **offer stage 5 by default**: one line on run/transaction notifications and one line on a strategy-specific dashboard, then ask if the operator wants either. Skipping stage 5 requires an explicit operator opt-out — never drop it silently. Hand off to **sail-extend** to build whatever they accept.
+
+## Project state — read `.sail/`, never ask
+
+Determine the user's progress by reading `.sail/` — do not ask; read it.
+
+| File | What it tells you |
+|---|---|
+| `config.json` | Project manifest: name, `chainId` (null until the user picks a chain), contract addresses |
+| `account.json` | Active SMA: safe, owner, manager (agent wallet), chainId, saltNonce, deployedChains |
+| `mandate.json` | The signed mandate the runner executes against (absent = not signed yet) |
+| `keys/` | Encrypted geth-v3 keystores (agent wallet, mandate signer) — never read or print contents |
+| `state/mandates.json` | Append-only record of every permission deployed/attached from this project |
+| `runtime/` | Live process state: `ui.json` (dashboard pid/port), `server.json` (signing station url/pid) |
+| `activity.jsonl` | Unified activity log — agent dispatches and owner signing decisions, one JSON per line |
+| `.env.local` | RPC_URL / CHAIN_ID / per-chain RPC vars / SAIL_PASSPHRASE — never commit or print |
 
 ## Skills
 
-Detailed procedures live in skills under `.agents/skills/`. If your tooling does not auto-discover them, open the files directly — they are plain markdown.
+Detailed procedures live in skills. If your tooling does not auto-discover skills, open these files directly — they are plain markdown.
 
 | Skill | Load when | Path |
 |---|---|---|
-| sail-setup | First-time environment readiness — dependencies, install mode, then `sailor init` | `.agents/skills/sail-setup/SKILL.md` |
-| sail-overview | How Sailor works, which skill to use when, and the safety invariants — read this first | `.agents/skills/sail-overview/SKILL.md` |
-| sail-sailor | How to invoke sailor — local vs Docker, installMode detection, all CLI commands, `sailor update` | `.agents/skills/sail-sailor/SKILL.md` |
-| sail-onboarding | New project setup, resuming a partially set-up project, or running a CLI command | `.agents/skills/sail-onboarding/SKILL.md` |
+| 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-mandates | Designing, authoring, testing, deploying, or authorizing permission contracts | `.agents/skills/sail-mandates/SKILL.md` |
-| sail-transactions | Building dispatches, running the agent, or debugging a transaction | `.agents/skills/sail-transactions/SKILL.md` |
-| sail-automation | Running the agent unattended — GitHub Actions, self-hosted runner, Docker, or daemon | `.agents/skills/sail-automation/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 (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` |
 
-## Your strategy
+**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
 
-Use the space below for notes about *your* strategy — what the agent should do, its bounds, and any project-specific context. This section is yours.
+- Do not present the welcome and immediately launch the UI — wait for the second "start"
+- Do not describe, mention, or present any code in `src/` or `examples/` as the user's strategy — treat strategy definition as a blank slate; ask what they want
+- Do not ask a running agent to confirm individual dispatches within its mandate
+- Do not put an owner key in the terminal — owner signing is browser-only
+- Do not hand-roll dispatch EIP-712 signatures — use `buildDispatchSignature` from the SDK
+- Do not hardcode the dispatch model — detect it on-chain with `detectKernelCapabilities`
+- Do not present example permissions as audited or as a supported menu
+- 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/docs/PERMISSION_MODEL.md

@@ -89,5 +89,5 @@ Run `sailor doctor` (read-only, no gas, no keys):
 - on a conjunctive kernel, **probes each permission for pass-through** and flags any
   that would brick dispatch.
 
-See [AGENT_PLAYBOOK.md](../AGENT_PLAYBOOK.md) for the operational decision tree and the
-revert failure-mode catalog.
+See [AGENTS.md](../AGENTS.md) (and the skills it routes to under `.agents/skills/`)
+for the operational decision tree and the revert failure-mode catalog.

package/{examples → templates/default/examples}/custom-mandate/.sail/contracts/interfaces/IPermission.sol

@@ -10,6 +10,10 @@ struct Context {
     uint256 value;
     uint256 blockTimestamp;
     uint256 blockNumber;
+    /// @dev Kernel registrationEpoch(account, permission) at dispatch. Configurable
+    ///      permissions fail closed on a mismatch with the epoch stamped at configure()
+    ///      time; permissions without post-deploy configuration can ignore it.
+    uint256 configEpoch;
 }
 
 interface IPermission {