npm - @dev.sail.money/sailor - Versions diffs - 1.3.0-98 → 1.4.0-242 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (231) hide show

package/packages/ui/dist/index.html CHANGED Viewed

@@ -5,8 +5,8 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="theme-color" content="#040b16" />
     <title>Sail - Unlocking Personalized Money</title>
-    <script type="module" crossorigin src="/assets/index-DLElIcBr.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-lhNfD4jA.css">
+    <script type="module" crossorigin src="/assets/index-LiKeH8Cd.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-B07bCKJ8.css">
   </head>
   <body>
     <div id="root"></div>

package/templates/default/.agents/skills/sail-mandates/SKILL.md CHANGED Viewed

@@ -116,4 +116,4 @@ The fee is read via `readPermissionRegistrationFee()` in `packages/sdk/src/fees.
 ## Clone templates (deploy-clone)
-`sailor mandate deploy-clone --template boundedApprove --sma <SMA> --tokens <csv> --spenders <csv> --max <wei> --json` deploys + registers an EIP-1167 clone of a published implementation in one transaction (owner signs `RegisterPermission` for the predicted clone address — BLOCKS; agent submits `deployAndAttach`). The only template key is `boundedApprove`. Implementations come from the SDK deployment registry (`standaloneTemplates`) — currently **empty on all six chains** pending redeployment against the new kernel, so deploy-clone errors with a clear message and you should write and deploy a bounded-approve permission with `sailor mandate deploy` instead. Check availability with `sailor mandate templates --json`.
+`sailor mandate deploy-clone --template boundedApprove --sma <SMA> --tokens <csv> --spenders <csv> --max <wei> --json` deploys + registers an EIP-1167 clone of a published implementation in one transaction (owner signs `RegisterPermission` for the predicted clone address — BLOCKS; agent submits `deployAndAttach`). The only template key is `boundedApprove`. Implementations come from the SDK deployment registry (`standaloneTemplates`) — that map is now populated with the shared swap/borrow/deposit/withdraw/transfer/approve-and-call-batch templates on all eleven chains, but no `boundedApprove` clone implementation is deployed yet, so deploy-clone errors with a clear message and you should write and deploy a bounded-approve permission with `sailor mandate deploy` instead. Check availability with `sailor mandate templates --json`.

package/templates/default/.agents/skills/sail-mandates/references/approvals.md CHANGED Viewed

@@ -25,12 +25,12 @@ This needs no batch support and works on every kernel.
 Approve + action run as one `dispatchBatch` — atomic, single transaction. A batch dispatch consults **exactly one batch-aware `IBatchPermission`**, never a pair of `IPermission`s:
-- The permission implements `@sail/interfaces/IBatchPermission.sol` — `evaluateBatch(Call[] calls, BatchContext ctx)` validates the WHOLE sequence (ordering, the approve's spender/amount, the action, and mandatory allowance cleanup) and `isBatchPermission()` returns true. `examples/permissions/BoundedApproveAndCallBatch.sol` is the model.
+- The permission implements `@sail/interfaces/IBatchPermission.sol` — `evaluateBatch(Call[] calls, BatchContext ctx)` validates the WHOLE sequence (ordering, the approve's spender/amount, the action, and mandatory allowance cleanup) and `isBatchPermission()` returns true. **For the canonical `approve → swap/deposit/supply → reset` shape, a shared `ApproveAndCallBatchPermission` singleton is deployed** on Base, Arbitrum, Unichain, Sepolia, and Base Sepolia (resolve it with `node scripts/shared-template-addr.mjs ApproveAndCallBatchPermission`) — reuse it via `attach` + `configure` rather than authoring one. `examples/permissions/BoundedApproveAndCallBatch.sol` remains the model for a non-standard shape you must author yourself.
 - A normal `IPermission` placed in a batch is rejected by the kernel with `PermissionNotBatchAware`. You cannot assemble a batch from two narrow per-call permissions — that was the trap.
 - Batch is a **selective-kernel** feature (`dispatchBatch` / `previewBatch`); conjunctive kernels have neither. Confirm the model with `sailor doctor`; details in `docs/PERMISSION_MODEL.md`.
-- At runtime, return one `Dispatch` whose `calls` array is `[approveCall, actionCall]`; the runner detects `calls.length > 1` and routes through `dispatch.batch`.
+- At runtime, return one `Dispatch` whose `calls` array is the batch. The shared `ApproveAndCallBatchPermission` requires **exactly** `[approve(spender, amount), action, approve(spender, 0)]` — the trailing reset to zero is mandatory, and the pre-batch allowance on that `(token, spender)` pair must already be zero (so never combine it with a standing approve). The runner detects `calls.length > 1` and routes through `dispatch.batch`.
-Use Model B only when atomicity genuinely matters (e.g. the approve must not be observable between calls). Otherwise prefer Model A — less contract to author and test.
+**For autonomous recurring actions (a DCA or rebalancer the agent runs on its own), Model B is the default — not an advanced option.** Model A's separate approve dispatch needs the owner back in the loop every time the bounded allowance runs out, which a recurring agent cannot do; on the first tick after the allowance is consumed it stalls (or, in a simulation, is tempted to cheat the allowance in). Reach for Model A when the owner is genuinely in the loop per action anyway. For bounded swaps specifically, [`sail-template-swap`'s "Approve coverage"](../../sail-template-swap/SKILL.md) works through the choice with concrete addresses.
 ## Verifying each model

package/templates/default/.agents/skills/sail-mandates/references/examples-index.md CHANGED Viewed

@@ -15,7 +15,7 @@ Permissions only bound on-chain actions: venues with off-chain order matching (P
 | `BoundedStake_Venice_Base.sol` | Venice (VVV) staking · Base | Recipient binding on stake; claim() structurally routes rewards to caller (the SMA) | `0xadc9772e` stake(address,uint256), `0x4e71d92d` claim() |
 | `BoundedTransfer_ERC20_Ethereum.sol` | ERC-20 · any EVM | Token allowlist + recipient allowlist + per-transfer cap; caps are per-token base units (USDC 6 decimals, WETH 18) — one permission per token if amounts differ | `0xa9059cbb` transfer(address,uint256) |
 | `BoundedPerp_GMXv2_Arbitrum.sol` | GMX v2 ExchangeRouter · Arbitrum | Market allowlist + collateral cap + size cap (USD is 1e30-scaled) + long/short flags on a struct-typed call | `0x212234c3` createOrder(CreateOrderParams) — MUST re-verify, see below |
-| `BoundedBet_Limitless_Base.sol` | Limitless CTF exchange · Base | Condition allowlist + stake cap + outcome allowlist on a prediction market | buy(bytes32,uint256,uint256) — **ABI UNVERIFIED**, see below |
+| `BoundedLimitless_Base.sol` | Limitless CTF exchange · Base | Condition allowlist + stake cap + outcome allowlist on a prediction market | buy(bytes32,uint256,uint256) — **ABI UNVERIFIED**, see below |
 | `BoundedApproveAndCallBatch.sol` | Sail batch dispatch · any selective kernel | `IBatchPermission`: atomic approve → consume → reset-to-0 in exactly 3 calls; single-call evaluate() deliberately returns false | `0x095ea7b3` approve (calls 0 and 2) |
 ## Lessons the examples encode
@@ -29,6 +29,6 @@ Permissions only bound on-chain actions: venues with off-chain order matching (P
 ## Interfaces (vendored in `examples/permissions/interfaces/`)
-- `IPermission.evaluate(bytes txData, Context ctx) → bool`; Context: `account, manager, submitter, target, selector, value, blockTimestamp, blockNumber`.
-- `IBatchPermission.evaluateBatch(Call[] calls, BatchContext ctx) → bool` + `isBatchPermission() → true`; Call: `(target, value, data)`; BatchContext: `account, manager, submitter, permission, batchHash, blockTimestamp, blockNumber`.
+- `IPermission.evaluate(bytes txData, Context ctx) → bool`; Context: `account, manager, submitter, target, selector, value, blockTimestamp, blockNumber, configEpoch`.
+- `IBatchPermission.evaluateBatch(Call[] calls, BatchContext ctx) → bool` + `isBatchPermission() → true`; Call: `(target, value, data)`; BatchContext: `account, manager, submitter, permission, batchHash, blockTimestamp, blockNumber, configEpoch`.
 - `SailCalldata.sol`: bounded slot-indexed calldata readers (`hasParams`, `asAddress`, `asUint256`, …) — use these instead of `abi.decode` to avoid wrong-offset reads.

package/templates/default/.agents/skills/sail-onboarding/SKILL.md CHANGED Viewed

@@ -5,46 +5,47 @@ description: Walks the agent through setting up a new Sailor project or resuming
 # Sail onboarding
-## First contact
+## Running the CLI
-On the user's first message (or after `sailor init` completes), present the full onboarding overview below — do NOT launch the UI yet. The goal is for the user to understand every stage before committing.
+**Determine the installation mode first** — read `.sail/config.json → installMode` before running any command:
----
+- `"local"` (or field absent) — `sailor` is on the PATH. Run commands directly: `sailor <command>`
+- `"docker"` — sailor runs in a container. Read `containerName` from the same config. Prefix every command:
+  `docker exec <containerName> sailor <command>`
+  Project files are on your **local filesystem** (mounted at `/workspace` inside the container) — read and write them normally from local paths. Do NOT use `docker exec` to read files; the volume mount makes them directly accessible.
-> **Sail Protocol** is infrastructure for onchain Separately Managed Accounts (SMAs) run by AI agents. You keep full custody; the agent acts only within cryptographically-bound permissions you approve and can always revoke. It cannot exceed them.
->
-> Here is the complete path. Read it before we begin — each stage requires something from you.
->
-> ---
->
-> **Stage 1 — Deploy your SMA and create your agent wallet**
-> We open a browser interface where you connect your owner wallet (MetaMask or any WalletConnect wallet), choose your chain, and deploy your SMA — a smart contract account you own. We also create a separate agent wallet: a signing key the agent uses to submit transactions on your behalf. Both wallets need gas. The owner wallet signs the deployment; the agent wallet pays for everything after that.
->
-> **Stage 2 — Define your strategy**
-> You tell me what you want the agent to do: which protocol, which tokens, what conditions, what limits. I help you separate the constraints that must be enforced on-chain (amount caps, venue allowlists, slippage floors) from the ones that live in agent logic (cadence, schedule, timing). Nothing is deployed yet — this is design.
->
-> **Stage 3 — Build, test, and sign your mandate**
-> I write the Solidity permission contracts that encode the strategy bounds from Stage 2. You review them. We run Foundry tests against your actual strategy parameters (must-pass and must-fail cases). We deploy the contracts on-chain and simulate them before you sign anything. You authorize the permission set in the browser — one signature. After this, the agent can act autonomously within those bounds.
->
-> **Stage 4 — Run your agent**
-> We run the agent locally first (`sailor run --once`) to confirm a full tick works. Then we automate it — GitHub Actions, a self-hosted runner, a local daemon, or Docker — matched to your latency needs and infrastructure comfort.
->
-> **Stage 5 — Extend**
-> Once the agent is live, I offer to add run and transaction notifications (Telegram, email) and a strategy-specific dashboard. This is optional, but I will offer it — you opt out explicitly if you don't want it.
->
-> ---
->
-> Ready to begin? Say **start** and I'll open the setup interface in your browser for Stage 1.
+### Starting the Docker container
----
+If the container is not running, start it from the project root:
+```bash
+docker run -d --name agent -P -v "${PWD}:/workspace" sailmoney/sailor
+```
+- `-d` — detached, runs in the background
+- `--name agent` — names the container; use a different name with `-e SAILOR_CONTAINER_NAME=<name>` if needed
+- `-P` — publishes all exposed ports to random available host ports (UI: 3334, station: 3141)
+- `-v "${PWD}:/workspace"` — mounts the current project directory into the container
-After the user says "start" (or "ready" or any affirmative), THEN run `sailor ui start` — the explanation and the UI launch are two separate beats. Do not skip the explanation. If the user's first message is an npm install command, run it, then present the overview immediately after.
+After starting, resolve the host port before opening the UI in the browser:
-## Running sailor commands
+```bash
+docker port agent 3334
+# → 0.0.0.0:49201   (use 49201, not 3334, in the browser URL)
+```
+All `sailor` commands run via `docker exec`:
+```bash
+docker exec agent sailor --version
+docker exec agent sailor init
+docker exec agent sailor ui start
+docker exec agent sailor station start --json &
+```
-Before running any command, check how sailor is installed — see **sail-sailor** for the full guide (local vs Docker, `installMode` detection, `docker exec` prefix, `--json` flag, `SAIL_PASSPHRASE`).
+The published package is **`@sail.money/sailor`** — always use the scoped name with the registry. The bare name `sailor` is a different, unrelated npm package; never `npx sailor@<version>` or `npm i sailor`. Install it (`npm i -g @sail.money/sailor`, or as a project dep), after which the `sailor` bin works bare (`sailor <command>`) and `npx sailor <command>` resolves the installed bin. Every `sailor …` command in these skills assumes it is installed. Confirm the toolchain up front and pin a recent version — `npx @sail.money/sailor@latest --version` — because an old cached `npx` build can be missing newer commands (e.g. `mandate simulate`); if a documented command reports "unknown command", you are on a stale version, not hitting a missing feature.
-Short version: read `.sail/config.json → installMode`. If `"docker"`, prefix every command with `docker exec <containerName>`. If `"local"` or absent, run `sailor <command>` directly.
+After upgrading the CLI, run `sailor update` from the project root to pull in updated skills, `AGENTS.md`, `Dockerfile`, and other tooling files. User files (`src/`, `mandates/`, `.sail/`, `package.json`) are never touched.
 Stage machine keyed off `.sail/`. Read the state, enter at the right stage, never re-run completed stages.
@@ -57,7 +58,7 @@ Stage machine keyed off `.sail/`. Read the state, enter at the right stage, neve
 | `account.json` exists, `state/mandates.json` empty or absent | SMA live, no permissions — hand off to **sail-mandates** |
 | `account.json` + tracked mandates | SMA live with permissions — hand off to **sail-transactions** to run. Once the agent is live, the flow is not done: **offer Extend (stage 5 — notifications + a custom dashboard) by default**, unless the operator opts out, then hand off to **sail-extend**. The end state is "stage 5 offered," not "running" |
-Supported chains: Ethereum (1), Base (8453), Arbitrum (42161), Unichain (130), Base Sepolia (84532), Eth Sepolia (11155111). `sailor chains --json` lists them with kernel addresses.
+Supported chains: Ethereum (1), Base (8453), Arbitrum (42161), Optimism (10), Unichain (130), BSC (56), World Chain (480), HyperEVM (999), MegaETH (4326), Base Sepolia (84532), Eth Sepolia (11155111). `sailor chains --json` lists them with kernel addresses.
 ## Stage 1 — Deploy the SMA and create the agent wallet

package/templates/default/.agents/skills/sail-servers/SKILL.md CHANGED Viewed

@@ -20,6 +20,7 @@ sailor ui start --expose tailscale   # also serve it on the tailnet over HTTPS (
 - The server serves the pre-built React app (`SERVE_DIST=1`) and a local `/api` that reads `.sail/` state (`SAIL_DIR` env).
 - `ui start` does not block — no `&` needed.
 - `--expose tailscale` (optional): proxies the dashboard onto the operator's tailnet over HTTPS via `tailscale serve` (tailnet-private, never `funnel`). Requires `tailscale` installed + logged in, and Serve + HTTPS enabled for the tailnet (else the command prints the enable link). `ui stop` tears the proxy down. To allow extra browser origins, set `SAILOR_CORS_ORIGINS` (comma-separated; the local origin is always allowed).
+- Binds `127.0.0.1` by default (local only). To expose without `--expose tailscale` — e.g. behind a reverse proxy on a domain — set `SAILOR_HOST=0.0.0.0`. The `/api` key-management endpoints are **unauthenticated**, so only do this behind your own auth (reverse-proxy basic-auth or a private tailnet), and throttle them with `SAILOR_RATE_LIMIT_PER_MIN` (default 100; or `rateLimitPerMin` in `.sail/config.json`).
 ## Signing station — `sailor station`

package/templates/default/.agents/skills/sail-swap-quote/SKILL.md ADDED Viewed

@@ -0,0 +1,76 @@
+---
+name: sail-swap-quote
+description: Fetch a live Uniswap V3 quote via QuoterV2 and compute a slippage-adjusted amountOutMinimum for a swap. Use after sail-token-resolve to show the user the current price and to produce the amountOutMinimum floor the agent must embed in every swap dispatch. Runs the bundled `scripts/quote-swap.mjs` (no dependencies, no gas).
+---
+# sail-swap-quote — live price + amountOutMinimum floor
+After [`sail-token-resolve`](../sail-token-resolve/SKILL.md) confirms a token is
+swap-ready, get the actual number: how much tokenOut the user's amountIn buys
+right now, and the `amountOutMinimum` floor that protects against slippage.
+## When to load
+- After `sail-token-resolve` returned `swapReady: true`.
+- Before presenting a mandate to the user (show them the current price).
+- To validate `amountOutMinimum` before the agent dispatches a real swap.
+- Whenever the user asks "what's the price of X?" or "how much WETH for 25 USDC?".
+## Run it
+```bash
+# From the project root. Inputs come from sail-token-resolve's output.
+node scripts/quote-swap.mjs \
+  --token-in  0x078D782b760474a361dDA0AF3839290b0EF57AD6  --decimals-in  6  \
+  --token-out 0x4200000000000000000000000000000000000006 --decimals-out 18 \
+  --amount 25000000 --fee 3000 --slippage-bps 100
+```
+- `--amount` is in **base units** of tokenIn (25 USDC = `25000000`, not `25`).
+- `--fee` is the tier from `sail-token-resolve` (deepest pool).
+- `--slippage-bps` defaults to `100` (1%). Tighten (e.g. `50`) for stable pairs,
+  loosen for volatile ones. `0` removes the floor — testing only.
+- `--chain` / `--rpc` override the project's active chain/RPC.
+Output: one JSON object on stdout; human notes on stderr.
+## What it returns
+```json
+{
+  "amountIn": "25000000", "amountOut": "15805313193992907",
+  "amountOutMinimum": "15647260062052977",   // amountOut × (10000-slip)/10000
+  "slippageBps": 100, "fee": 3000,
+  "human": { "amountIn": "25.0", "amountOut": "0.015805313193992907",
+             "amountOutMinimum": "0.015647260062052977",
+             "price": "0.015805313193992907 out per 25.0 in" }
+}
+```
+## How the floor is computed
+```
+amountOutMinimum = amountOut × (10000 − slippageBps) / 10000
+```
+At 1% slippage, `amountOut × 9900 / 10000`. The agent must embed a value **at
+least this high** in its swap calldata's `amountOutMinimum` field — the
+`SwapPermission` mandate rejects any swap whose `amountOutMinimum` is below the
+pool-implied floor (fail-closed). Re-quote close to dispatch time; a stale quote
+is the most common reason a legitimate swap gets rejected.
+## What to do with it
+1. **Show the user** the `human.price` line before they approve the mandate.
+2. **Record `amountOutMinimum`** as the floor the agent's dispatch logic must
+   respect. Hand the full quote to [`sail-template-swap`](../sail-template-swap/SKILL.md)
+   — the mandate's `maxSlippageBps` bound is the on-chain enforcement of this.
+3. **Re-quote at dispatch time** — pool state moves; a quote taken minutes ago may
+   no longer match.
+## If it fails
+| Error | Meaning |
+|---|---|
+| `QuoterV2 reverted` / `amountOut == 0` | No pool at this fee tier (despite resolve-token). Try the next tier from resolve-token's `probedTiers`, or re-run resolve-token — liquidity may have shifted. |
+| `No RPC for chain` | Run from the project root, or pass `--rpc`. |

package/templates/default/.agents/skills/sail-template-approve-batch/SKILL.md ADDED Viewed

@@ -0,0 +1,98 @@
+---
+name: sail-template-approve-batch
+description: Gate an SMA's "approve → call → reset" interactions by REUSING the shared ApproveAndCallBatchPermission singleton (Protocol/contracts/templates/ApproveAndCallBatchPermission.sol) — register + configure, no per-SMA deploy. Use when an agent must approve an ERC-20 to a protocol, make one consuming call, and reset the allowance to zero — all in one atomic batch — with token/spender/target/selector allowlists and a per-token approval cap. NOTE: `sailor mandate attach` only registers — you must also configure per-account (see steps).
+compatibility: A Sailor project (`@sail/sdk`, `sailor` CLI). Requires ApproveAndCallBatchPermission 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/ApproveAndCallBatchPermission.sol
+---
+# sail-template-approve-batch — atomic approve/call/reset via the shared singleton
+Reuse the shared **`ApproveAndCallBatchPermission`** singleton — the safest way to bracket a
+single protocol interaction that needs an allowance. Family overview + flow:
+[`sail-templates`](../sail-templates/SKILL.md).
+## What it enforces (per account, from source)
+Authorises exactly this 3-call batch:
+```
+[0] approve(spender, amount)   on an allowlisted ERC-20
+[1] consuming call             on an allowlisted (target, selector)
+[2] approve(spender, 0)        reset to zero (same atomic batch)
+```
+Invariants: `tokens`, `spenders`, and `consumingPairs` must each be non-empty with no zero
+addresses/selectors (`EmptyAllowlist` reverts at configure otherwise); `token ∈ tokens` and
+`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`; the reset-to-zero is required; if
+`requireAmountMatch`, the consuming call's leading `uint256` arg must equal the approve amount.
+Malformed calldata reverts (kernel treats revert as deny).
+> **Output recipient — `allowUnconstrainedRecipient` (opt-out, default-safe).** By DEFAULT
+> (`allowUnconstrainedRecipient = false`, i.e. omitted) the consuming call's output recipient is
+> decoded and **must equal the SMA** — the safe posture — and any selector outside the decodable
+> set below is denied (fail-closed). Set `allowUnconstrainedRecipient = true` ONLY to deliberately
+> leave the recipient unconstrained (e.g. to authorize a selector outside the decodable set); then
+> only allowlist `(target, selector)` pairs whose semantics you trust to deliver output to the SMA.
+> ⚠️ This is an **opt-out** flag, not an opt-in — do not set it `true` thinking that "requires"
+> or "pins" the recipient; that gets you the opposite (unconstrained) behavior on-chain.
+>
+> **Decodable set** (recipient AND consumed-asset both resolvable at a fixed calldata offset —
+> any other selector is denied regardless of `allowUnconstrainedRecipient`, since the consumed
+> asset can never be bound to the approved token): `swapExactTokensForTokens` (V2), V3
+> `exactInputSingle` (both the SwapRouter and SwapRouter02 layouts), Aave V2 `deposit` / Aave V3
+> `supply`, ERC-4626 `deposit` / `mint`.
+## Config blob (authoritative — `config-schemas.md`)
+```
+abi.encode(Config{
+  address[]       tokens;                       // approvable ERC-20s
+  address[]       spenders;                     // allowed allowance recipients
+  ConsumingPair[] consumingPairs;               // {address target; bytes4 selector} — pair bound together
+  uint256[]       maxApprovalAmounts;           // index-parallel with tokens; per-token cap
+  bool            requireAmountMatch;           // call[1] leading uint256 must equal approve amount
+  bool            allowUnconstrainedRecipient;  // OPT-OUT (default false = call[1] output recipient decoded, must == account)
+})
+struct ConsumingPair { address target; bytes4 selector; }
+```
+`maxApprovalAmounts.length` must equal `tokens.length` (configure reverts otherwise).
+`consumingPairs` is a **struct array** `(address target, bytes4 selector)[]` — NOT two flat
+`address[]`/`bytes4[]` arrays. A selector is authorised only on the target it is paired with.
+**ABI tuple (verified round-trip):** `(address[],address[],(address,bytes4)[],uint256[],bool,bool)`.
+Encode with cast — note `selector` is a `bytes4` (left-aligned), and both trailing bools are required:
+```bash
+cast abi-encode 'cfg((address[],address[],(address,bytes4)[],uint256[],bool,bool))' \
+  '([<token>],[<spender>],[(<target>,<selector>)],[<maxApproval>],<requireAmountMatch>,<allowUnconstrainedRecipient>)'
+```
+`allowUnconstrainedRecipient` is an **opt-out** — leave it `false` unless you deliberately want
+the consuming call's output recipient unconstrained (see the field note above).
+The leading word is the `0x20` struct offset — that is correct, not flat-param corruption. A
+generic (un-named) revert inside `_applyConfig` means the blob did not decode to this exact tuple
+(usually: flat params with no `0x20` offset, the two flat arrays instead of `ConsumingPair[]`, or a
+missing trailing bool). The named errors (`TokensAndAmountsLengthMismatch`, `EmptyAllowlist`,
+`AllowlistTooLong`) fire only after a successful decode.
+## Steps
+Register → configure → simulate → reconfigure mechanics 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:** `ApproveAndCallBatchPermission` — `node SKILLS/sail-templates/catalog.mjs --chain
+  <id>`.
+- **Spec to confirm:** tokens+caps, spenders, `(target, selector)` consuming pairs,
+  `requireAmountMatch`, `allowUnconstrainedRecipient`. Get each selector with `cast sig` and verify
+  it delivers output to the SMA (leave `allowUnconstrainedRecipient = false`, the default, to
+  enforce that on-chain — set `true` only to deliberately opt out).
+- **Blob — ⚠️ NOT flat params.** `abi.encode(Config{ … })` — a **single wrapped struct**, so the
+  blob starts with a `0x20` offset word. `consumingPairs` is `(address,bytes4)[]` (a struct array),
+  and both trailing bools are required — see the verified `cast abi-encode` form above. Unlike
+  transfer/withdraw/deposit/borrow/swap, wrapping is required here; a flat blob reverts at configure.
+- **Simulate (mandatory — unaudited example):** the full allowed approve/call/reset batch passes;
+  missing reset, off-list spender/target/selector, or over-cap approve is rejected.

package/templates/default/.agents/skills/sail-template-borrow/SKILL.md ADDED Viewed

@@ -0,0 +1,68 @@
+---
+name: sail-template-borrow
+description: Gate an SMA's lending borrows by REUSING the shared BorrowPermission singleton (Protocol/contracts/templates/BorrowPermission.sol) — register + configure, no per-SMA deploy. Use for a bounded borrow mandate against Aave / Morpho / Compound with a protocol + asset allowlist, per-tx cap, and an on-chain LTV check via collateral + borrow oracles. NOTE: `sailor mandate attach` only registers — you must also configure per-account (see steps).
+compatibility: A Sailor project (`@sail/sdk`, `sailor` CLI). Requires BorrowPermission 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/BorrowPermission.sol
+---
+# sail-template-borrow — bounded lending borrow via the shared singleton
+Reuse the shared **`BorrowPermission`** singleton. Family overview + flow:
+[`sail-templates`](../sail-templates/SKILL.md).
+## What it enforces (per account, from source)
+Selectors (any other ⇒ `false`): Aave `borrow(address,uint256,uint256,uint16,address)`
+(**variable-rate only** — a stable-rate borrow, `rateMode != 2`, is rejected), Morpho
+**Optimizer/Morpho-Aave** `borrow(address,uint256,address,address)` (**NOT Morpho Blue** — its
+ABI differs and simply won't match this selector, i.e. fails closed; target a Blue-specific
+permission instead), Compound `borrow(uint256)` (the call target is the **cToken**; the template
+resolves `cToken.underlying()` and keys the allowlist/cap/LTV on the underlying — a target with
+no `underlying()`, e.g. cETH, is denied). Invariants: `target ∈ protocols`; `asset ∈ assets`
+(Aave/Morpho decode the asset; Compound resolves it via `underlying()`); `amount ≤
+maxAmountPerTx`; `onBehalfOf`/`receiver == SMA`; **`_ltvCheck` passes** — the projected debt
+value (via `borrowOracle`) against collateral value (via `collateralOracle`) must stay within
+`maxLtvBps`, when oracles are configured (see ORACLE MODES below).
+> **Oracle modes:** configure **zero** oracles for amount-cap-only borrowing (no LTV ceiling is
+> applied at all, despite `maxLtvBps` being stored) or **both** — exactly one oracle reverts
+> `OracleConfigInconsistent` at configure (a single feed can't price a ratio). When both are set,
+> the check still depends on their honesty/freshness — see staleness via `maxPriceAgeSec`.
+## Config blob (authoritative — `config-schemas.md`)
+```
+abi.encode(address[] protocols, address[] assets, uint256 maxAmountPerTx,
+           uint256 maxLtvBps, address collateralOracle, address borrowOracle,
+           uint256 maxPriceAgeSec)
+```
+| Field | Notes |
+|---|---|
+| `protocols` | lending pools the agent may borrow from |
+| `assets` | borrowable ERC-20 allowlist |
+| `maxAmountPerTx` | per-borrow cap, base units |
+| `maxLtvBps` | max loan-to-value, bps (e.g. `5000` = 50%) |
+| `collateralOracle` / `borrowOracle` | price sources for the LTV check |
+| `maxPriceAgeSec` | oracle freshness bound; `> 0` when oracles are set |
+> `maxLtvBps` is a **per-transaction** projection, not a tracked lifetime LTV. For
+> portfolio-level exposure, rely on the protocol's health factor or pair with a
+> position-monitoring permission.
+## 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:** `BorrowPermission` — `node SKILLS/sail-templates/catalog.mjs --chain <id>`.
+- **Spec to confirm:** protocols, assets, cap, max LTV, oracles.
+- **Blob:** `abi.encode(protocols[], assets[], maxAmountPerTx, maxLtvBps, collateralOracle,
+  borrowOracle, maxPriceAgeSec)` — **flat params, no wrapper**.
+- **Simulate (mandatory — unaudited example):** allowed borrow within LTV passes; over-cap,
+  over-LTV, or wrong recipient is rejected.

package/templates/default/.agents/skills/sail-template-deposit/SKILL.md ADDED Viewed

@@ -0,0 +1,61 @@
+---
+name: sail-template-deposit
+description: Gate an SMA's deposits into vaults / lending pools by REUSING the shared DepositPermission singleton (Protocol/contracts/templates/DepositPermission.sol) — register + configure, no per-SMA deploy. Use for a bounded deposit mandate into ERC-4626 vaults (deposit/mint) or Aave v2/v3 (deposit/supply) with a target + token allowlist and a per-tx cap; the resulting position always accrues to the SMA. NOTE: `sailor mandate attach` only registers — you must also configure per-account (see steps).
+compatibility: A Sailor project (`@sail/sdk`, `sailor` CLI). Requires DepositPermission 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/DepositPermission.sol
+---
+# sail-template-deposit — bounded vault/lending deposit via the shared singleton
+Reuse the shared **`DepositPermission`** singleton. Family overview + flow:
+[`sail-templates`](../sail-templates/SKILL.md). Discover yield targets first with
+`sail-defillama-yields`.
+## What it enforces (per account, from source)
+Selectors (any other ⇒ `false`):
+| Function | Venue |
+|---|---|
+| `deposit(uint256 assets, address receiver)` | ERC-4626 / simple vault |
+| `mint(uint256 shares, address receiver)` | ERC-4626 |
+| `deposit(address asset, uint256 amount, address onBehalfOf, uint16)` | Aave v2 |
+| `supply(address asset, uint256 amount, address onBehalfOf, 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 checks the `asset` arg, ERC-4626 requires the `target` (vault) itself
+∈ `tokens`; `amount`/`shares ≤ maxAmountPerTx`; `receiver`/`onBehalfOf == SMA`.
+> `mint`'s cap is in **shares**, not underlying. At a high share price the effective asset cap
+> is `maxAmountPerTx × sharePrice` — size accordingly. For ERC-4626 `deposit`/`mint` the token
+> allowlist is the last line of defence (no asset in calldata) — only allowlist vaults whose
+> accepted token you trust.
+## Config blob (authoritative — `config-schemas.md`)
+```
+abi.encode(address[] targets, address[] tokens, uint256 maxAmountPerTx)
+```
+| Field | Notes |
+|---|---|
+| `targets` | vault / lending-pool addresses |
+| `tokens` | ERC-20 allowlist (the asset for Aave; the vault itself for ERC-4626) |
+| `maxAmountPerTx` | per-deposit cap (assets, or shares for `mint`), 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:** `DepositPermission` — `node SKILLS/sail-templates/catalog.mjs --chain <id>`.
+- **Spec to confirm:** targets, tokens, cap (note the share-price caveat for `mint`).
+- **Blob:** `abi.encode(targets[], tokens[], maxAmountPerTx)` — **flat params, no wrapper**.
+- **Simulate (mandatory — unaudited example):** allowed deposit within cap passes; off-list
+  target/token, over-cap, or `receiver != SMA` is rejected.