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

package/templates/default/.agents/skills/sail-template-swap/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: sail-template-swap
+description: Gate an SMA's DEX swaps by REUSING the shared SwapPermission singleton (Protocol/contracts/templates/SwapPermission.sol) — register + configure, no per-SMA deploy. Use for a bounded swap / DCA mandate on Uniswap V3, V3-02, or V2 with router + token-in/out allowlists, a per-tx cap, and a MANDATORY oracle slippage band (priceOracle is required — for no-oracle tokens use sail-template-swap-no-oracle). For the LI.FI aggregator or Pendle, author a bespoke permission via sail-mandates. NOTE: `sailor mandate attach` only registers — you must also configure per-account (see steps).
+compatibility: A Sailor project (`@sail/sdk`, `sailor` CLI). Requires SwapPermission deployed on the target chain (recorded in sail-templates/deployed.json); run sail-templates first.
+metadata:
+  workspace: sailor-harness
+  classification: generic
+  status: draft
+  origin: Protocol/contracts/templates/SwapPermission.sol
+---
+
+# sail-template-swap — bounded DEX swap via the shared singleton
+Reuse the shared **`SwapPermission`** singleton instead of authoring/deploying a swap contract.
+Register its address on the SMA and `configure()` your routers, token allowlists, cap, and
+
+slippage. Family overview + flow: [`sail-templates`](../sail-templates/SKILL.md).
+
+## What it enforces (per account, from source)
+
+Supported selectors (any other ⇒ `false`):
+
+| Selector | Function | Venue |
+|---|---|---|
+| `0x414bf389` | `exactInputSingle((tokenIn,tokenOut,fee,recipient,deadline,amountIn,amountOutMinimum,sqrtPriceLimitX96))` | Uniswap V3 SwapRouter |
+| `0x04e45aaf` | `exactInputSingle((tokenIn,tokenOut,fee,recipient,amountIn,amountOutMinimum,sqrtPriceLimitX96))` | Uniswap V3 SwapRouter02 |
+| `0x38ed1739` | `swapExactTokensForTokens(amountIn,amountOutMin,path[],to,deadline)` | Uniswap V2 Router |
+
+Invariants: `ctx.value == 0` (native value rejected — ERC-20→ERC-20 only); `target ∈ routers`;
+**`tokenIn != tokenOut` / `path[0] != path[last]`** (self-routes denied — a round-trip burns AMM
+fees while an oracle reporting base==quote would otherwise clear the band); `tokenIn`/`path[0] ∈
+tokensIn`; `tokenOut`/`path[last] ∈ tokensOut`; `recipient`/`to == SMA` (funds can't leave the
+account); `amountIn ≤ maxAmountPerTx`; **oracle band ALWAYS enforced** (the oracle is
+mandatory — see below): `amountOutMin ≥ amountIn × price/10^dec ×
+(10_000 − maxSlippageBps)/10_000`. Dust trades whose computed floor truncates to `0` are
+**denied** (fail-closed).
+
+> **⛔ The oracle is MANDATORY (contract `v2`, hardened in PR #45).** `_applyConfig` reverts
+> `OracleRequired()` if `priceOracle == 0` and `MissingPriceAge()` if `maxPriceAgeSec == 0`.
+> There is **no oracle-disabled mode** on this template — for tokens with no oracle use the
+> separate [`SwapPermissionNoOracle`](../sail-template-swap-no-oracle/SKILL.md) (live-pool
+> hallucination band). `maxSlippageBps == 0` is **NOT** a bypass — it means zero tolerance
+> (exact-out-or-better), the strictest valid setting. `maxSlippageBps > 9_999` reverts
+> `SlippageBpsTooLarge`.
+
+> **V2 intermediate hops are NOT checked** — only `path[0]`/`path[last]`. Restrict to V3 or
+> ensure any plausible intermediate token is acceptable.
+
+## ⚠️ Approve coverage — the hidden precondition
+
+`SwapPermission` authorizes the swap **call** only. The router pulls `tokenIn` via an ERC-20
+allowance, and the `approve(router, amount)` that establishes it is a **separate transaction this
+permission does not cover** (same rule as every protocol permission — see
+[`sail-mandates/references/approvals.md`](../sail-mandates/references/approvals.md)). A swap with
+no/insufficient allowance reverts inside the router and the tick fails. **Every** bounded swap
+needs the allowance handled — decide how at mandate-build time, not when the first tick reverts.
+
+- **Autonomous agent (DCA / rebalancer / treasury) — default:** do NOT use `SwapPermission` alone;
+  register the shared **`ApproveAndCallBatchPermission`** singleton and dispatch each tick as one
+  atomic `[approve(router, amountIn), swap, approve(router, 0)]` batch — no lingering allowance,
+  no per-tick owner signature. See [`sail-template-approve-batch`](../sail-template-approve-batch/SKILL.md).
+- **Owner in the loop per swap:** keep `SwapPermission`; the owner pre-approves the router. The
+  agent must read `allowance(SMA, router)` and **stall (never self-approve)** when it is below
+  `amountIn` — `approve()` is an owner-side action the agent cannot take on its own.
+
+## Config blob (authoritative — `config-schemas.md`)
+
+```
+abi.encode(address[] routers, address[] tokensIn, address[] tokensOut,
+           uint256 maxAmountPerTx, uint256 maxSlippageBps,
+           address priceOracle, uint256 maxPriceAgeSec)
+```
+| Field | Notes |
+|---|---|
+| `routers` | DEX routers the agent may call |
+| `tokensIn` / `tokensOut` | sell-side / buy-side allowlists (multiple out ⇒ portfolio DCA) |
+| `maxAmountPerTx` | per-swap cap, base units (e.g. `25_000_000` = 25 USDC) |
+| `maxSlippageBps` | e.g. `100` = 1%. `0` = zero tolerance (strictest), NOT a bypass. Must be `≤ 9_999`. |
+| `priceOracle` | **REQUIRED, non-zero.** An `IOracle` adapter exposing `getPrice(tokenIn, tokenOut) → (price, dec, updatedAt)` — **not** a raw Chainlink/Pyth feed. `0` reverts `OracleRequired`. |
+| `maxPriceAgeSec` | **REQUIRED, `> 0`** (oracle staleness bound). `0` reverts `MissingPriceAge`. |
+
+Size the cap and slippage floor with `uniswap-v3-quote` / `sail-pyth-prices`. The SDK
+`boundedSwapTemplate` encoder matches this tuple — fine to use after a quick verify.
+
+### Worked example — single-leg USDC → WETH
+
+Concrete params for a 25-USDC-per-swap, 1%-slippage DCA leg. These are the values you hand to
+`boundedSwapTemplate.encoder.encode(...)` to produce the `configureDirect` blob (step 3b) — they
+are **not** an args-file for a CLI command. `priceOracle` must be a **real, non-zero `IOracle`
+adapter** for this pair on this chain (`0x0` reverts):
+
+```json
+{
+  "routers":        ["0x73855d06DE49d0fe4A9c42636Ba96c62da12FF9C"],
+  "tokensIn":       ["0x078D782b760474a361dDA0AF3839290b0EF57AD6"],
+  "tokensOut":      ["0x4200000000000000000000000000000000000006"],
+  "maxAmountPerTx": "25000000",
+  "maxSlippageBps": 100,
+  "priceOracle":    "0x9d84C11626d13C5DC9540fA12A3Ff7B85Ac3c1B9",
+  "maxPriceAgeSec": 3600
+}
+```
+
+> The `priceOracle` above is the **default Unichain USDC/WETH `IOracle` adapter** — a verified
+> Uniswap V3 30-min TWAP (`UniV3TwapOracle`, pool `0x65081C…DBcF1`, 0.05% tier). It serves the
+> USDC↔WETH pair both directions and reverts `UnsupportedPair` for anything else. `catalog.mjs`
+> lists it under **IOracle adapters**; on other chains/pairs you must supply your own adapter
+> (`address(0)` reverts). Because it's a live TWAP, `updatedAt` is always current — `maxPriceAgeSec`
+> just needs to be a few minutes (e.g. `3600`).
+
+| Field | From | Notes |
+|---|---|---|
+| `routers` | SwapRouter02 for the chain (resolve-token's chain table) | V3 router; the agent calls `exactInputSingle` on it |
+| `tokensIn` | `resolve-token` | sell-side allowlist (usually just USDC) |
+| `tokensOut` | `resolve-token` | buy-side allowlist; **multiple ⇒ portfolio DCA** |
+| `maxAmountPerTx` | user's per-swap size, **base units** (string) | `"25000000"` = 25 USDC (6 dec) |
+| `maxSlippageBps` | `quote-swap`'s recommendation | `100` = 1%. `0` = zero tolerance (strictest), not a bypass. `≤ 9_999`. |
+| `priceOracle` | an `IOracle` adapter for the chain (Pyth/Chainlink-backed) | **REQUIRED, non-zero.** Must expose `getPrice(tokenIn,tokenOut)` — not the raw feed contract. |
+| `maxPriceAgeSec` | seconds | **REQUIRED, `> 0`** — staleness bound. e.g. `3600` = 1h. |
+
+> **Caps are base units.** A decimals mismatch (USDC is 6, most tokens 18) silently mis-sizes
+> every bound. `resolve-token` verified decimals on-chain — use that value, never a guess.
+> For a **portfolio DCA**, list every buy-side token in `tokensOut` (one config, many legs).
+
+## Steps
+
+> **Register ≠ configure.** `sailor mandate attach` only registers the singleton on the kernel;
+> it does NOT configure it. A registered-but-unconfigured singleton denies every call. You must
+> do both — steps 3a (register) and 3b (configure). Full mechanics + the encoding gotcha:
+> [`sail-templates` reuse-flow](../sail-templates/references/reuse-flow.md).
+
+1. **Address:** `node SKILLS/sail-templates/catalog.mjs --chain <id>` → `SwapPermission`
+   address. It's the same address on every chain (CREATE2); see `deployed.json`.
+2. **Confirm the spec with the user** (sell/buy tokens, per-swap cap, slippage, router/fee
+   tier, recipient = SMA) — print the explainer's humanReadable + warnings. No gas before
+   approval.
+3. **a. Register** the singleton on the SMA's kernel (does NOT configure):
+   ```bash
+   sailor mandate attach --address <SWAP_PERMISSION> --sma <SMA> --label "bounded-swap"
+   ```
+   **b. Configure** the per-account bounds — this is what makes the permission live. Build a
+   JSON file with the flat template params (`routers`, `tokensIn`, `tokensOut`, `maxAmountPerTx`,
+   `maxSlippageBps`, `priceOracle`, `maxPriceAgeSec` — matches the SDK `boundedSwapTemplate`
+   encoder tuple, no wrapper), then run:
+   ```bash
+   sailor mandate configure --address <SWAP_PERMISSION> --sma <SMA> \
+     --template SwapPermission --args-file ./swap-config.json
+   ```
+   `configureDirect` requires `msg.sender == permissionSigner` (`kernel.configs(<SMA>)` — the
+   owner only when they collapse to the same address); the command pre-flights the blob with an
+   `eth_call` BEFORE any signing or gas — it **reverts** on `priceOracle == 0` (`OracleRequired`),
+   `maxPriceAgeSec == 0` (`MissingPriceAge`), or `maxSlippageBps > 9_999` (`SlippageBpsTooLarge`) —
+   then requests the `configureDirect` tx from `permissionSigner` through the signing station and
+   verifies `isConfigured(<SMA>) == true` on receipt. Pass `--simulate-only` to stop after the
+   pre-flight (no signing, no gas).
+   *(The signed `configure(account, params, deadline, sig)` path uses EIP-712 domain `("SwapPermission","2")`.)*
+4. **Simulate** — prove an allowed swap passes and a bad one (wrong recipient / over-cap /
+   disallowed token) fails:
+   ```bash
+   sailor mandate simulate --address <SWAP_PERMISSION> --sma <SMA> --calls ./swap-probe.json
+   ```
+5. **Reconfigure** later (new cap / extra output token) — re-run step 3b with a new blob; same
+   address, no re-register.
+
+## Agent config (off-chain, within the on-chain bounds)
+
+The mandate bounds what the agent MAY do; the agent's code decides what it WILL do and when. Wire
+the legs from the resolve + quote outputs:
+
+```typescript
+export const DCA_LEGS = [
+  {
+    tokenIn: "<USDC_ADDR>", tokenOut: "<WETH_ADDR>",
+    tokenInDecimals: 6, tokenOutDecimals: 18,
+    feeTier: 3000, amountPerSwap: 25_000_000n,   // base units, ≤ maxAmountPerTx
+    slippageBps: 100,
+  },
+] as const;
+```
+
+The agent must re-quote via [`sail-swap-quote`](../sail-swap-quote/SKILL.md) close to dispatch time
+and embed the floor `amountOutMinimum` in the swap calldata — the on-chain `maxSlippageBps` enforces
+it regardless. **Match the tick's dispatch shape to your approve model:** under the batch model
+(default) the agent returns one `Dispatch` whose `calls` is the 3-element
+`[approve(router, amountIn), swap, approve(router, 0)]` and must NOT pre-approve out of band (the
+batch requires a zero pre-batch allowance); under `SwapPermission` + owner pre-approve it emits a
+plain single-call swap and MUST read `allowance(SMA, router)` and **stall (not self-approve)** when
+it is below `amountIn`.
+
+## When NOT to use this
+- **Token has no `IOracle` adapter** → this template REQUIRES a non-zero oracle and will not
+  configure without one. Use [`sail-template-swap-no-oracle`](../sail-template-swap-no-oracle/SKILL.md)
+  (live-pool hallucination band — catches honest mistakes, NOT MEV/flash-loan attacks) or author a
+  bespoke permission. There is no oracle-off mode on `SwapPermission`.
+- **Aggregator (LI.FI) or opaque calldata** → the mandate can't inspect the route; use
+  [`sail-mandates`](../sail-mandates/SKILL.md).
+- **`SwapPermission` not deployed on your chain** → check `deployed.json` first (it's live on all
+  11 Sailor-bundled chains as of the current deploy); for anything outside that set, author your
+  own via [`sail-mandates`](../sail-mandates/SKILL.md).
+
+## Notes
+- The oracle is **mandatory** and the band is **always** enforced; `maxSlippageBps = 0` is the
+  strictest setting (zero tolerance), not a way to disable the check.
+- `priceOracle` must be an `IOracle` adapter (`getPrice(tokenIn,tokenOut) → (price, dec, updatedAt)`),
+  not a raw Chainlink/Pyth feed; it must return a meaningful `updatedAt` or evaluate fails closed.
+- Native value is rejected (`ctx.value != 0 ⇒ deny`) — ERC-20→ERC-20 only.
+- Unaudited example — step 4 is mandatory.
+- `recipient = SMA` is non-negotiable and enforced in the contract, not just config.

package/templates/default/.agents/skills/sail-template-swap-no-oracle/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: sail-template-swap-no-oracle
+description: Gate an SMA's DEX swaps for tokens that have NO oracle by REUSING the shared SwapPermissionNoOracle singleton (Protocol/contracts/templates/SwapPermissionNoOracle.sol) — register + configure, no per-SMA deploy. Use for a bounded swap mandate on Uniswap V3/V3-02/V2 (and forks) where no manipulation-resistant price feed exists: router + token-in/out allowlists, a per-tx cap, recipient pinned to the SMA, and a per-pair live-pool "hallucination band". NOT manipulation-resistant — if the token HAS an oracle use sail-template-swap instead; for the LI.FI aggregator author a bespoke permission via sail-mandates. Deployed on all 11 Sailor-bundled chains (recorded in sail-templates/deployed.json).
+compatibility: A Sailor project (`@sail/sdk`, `sailor` CLI). Requires SwapPermissionNoOracle deployed on the target chain (recorded in sail-templates/deployed.json); run sail-templates first.
+metadata:
+  workspace: sailor-harness
+  classification: generic
+  status: draft
+  origin: Protocol/contracts/templates/SwapPermissionNoOracle.sol
+---
+
+# sail-template-swap-no-oracle — bounded DEX swap for oracle-less tokens
+
+Reuse the shared **`SwapPermissionNoOracle`** singleton instead of authoring/deploying a swap
+contract. Register its address on the SMA and `configure()` your routers, token allowlists, cap,
+and a **reference pool per tradeable pair**. Family overview + flow:
+[`sail-templates`](../sail-templates/SKILL.md). For the oracle-gated tier see
+[`sail-template-swap`](../sail-template-swap/SKILL.md).
+
+> ⚠️ **Pick the right tier.** This template provides **NO manipulation-resistant slippage
+> protection**. Its price band reads a *single pool's live spot price*, which any party can move
+> within the same transaction (flash-loan / sandwich / MEV). It only catches an **honest mistake**
+> — a confused manager/agent quoting a wildly wrong number (a "hallucination guard"). If the token
+> has an independent, freshness-checked price feed, use [`sail-template-swap`](../sail-template-swap/SKILL.md)
+> instead. Only reach for this when no such oracle exists.
+
+## What it enforces (per account, from source)
+
+Supported selectors (any other ⇒ `false`) — identical decode region to `SwapPermission`:
+
+| Selector | Function | Venue |
+|---|---|---|
+| `0x414bf389` | `exactInputSingle((tokenIn,tokenOut,fee,recipient,deadline,amountIn,amountOutMinimum,sqrtPriceLimitX96))` | Uniswap V3 SwapRouter |
+| `0x04e45aaf` | `exactInputSingle((tokenIn,tokenOut,fee,recipient,amountIn,amountOutMinimum,sqrtPriceLimitX96))` | Uniswap V3 SwapRouter02 |
+| `0x38ed1739` | `swapExactTokensForTokens(amountIn,amountOutMin,path[],to,deadline)` | Uniswap V2 Router |
+
+Structural invariants: `target ∈ routers`; `tokenIn`/`path[0] ∈ tokensIn`; `tokenOut`/`path[last]
+∈ tokensOut`; `recipient`/`to == SMA` (funds can't leave the account); `amountIn ≤ maxAmountPerTx`.
+
+**Price band (the only difference from `SwapPermission`):** for the swap's `(tokenIn, tokenOut)`
+pair, read the live spot price of the operator-named reference pool and require
+`amountOutMin ≥ expectedOut × (10_000 − toleranceBps)/10_000` **and** `amountOutMin > 0`. Fails
+closed (denies) if the pool is missing, unreadable, illiquid, doesn't price the pair, or the floor
+truncates to zero.
+
+> **V2 intermediate hops are NOT checked** — only `path[0]`/`path[last]`. Restrict to V3 or ensure
+> any plausible intermediate token is acceptable. Does NOT cover Universal Router, Uniswap V4, or
+> aggregators (opaque calldata).
+
+## Config blob (authoritative — `config-schemas.md`)
+
+```
+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; }
+```
+| Field | Notes |
+|---|---|
+| `routers` | DEX routers the agent may call |
+| `tokensIn` / `tokensOut` | sell-side / buy-side allowlists |
+| `maxAmountPerTx` | per-swap cap, base units (e.g. `25_000_000` = 25 USDC) |
+| `referencePools` | one per directional `(tokenIn, tokenOut)` pair — see coverage rule below |
+| `ReferencePool.pool` | a V2 pair or V3 pool that actually prices the pair (validated at configure) |
+| `ReferencePool.kind` | `0` = V2 (`getReserves`), `1` = V3 (`slot0`+`liquidity`) |
+| `ReferencePool.toleranceBps` | band width, **≤ 5_000 (50%)** or configure reverts. e.g. `1_000` = 10% |
+
+**Strict coverage rule:** `configure()` reverts `MissingReferencePool` unless every non-self
+directional combination of `tokensIn × tokensOut` has a `ReferencePool`. The pool's
+`token0()`/`token1()` must match the pair (orientation is precomputed at configure time), else it
+reverts `PoolTokenMismatch`. `pool == 0` reverts `ZeroPool`.
+
+Size the cap with `uniswap-v3-quote`. Verify the SDK encoder's param tuple matches the source blob
+above before using it (see [`sail-templates`](../sail-templates/SKILL.md) notes).
+
+## Steps
+
+Register → configure → simulate → reconfigure mechanics (and the encoding gotcha) live in
+[`sail-templates` reuse-flow](../sail-templates/references/reuse-flow.md) — follow it.
+`sailor mandate attach` registers only; `configureDirect` (owner tx) is the half that makes the
+permission live.
+
+Template-specific bits:
+
+- **Singleton:** `SwapPermissionNoOracle` — `node SKILLS/sail-templates/catalog.mjs --chain <id>`.
+- **Spec to confirm:** sell/buy tokens, per-swap cap, router/fee tier, recipient = SMA, and for each
+  pair the reference pool + tolerance. **Explicitly confirm the no-oracle trade-off** with the user:
+  this is a hallucination guard, not slippage/manipulation protection.
+- **Blob:** `abi.encode(routers[], tokensIn[], tokensOut[], maxAmountPerTx, ReferencePool[])` —
+  **flat params, no wrapper**; `ReferencePool{tokenIn, tokenOut, pool, kind, toleranceBps}`.
+- **Simulate (mandatory — unaudited example):** an allowed swap passes; wrong recipient, over-cap,
+  disallowed token, and an `amountOutMin` below the pool-implied floor are rejected.
+
+## Notes
+- The band is **not** manipulation-resistant — re-state this whenever authorizing. Prefer
+  [`sail-template-swap`](../sail-template-swap/SKILL.md) wherever an oracle exists.
+- `toleranceBps` is capped at 50% in source; a wider band is meaningless and rejected at configure.
+- Unaudited example — step 4 is mandatory.
+- Aggregator routing (opaque calldata) → author a bespoke permission via [`sail-mandates`](../sail-mandates/SKILL.md).

package/templates/default/.agents/skills/sail-template-transfer/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: sail-template-transfer
+description: Gate an SMA's ERC-20 transfers by REUSING the shared TransferPermission singleton (Protocol/contracts/templates/TransferPermission.sol) — register + configure, no per-SMA deploy. Use to let an agent move approved tokens, within a per-tx cap, only to a recipient allowlist (partner protocols, CEX deposit addrs, co-manager wallets). For returning funds to a single fixed Safe, prefer sail-template-withdraw. NOTE: `sailor mandate attach` only registers — you must also configure per-account (see steps).
+compatibility: A Sailor project (`@sail/sdk`, `sailor` CLI). Requires TransferPermission deployed on the target chain (recorded in sail-templates/deployed.json); run sail-templates first.
+metadata:
+  workspace: sailor-harness
+  classification: generic
+  status: draft
+  origin: Protocol/contracts/templates/TransferPermission.sol
+---
+
+# sail-template-transfer — bounded transfer to an allowlist via the shared singleton
+
+Reuse the shared **`TransferPermission`** singleton. Family overview + flow:
+[`sail-templates`](../sail-templates/SKILL.md).
+
+## What it enforces (per account, from source)
+
+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 == SMA`** (cannot pull from third parties that approved the Safe). Max 50 entries per
+allowlist.
+
+## Config blob (authoritative — `config-schemas.md`)
+
+```
+abi.encode(address[] allowedRecipients, address[] allowedTokens, uint256 maxAmountPerTx)
+```
+| Field | Notes |
+|---|---|
+| `allowedRecipients` | addresses the agent may send to (≤ 50) |
+| `allowedTokens` | ERC-20 tokens the agent may move (≤ 50) |
+| `maxAmountPerTx` | per-transfer cap, base units |
+
+> Recipient/token allowlists are mutable via `reconfigure` (permissionSigner). In production
+> use a multisig/timelock as the signer — it can widen the allowlist. Vet recipient contracts.
+
+## Steps
+
+Register → configure → simulate → reconfigure mechanics (and the encoding gotcha) live in
+[`sail-templates` reuse-flow](../sail-templates/references/reuse-flow.md) — follow it.
+`sailor mandate attach` registers only; `configureDirect` (owner tx) is the half that makes the
+permission live. Template-specific bits:
+
+- **Singleton:** `TransferPermission` — `node SKILLS/sail-templates/catalog.mjs --chain <id>`.
+- **Spec to confirm:** recipients, tokens, cap.
+- **Blob:** `abi.encode(allowedRecipients[], allowedTokens[], maxAmountPerTx)` — **flat params, no
+  wrapper**.
+- **Simulate (mandatory — unaudited example):** allowed recipient/token within cap passes; off-list
+  recipient, wrong token, over-cap, or `transferFrom` with `from != SMA` is rejected.

package/templates/default/.agents/skills/sail-template-withdraw/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: sail-template-withdraw
+description: Gate an SMA's ERC-20 withdrawals by REUSING the shared WithdrawPermission singleton (Protocol/contracts/templates/WithdrawPermission.sol) — register + configure, no per-SMA deploy. Use when the agent may move approved tokens, within a per-tx cap, only to ONE fixed recipient (typically the owner's Safe) for safe-to-safe consolidation. For a mutable multi-recipient allowlist, use sail-template-transfer instead. NOTE: `sailor mandate attach` only registers — you must also configure per-account (see steps).
+compatibility: A Sailor project (`@sail/sdk`, `sailor` CLI). Requires WithdrawPermission deployed on the target chain (recorded in sail-templates/deployed.json); run sail-templates first.
+metadata:
+  workspace: sailor-harness
+  classification: generic
+  status: draft
+  origin: Protocol/contracts/templates/WithdrawPermission.sol
+---
+
+# sail-template-withdraw — bounded withdraw to a fixed recipient via the shared singleton
+
+Reuse the shared **`WithdrawPermission`** singleton. Family overview + flow:
+[`sail-templates`](../sail-templates/SKILL.md).
+
+## What it enforces (per account, from source)
+
+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` (a single address from config); `amount ≤ maxAmountPerTx`;
+**`transferFrom` requires `from == SMA`**.
+
+> Single recipient per config. To change it, `reconfigure` with a new blob (no redeploy). This
+> is the consolidation primitive — funds can only flow to the one approved address.
+
+## Config blob (authoritative — `config-schemas.md`)
+
+```
+abi.encode(address[] tokens, address allowedRecipient, uint256 maxAmountPerTx)
+```
+| Field | Notes |
+|---|---|
+| `tokens` | ERC-20 tokens the agent may move |
+| `allowedRecipient` | the single destination (e.g. owner's Safe) |
+| `maxAmountPerTx` | per-withdraw cap, base units |
+
+## Steps
+
+Register → configure → simulate → reconfigure mechanics (and the encoding gotcha) live in
+[`sail-templates` reuse-flow](../sail-templates/references/reuse-flow.md) — follow it.
+`sailor mandate attach` registers only; `configureDirect` (owner tx) is the half that makes the
+permission live. Template-specific bits:
+
+- **Singleton:** `WithdrawPermission` — `node SKILLS/sail-templates/catalog.mjs --chain <id>`.
+- **Spec to confirm:** tokens, the single recipient, cap.
+- **Blob:** `abi.encode(tokens[], allowedRecipient, maxAmountPerTx)` — **flat params, no wrapper**.
+- **Simulate (mandatory — unaudited example):** withdraw to the recipient within cap passes; any
+  other `to`, wrong token, over-cap, or `transferFrom` with `from != SMA` is rejected.

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

@@ -0,0 +1,142 @@
+---
+name: sail-templates
+description: Registry + reuse guide for Sail's shared permission templates (Protocol/contracts/templates). Load this when you need to know which permission primitives are available as reusable templates and want to gate an SMA's mandate by REUSING a configurable singleton — deploy once, then register + configure per SMA (no per-SMA deploy). Covers swap (oracle-gated and no-oracle), borrow, transfer, deposit, withdraw, and approve-and-call-batch. All seven are deployed today, at the SAME address on every supported chain (CREATE2); addresses live in deployed.json.
+compatibility: Node 18+; a Sailor project (`@sail/sdk`, `sailor` CLI); read access to the workspace `Protocol/contracts/templates/` (or set SAIL_PROTOCOL_DIR).
+metadata:
+  workspace: sailor-harness
+  classification: generic
+  status: draft
+  origin: Protocol/contracts/templates source contracts
+---
+
+# Sail shared permission templates — registry & reuse
+
+`Protocol/contracts/templates/` holds seven **shared permission templates** — reusable
+`IPermission` patterns covering the most common DeFi primitives. Each extends
+`ConfigurablePermission`, which means it is a **configurable singleton**:
+
+> Deploy the contract **once per chain**. Every SMA then reuses that single address via
+> **register + configure** — its own routers / tokens / caps live in the singleton's
+> `mapping(address => …)`. **No per-SMA deploy, no per-SMA audit, minimal gas.**
+
+> **Deployment status (2026-07-01, by `0xB01dCE…815B6`):** **all seven** templates are live on
+> every chain Sailor bundles — Ethereum, Base, Arbitrum, Optimism, Unichain, BSC, World Chain,
+> HyperEVM, MegaETH, Base Sepolia, and Eth Sepolia (11 chains) — all bound to the current
+> CREATE2 kernel `0x38b508756c976e876EFF05a29E731A4d348BA6ED`. This is a CREATE2 deploy with a
+> global salt, so the kernel and every template address are **identical on every chain**. Live
+> addresses are in [`deployed.json`](deployed.json) (keyed by chainId → contract name, though
+> the value is the same for all 11 keys). This supersedes the prior 2026-06-09 deploy (kernel
+> `0x02ABC18B65A328de2e749F56ba79ACF2718a6659`) — those addresses are dead.
+
+> ⚠️ **Audit scope.** These are marked *"UNAUDITED EXAMPLE — NOT PART OF THE TRUSTED CORE"* in
+> source. The kernel runs them safely (staticcall + gas cap + fail-closed) but does not verify
+> their internal logic. Always `sailor mandate simulate` against your SMA before authorizing.
+
+> ⚠️ **CRITICAL — "register" ≠ "configure" in the shipped CLI.** A shared template is useless
+> until it is both **registered** on the kernel AND **configured** per-account. `sailor mandate
+> attach` does **only the register** half (it submits `RegisterPermission` and nothing more). A
+> registered-but-unconfigured singleton has `isConfigured == false` and the kernel **denies every
+> call**. Run `sailor mandate configure` as the separate second step (see the reuse flow below).
+
+## The seven templates
+
+| Primitive | Contract | Deployed? | Skill |
+|---|---|---|---|
+| DEX swap (oracle band) | `SwapPermission` | ✅ 11 chains | [`sail-template-swap`](../sail-template-swap/SKILL.md) |
+| DEX swap (no oracle) | `SwapPermissionNoOracle` | ✅ 11 chains | [`sail-template-swap-no-oracle`](../sail-template-swap-no-oracle/SKILL.md) |
+| Lending borrow | `BorrowPermission` | ✅ 11 chains | [`sail-template-borrow`](../sail-template-borrow/SKILL.md) |
+| Transfer (allowlist) | `TransferPermission` | ✅ 11 chains | [`sail-template-transfer`](../sail-template-transfer/SKILL.md) |
+| Vault/lending deposit | `DepositPermission` | ✅ 11 chains | [`sail-template-deposit`](../sail-template-deposit/SKILL.md) |
+| Withdraw to fixed addr | `WithdrawPermission` | ✅ 11 chains | [`sail-template-withdraw`](../sail-template-withdraw/SKILL.md) |
+| Approve+call batch | `ApproveAndCallBatchPermission` | ✅ 11 chains | [`sail-template-approve-batch`](../sail-template-approve-batch/SKILL.md) |
+
+Authoritative config tuples + enforced invariants (from source):
+[references/config-schemas.md](references/config-schemas.md).
+
+### One source of truth per concern
+
+This hub is canonical for everything shared; each spoke skill carries only what's unique to its
+primitive (selectors, invariants, config blob, probe cases) and defers the rest here. When
+something changes, edit it in ONE place:
+
+| Concern | Lives in | Spokes do |
+|---|---|---|
+| Which templates exist | source contracts, auto-detected by [`catalog.mjs`](catalog.mjs) | — |
+| Deployed addresses (per chain) | [`deployed.json`](deployed.json) | link here |
+| Register → configure → simulate flow | [references/reuse-flow.md](references/reuse-flow.md) | link here, don't restate |
+| Config tuples + invariants | [references/config-schemas.md](references/config-schemas.md) | quote only their own tuple |
+
+So a change to the CLI flow is a single edit to
+`reuse-flow.md`, not seven spoke edits. The deliberately-fuller [`sail-template-swap`](../sail-template-swap/SKILL.md)
+is the worked-example exemplar; the other spokes stay thin.
+
+## Step 1 — see what exists / deployment status
+
+The list is auto-detected from source; deployment status comes from `deployed.json`:
+
+```bash
+node SKILLS/sail-templates/catalog.mjs              # all templates
+node SKILLS/sail-templates/catalog.mjs --chain 8453 # status on one chain
+node SKILLS/sail-templates/catalog.mjs --json       # machine-readable
+```
+
+(The catalog warns if a new source contract appears with no curated metadata — a signal to
+add it here and write a skill.)
+
+## Step 2 — the reuse flow (per template)
+
+> The on-chain **intended** design is one signed call (`MandateFactory.attach`) that registers
+> the address on the kernel and writes the per-account config together. The **shipped** CLI
+> does not implement that combined call yet, so today these are two separate steps:
+> `sailor mandate attach` (register) followed by `sailor mandate configure` (configure). The
+> flow below describes what actually works now.
+
+1. **Deploy once** (one-time, Protocol team / `DeploySharedTemplates`, CREATE2 — same address on
+   every chain) → record the address in `deployed.json`. (Already done for all seven.)
+2. **Build the config blob** for your SMA (per-primitive skill gives the exact params).
+3. **Register** the singleton address on the SMA's kernel (this does NOT configure it):
+   ```bash
+   sailor mandate attach --address <DEPLOYED_ADDRESS> --sma <SMA> --label "<primitive>"
+   ```
+   A comma-separated `--address` list registers several in one signature (`attachBatch`).
+4. **Configure** the per-account bounds — this is the step that makes the permission actually
+   allow calls:
+   ```bash
+   sailor mandate configure --address <DEPLOYED_ADDRESS> --sma <SMA> \
+     --template <TemplateName> --args-file ./config.json
+   ```
+   This drives `configureDirect(account, <config blob>)` as an owner transaction (the owner is
+   the `permissionSigner`), pre-flighted with an `eth_call` before any signing or gas. See
+   [references/reuse-flow.md](references/reuse-flow.md) for the exact encoding gotcha and the
+   signing-station path.
+5. **Simulate** off-chain (no gas) — prove allowed calls pass and bad ones fail:
+   ```bash
+   sailor mandate simulate --address <DEPLOYED_ADDRESS> --sma <SMA> --calls ./probe.json
+   ```
+6. **Reconfigure** later (new caps / allowlists) via `configure`/`configureDirect` on the same
+   singleton — same address, no re-register. (On-chain `MandateFactory.reconfigure` is the
+   intended batch path for this.)
+
+Full mechanics (EIP-712 sigs, `configure`/`configureDirect`, `attachBatch`, `replace`,
+`detach`, and the register-vs-configure split): [references/reuse-flow.md](references/reuse-flow.md).
+
+## When NOT to use these
+
+No shared template covers: **perps** (GMX, Gains, Synthetix), **prediction markets** (Azuro,
+Limitless), or the **LI.FI aggregator**. For those, author a bespoke `IPermission` via
+`sailor mandate deploy` — see [`sail-mandates`](../sail-mandates/SKILL.md) for the
+authoring flow and `examples/permissions/` for worked per-protocol patterns.
+
+## Notes
+
+- The kernel and every template address are identical on every chain (CREATE2 global salt) —
+  but that pairing is generation-specific: a template address from one deploy generation (e.g.
+  the superseded 2026-06-09 deploy) is never valid against a different generation's kernel.
+  Always resolve both from the same `deployed.json` entry / SDK deployment.
+- Caps/amounts are in **base units**. Size them with `sail-pyth-prices` / `uniswap-v3-quote`.
+- The config encoder must match each contract's `_applyConfig` decode exactly — use the SDK
+  builder under `@sail/sdk/templates` **only after** verifying its param tuple equals the
+  source blob in `config-schemas.md` (the SDK builders track a previously-deployed set and may
+  differ from these source contracts).
+- **CLI gap:** `sailor mandate attach` (register) and `sailor mandate configure` (configure) are
+  still separate commands — no combined one-step call ships yet. Always run both.