npm - @dev.sail.money/sailor - Versions diffs - 1.0.0-41 → 1.1.0-43 - Mend

@dev.sail.money/sailor 1.0.0-41 → 1.1.0-43

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 (129) hide show

package/packages/ui/dist/assets/{walletconnect-ioE7leyd.js → walletconnect-DmCqpZUB.js} RENAMED Viewed

@@ -1,4 +1,4 @@
-import{F as l}from"./core-DJKvcaym.js";import"./index-CBEcDgJN.js";import"./events-cYLbpQpi.js";import"./index.es-D8L0a50U.js";import"./fallback-mNp6Xdgm.js";const o=l`<svg fill="none" viewBox="0 0 96 67">
+import{F as l}from"./core-CqvnE8sM.js";import"./index-DOy_BvMy.js";import"./events-D_3qqJ93.js";import"./index.es-Cz1WraDz.js";import"./fallback-BDBC0epM.js";const o=l`<svg fill="none" viewBox="0 0 96 67">
   <path
     fill="currentColor"
     d="M25.32 18.8a32.56 32.56 0 0 1 45.36 0l1.5 1.47c.63.62.63 1.61 0 2.22l-5.15 5.05c-.31.3-.82.3-1.14 0l-2.07-2.03a22.71 22.71 0 0 0-31.64 0l-2.22 2.18c-.31.3-.82.3-1.14 0l-5.15-5.05a1.55 1.55 0 0 1 0-2.22l1.65-1.62Zm56.02 10.44 4.59 4.5c.63.6.63 1.6 0 2.21l-20.7 20.26c-.62.61-1.63.61-2.26 0L48.28 41.83a.4.4 0 0 0-.56 0L33.03 56.21c-.63.61-1.64.61-2.27 0L10.07 35.95a1.55 1.55 0 0 1 0-2.22l4.59-4.5a1.63 1.63 0 0 1 2.27 0L31.6 43.63a.4.4 0 0 0 .57 0l14.69-14.38a1.63 1.63 0 0 1 2.26 0l14.69 14.38a.4.4 0 0 0 .57 0l14.68-14.38a1.63 1.63 0 0 1 2.27 0Z"

package/packages/ui/dist/assets/{warning-circle-CfXfQlpb.js → warning-circle-bT7aRO8J.js} RENAMED Viewed

@@ -1,4 +1,4 @@
-import{F as r}from"./core-DJKvcaym.js";import"./index-CBEcDgJN.js";import"./events-cYLbpQpi.js";import"./index.es-D8L0a50U.js";import"./fallback-mNp6Xdgm.js";const a=r`<svg fill="none" viewBox="0 0 20 20">
+import{F as r}from"./core-CqvnE8sM.js";import"./index-DOy_BvMy.js";import"./events-D_3qqJ93.js";import"./index.es-Cz1WraDz.js";import"./fallback-BDBC0epM.js";const a=r`<svg fill="none" viewBox="0 0 20 20">
   <path
     fill="currentColor"
     d="M11 6.67a1 1 0 1 0-2 0v2.66a1 1 0 0 0 2 0V6.67ZM10 14.5a1.25 1.25 0 1 0 0-2.5 1.25 1.25 0 0 0 0 2.5Z"

package/packages/ui/dist/assets/{x-DB1YTl_6.js → x-DuFufU-Y.js} RENAMED Viewed

@@ -1,4 +1,4 @@
-import{F as l}from"./core-DJKvcaym.js";import"./index-CBEcDgJN.js";import"./events-cYLbpQpi.js";import"./index.es-D8L0a50U.js";import"./fallback-mNp6Xdgm.js";const a=l`<svg fill="none" viewBox="0 0 41 40">
+import{F as l}from"./core-CqvnE8sM.js";import"./index-DOy_BvMy.js";import"./events-D_3qqJ93.js";import"./index.es-Cz1WraDz.js";import"./fallback-BDBC0epM.js";const a=l`<svg fill="none" viewBox="0 0 41 40">
   <g clip-path="url(#a)">
     <path fill="#000" d="M.8 0h40v40H.8z" />
     <path

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-CBEcDgJN.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-DS-4Qz48.css">
+    <script type="module" crossorigin src="/assets/index-DOy_BvMy.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BODuSfdj.css">
   </head>
   <body>
     <div id="root"></div>

package/scripts/check-docs.mjs CHANGED Viewed

@@ -19,7 +19,7 @@
  * Run: `node scripts/check-docs.mjs` (or `pnpm docs:check`). Exit 1 on any miss.
  */
-import { readFileSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -159,8 +159,6 @@ const DOC_GLOBS = [
   "templates",
   "packages/cli/README.md",
   "packages/sdk/README.md",
-  "packages/chains/README.md",
-  "packages/create-app/README.md",
 ];
 function collectDocs() {
@@ -193,7 +191,54 @@ function codeRegions(md) {
   return regions;
 }
-// ── 4. Validate ──────────────────────────────────────────────────────────────
+// ── 4. Skills consistency ─────────────────────────────────────────────────────
+//
+// The scaffolded template ships agent skills under .agents/skills/. AGENTS.md is
+// the routing layer: it must point at every skill that exists, and every skill it
+// points at must exist with valid frontmatter — otherwise an agent either never
+// discovers a workflow or follows a dangling pointer.
+function checkSkills(errors) {
+  const skillsRoot = join(ROOT, "templates/default/.agents/skills");
+  const agentsPath = join(ROOT, "templates/default/AGENTS.md");
+  if (!existsSync(skillsRoot)) {
+    errors.push("templates/default/.agents/skills: directory missing");
+    return;
+  }
+  const agentsMd = readFileSync(agentsPath, "utf-8");
+  const dirs = readdirSync(skillsRoot).filter((d) =>
+    statSync(join(skillsRoot, d)).isDirectory(),
+  );
+  if (dirs.length === 0) errors.push("templates/default/.agents/skills: no skills found");
+  for (const d of dirs) {
+    const skillFile = join(skillsRoot, d, "SKILL.md");
+    if (!existsSync(skillFile)) {
+      errors.push(`templates/default/.agents/skills/${d}: missing SKILL.md`);
+      continue;
+    }
+    const fm = readFileSync(skillFile, "utf-8").match(/^---\n([\s\S]*?)\n---/);
+    if (!fm) {
+      errors.push(`${rel(skillFile)}: missing YAML frontmatter`);
+      continue;
+    }
+    const name = fm[1].match(/^name:\s*(\S+)\s*$/m)?.[1];
+    const description = fm[1].match(/^description:\s*(.+)$/m)?.[1]?.trim();
+    if (name !== d) errors.push(`${rel(skillFile)}: frontmatter name "${name}" ≠ directory "${d}"`);
+    if (!description) errors.push(`${rel(skillFile)}: frontmatter description missing or empty`);
+    if (!agentsMd.includes(`.agents/skills/${d}/SKILL.md`)) {
+      errors.push(`templates/default/AGENTS.md: routing table does not reference .agents/skills/${d}/SKILL.md`);
+    }
+  }
+  for (const m of agentsMd.matchAll(/\.agents\/skills\/([\w-]+)\/SKILL\.md/g)) {
+    if (!dirs.includes(m[1])) {
+      errors.push(`templates/default/AGENTS.md: references .agents/skills/${m[1]}/SKILL.md which does not exist`);
+    }
+  }
+}
+// ── 5. Validate ──────────────────────────────────────────────────────────────
 function main() {
   const cli = parseCliSurface();
@@ -242,6 +287,8 @@ function main() {
     }
   }
+  checkSkills(errors);
   // ── Report ───────────────────────────────────────────────────────────────
   const cliCount = cli.leaves.size + [...cli.groups.values()].reduce((n, s) => n + s.size, 0);
   const sdkCount =

package/scripts/check-init.mjs CHANGED Viewed

@@ -65,6 +65,18 @@ try {
     "foundry.toml",
     "mandates",
     "AGENTS.md",
+    ".sail/contracts/interfaces/IPermission.sol",
+    ".sail/contracts/interfaces/IBatchPermission.sol",
+    "test/BoundedCallPermission.t.sol",
+    "examples/custom-mandate/README.md",
+    ".agents/skills/sail-onboarding/SKILL.md",
+    ".agents/skills/sail-project-info/SKILL.md",
+    ".agents/skills/sail-servers/SKILL.md",
+    ".agents/skills/sail-transactions/SKILL.md",
+    ".agents/skills/sail-mandates/SKILL.md",
+    ".agents/skills/sail-mandates/references/approvals.md",
+    ".agents/skills/sail-ci/SKILL.md",
+    ".agents/skills/sail-extend/SKILL.md",
   ];
   for (const rel of mustExist) {
     if (!fs.existsSync(path.join(dest, rel))) fail(`expected scaffolded "${rel}" — not found`);

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

@@ -0,0 +1,66 @@
+---
+name: sail-ci
+description: Automate the agent on a schedule with GitHub Actions — exporting the encrypted keystore, committing the right files, configuring secrets, and driving the workflow with the gh CLI. Use when the user wants the agent to run on a schedule, in CI, or unattended after sailor run --once has been confirmed working.
+---
+# Sail CI — GitHub Actions automation
+The scaffolded workflow at `.github/workflows/agent-tick.yml` runs `npx sailor run --once` on a cron schedule (default: every Monday 09:00 UTC — edit the `cron` line to the user's cadence; `workflow_dispatch` allows manual runs). It uses `npm ci`, copies `ci-keystore.json` to `.sail/keys/manager.json`, and unlocks it with `SAIL_PASSPHRASE`. `CHAIN_ID` comes from the repository variable `CHAIN_ID` (default `8453`). No private key ever appears in the workflow or in secrets.
+Confirm `sailor run --once` works locally before automating.
+## 1. Export the keystore
+```bash
+sailor keys export-ci
+```
+Copies the encrypted agent wallet to `ci-keystore.json` in the project root and adds a `!ci-keystore.json` allowlist entry to `.gitignore`. The keystore is geth v3 encrypted (scrypt + aes-128-ctr); the raw private key is never exposed — safe to commit.
+## 2. Commit the required files
+CI needs these non-secret files in the repo:
+```bash
+npm install                  # generate package-lock.json if it doesn't exist
+git add ci-keystore.json package-lock.json .sail/account.json .sail/config.json .sail/mandate.json
+git commit -m "chore: add CI keystore and sail state" && git push
+```
+`package-lock.json` is required by `npm ci`. `.sail/account.json`, `.sail/config.json`, and `.sail/mandate.json` contain only public addresses and flags — no secrets. The `.gitignore` already has `!` exceptions for all of these.
+## 3. Add the two repository secrets
+GitHub → Settings → Secrets and variables → Actions:
+- `SAIL_PASSPHRASE` — the passphrase that encrypts the agent wallet
+- `RPC_URL` — the RPC endpoint
+(If the chain is not Base, also set the repository **variable** `CHAIN_ID` to the right chain id.)
+## 4. Install and authenticate the gh CLI
+Required to manage the workflow from the terminal (trigger runs, check logs, add secrets without the browser):
+- macOS: `brew install gh`
+- Windows: `winget install --id GitHub.cli` or `scoop install gh`
+- Linux: https://github.com/cli/cli/blob/trunk/docs/install_linux.md
+Authenticate with the `workflow` scope — without it, `gh` cannot trigger or inspect Actions runs:
+```bash
+gh auth login --scopes workflow
+gh auth status                            # confirm workflow scope is listed
+```
+## 5. Drive it
+```bash
+gh secret set SAIL_PASSPHRASE             # prompts for the value
+gh secret set RPC_URL
+gh workflow run agent-tick.yml            # manual trigger
+gh run list --workflow agent-tick.yml     # run history
+gh run view --log                         # logs of the latest run
+```
+A failing run's logs show the same stderr the local runner produces (`reverted: <txHash>`, `skipped: no registered permission…`) — debug with the sail-transactions skill.

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

@@ -0,0 +1,74 @@
+---
+name: sail-extend
+description: Recipes for extending a live agent with notifications (Telegram, email) and a strategy-specific dashboard. Use when the agent is running and the user asks for run/transaction alerts, monitoring, or a custom view of their strategy.
+---
+# Sail extend — notifications and custom dashboards
+These are user-land code the assistant writes into this project on request — not Sailor features. Build them only once the agent is live.
+## Notifications
+Two hook points, pick per the user's setup:
+1. **Inside the agent loop** (`src/agent.ts`) — fires on every tick, works locally and in CI. Send from within `tick()` after a meaningful event, or read `.sail/activity.jsonl` and alert on `dispatch_reverted` / `dispatch_denied` / `error` entries.
+2. **As a GitHub Actions step** (`.github/workflows/agent-tick.yml`) — fires once per scheduled run; simplest for run-level success/failure alerts.
+### Telegram (Bot API)
+One-time setup: create a bot with @BotFather (get `TELEGRAM_BOT_TOKEN`), have the user message the bot once, read their chat id from `https://api.telegram.org/bot<token>/getUpdates`. Store both as secrets/env — never hardcode.
+The exact curl shape:
+```bash
+curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
+  -d chat_id="${TELEGRAM_CHAT_ID}" \
+  --data-urlencode text="sailor: tick complete — 2 executed, 0 reverted"
+```
+As a CI step appended to `agent-tick.yml` (add `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` as repo secrets):
+```yaml
+      - name: Notify Telegram
+        if: always()
+        env:
+          TOKEN: ${{ secrets.TELEGRAM_BOT_TOKEN }}
+          CHAT: ${{ secrets.TELEGRAM_CHAT_ID }}
+        run: |
+          curl -s "https://api.telegram.org/bot${TOKEN}/sendMessage" \
+            -d chat_id="${CHAT}" \
+            --data-urlencode text="agent-tick: ${{ job.status }} — $(date -u +%FT%TZ)"
+```
+From `src/agent.ts`, the same call via `fetch()` inside `tick()` — gate it so a notification failure never throws into the tick (wrap in try/catch; a lost alert must not stop a dispatch).
+### Email (CI step)
+Simplest reliable path is a provider action in the workflow, e.g. `dawidd6/action-send-mail` with SMTP credentials in secrets:
+```yaml
+      - name: Email on failure
+        if: failure()
+        uses: dawidd6/action-send-mail@v3
+        with:
+          server_address: smtp.example.com
+          server_port: 465
+          username: ${{ secrets.MAIL_USERNAME }}
+          password: ${{ secrets.MAIL_PASSWORD }}
+          subject: "Sail agent tick failed"
+          to: user@example.com
+          from: sailor-agent
+          body: "Run ${{ github.run_id }} failed. Check gh run view --log."
+```
+For local runs, email is rarely worth a daemon — prefer Telegram, or pipe `.sail/activity.jsonl` into whatever the user already monitors.
+## Custom dashboard
+The stock dashboard (`sailor ui start`) shows account state, mandate health, balances, and activity. A strategy-specific view (price chart + portfolio for a trading agent; health factor + yield for a lending agent) is a small app the assistant builds reading:
+- `.sail/activity.jsonl` — every dispatch with txHash, gas, denial reasons, owner signing events; append-only JSON lines, trivially tailable.
+- `.sail/account.json` / `.sail/state/mandates.json` — the SMA address and the permission set to display.
+- On-chain state via the SDK: `import { SailorClient } from '@sail.money/sailor/sdk'` for kernel/mandate reads, or any viem `PublicClient` for balances and protocol positions.
+Keep it local and read-only: a small server (or static page polling a tiny endpoint) that reads `.sail/` and the chain. Do not put keys, passphrases, or write operations in a dashboard. Pick a port outside 3333–3999 (reserved by per-project Sailor UIs) and 3141 (signing station).

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

@@ -0,0 +1,93 @@
+---
+name: sail-mandates
+description: The full permission-contract lifecycle — designing bounds with the user, authoring Solidity permissions, Foundry testing, deploying, simulating, and authorizing on the SMA, plus revoke/update/list and clone templates. Use when anything touches a permission contract or the mandate: writing or changing what the agent is allowed to do, deploying or attaching permissions, or verifying them before authorization.
+---
+# Sail mandates
+The lifecycle is an ordered set of gates. **The order is the correctness model** — skipping a gate or reordering them is how funds get lost. Never authorize (attach) anything that has not passed every earlier gate.
+## Gate 1 — Pin the strategy bounds with the user
+Establish, explicitly: tokens, amounts, venues, slippage, recipients. Philosophy: **every meaningful financial bound is enforced on-chain in Solidity**; only frequency/cadence lives in agent TypeScript. If a bound matters and it is not in a permission contract, it is not a bound.
+## Gate 2 — Enumerate approvals and pick the execution model
+List every ERC-20 `approve()` the strategy implies — protocol permissions never cover `approve()`, so each needs explicit coverage. How it is covered depends on the model you choose (read [references/approvals.md](references/approvals.md) before writing any contract):
+- **Per-call (default).** Approve and act are separate single-call dispatches, each gated by its own `IPermission`. Approve a sufficient allowance once and skip it when the on-chain allowance already covers the next action (the `examples/dca/` pattern). This is what the scaffolded `IPermission` supports out of the box.
+- **Atomic batch (advanced).** Approve + action run as one `dispatchBatch`. A batch consults exactly ONE batch-aware `IBatchPermission` (`evaluateBatch`) that validates the whole sequence — NOT two narrow `IPermission`s. Use this only when atomicity matters; see `references/approvals.md`. Do not mix the models.
+## Gate 3 — Author the permission contracts
+Permission contracts live in `mandates/`. The user authors, reviews, and owns them. Start from the worked examples — see [references/examples-index.md](references/examples-index.md) for what each `examples/permissions/*.sol` teaches — adapt them, never present them as audited or as a closed menu.
+- Implement `IPermission.evaluate(bytes txData, Context ctx) → bool` (single-call) or `IBatchPermission.evaluateBatch(Call[] calls, BatchContext ctx) → bool` (batch). Interfaces are vendored under `.sail/contracts/`.
+- Use the `SailCalldata` library for bounded calldata decoding — slot-indexed reads after the 4-byte selector prevent silent truncation bugs.
+- Bind recipients/beneficiaries to `ctx.account` wherever the protocol exposes them — funds must route to the SMA.
+- **Selector correctness is life-or-death.** Verify every selector against the venue's authoritative deployed ABI — `cast sig "fn(types…)"` against the verified source — never from memory. A wrong selector fails closed (every legitimate call rejected) or worse, gates nothing. Real precedents: Venice staking is `stake(address,uint256)` = `0xadc9772e`, not `stake(uint256)` = `0xa694fc3a`; GMX v2's `createOrder` struct has changed across router versions — recompute the selector against the exact router the agent calls.
+Prerequisite — Foundry. If `forge` is not found:
+```bash
+curl -L https://foundry.paradigm.xyz | bash   # then restart shell
+foundryup
+```
+## Gate 4 — Write and run Foundry tests BEFORE any deployment
+`test/BoundedCallPermission.t.sol` is the scaffolded example — copy it for each permission you author. Write tests that call `evaluate()` (and `evaluateBatch()` for batch permissions) directly with calldata derived from the user's stated strategy:
+- **Accept cases**: every call the strategy must make.
+- **Reject cases**: out-of-bounds amounts, wrong tokens, wrong recipients, wrong selectors, unbound venues.
+```bash
+forge build
+forge test
+```
+This gate comes before deployment because it is the only gate that exercises your boundary logic with full control of inputs, at zero cost. Do not deploy a permission whose tests do not pass.
+## Gate 5 — Deploy (deploy only — never --attach yet)
+```bash
+sailor mandate deploy --contract <Name> --sma <SMA> --json   # BLOCKS — owner signs the contract-creation tx in the browser
+```
+The owner pays gas; the deployed address is read from the receipt and tracked in `.sail/state/mandates.json`. Add `--build` to run `forge build` first.
+Constructor args: `--args '["0xToken","1000000"]'` (JSON array, inline, bash) or `--args-file args.json` (any shell — required on PowerShell). Full per-shell quoting rules: [references/constructor-args.md](references/constructor-args.md). Values are coerced to the constructor's ABI types (uint→bigint, etc.) and the array length is validated.
+## Gate 6 — Simulate against must-pass AND must-fail samples
+`evaluate()` lives on the deployed contract, so simulate after deploy and before the irreversible authorization. Generate sample calls from the user's stated strategy — ones the permission MUST accept and ones it MUST reject:
+```bash
+sailor mandate simulate --address <PermissionOrName> --sma <SMA> --calls calls.json --json
+```
+This is an off-chain `eth_call` — no gas, no signing. It reports what `evaluate()` returns per call, flags any target with no contract code on this chain (wrong or wrong-chain address), and checks whether each 4-byte selector actually routes on the target's bytecode. A mismatch between `expect` and the actual result exits non-zero. **Zero mismatches required before proceeding.** Simulate proves what the permission DOES; it does not guarantee it is correct.
+`calls.json` schema: [references/calls-schema.md](references/calls-schema.md). How to design pass/fail cases: [references/simulate-calls.md](references/simulate-calls.md).
+**Batch permissions:** simulate probes single-call `evaluate()` only — it does not exercise `evaluateBatch()`. Verify batch permissions by calling `evaluateBatch(calls, ctx)` directly via `cast call` with pass and fail batches before attaching.
+## Gate 7 — Attach (authorize)
+```bash
+sailor mandate attach --address <PermissionOrName> --sma <SMA> --json   # BLOCKS — owner signs RegisterPermission EIP-712 in the browser
+```
+Only now is the permission live. The owner (mandate signer) signs in the browser; the agent submits the registration and pays gas plus any registration fee. **Fund the agent wallet before attaching**, or this step fails with `gas required exceeds allowance`. The CLI verifies the signature came from the on-chain mandate signer — a wrong connected wallet is rejected. After confirmation it polls `getPermissions()` until the permission appears. Per-call model: attach every permission the strategy needs (bounded-approve alongside the protocol permission) in one signing session.
+## Maintenance
+- `sailor mandate revoke --address <P> --sma <SMA> --json` (or `--all`) — owner signs `RevokePermissions` in the browser (BLOCKS); agent submits. Revocations are recorded to the activity log; `state/mandates.json` keeps the historical record.
+- `sailor mandate update --address <P> --name/--source-path/--artifact-path` — fix tracked metadata.
+- `sailor mandate list` — everything deployed from this project, with attachments.
+- `sailor mandate sign` — reviews the permission set and reconciles against live on-chain `getPermissions()` before writing `mandate.json`; permissions revoked on-chain are excluded even if still in local state. `--yes` for non-interactive use.
+- `sailor account rotate-signer` — rotates the agent wallet and re-approves attached mandates (BLOCKS on browser); `--reattach-only` resumes after funding, `--list` shows known agent wallets.
+## 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`.

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

@@ -0,0 +1,42 @@
+# ERC-20 approve coverage
+## The rule
+Protocol permissions (supply, swap, deposit, stake, …) do NOT cover ERC-20 `approve()`. The kernel evaluates the approve as its own call: an agent that calls `approve()` without authorizing coverage for it is rejected, and the tick fails.
+There are two ways to cover and execute an approve + action. Pick ONE; they are not mixable.
+## Model A — per-call (default, simplest)
+Approve and action are **separate single-call dispatches**, each gated by its own `IPermission`. This is what the scaffolded `IPermission` interface and the `examples/dca/` agent use.
+1. Deploy a bounded-approve `IPermission` covering the `(token, spender, max amount)` triple — a clone where available:
+   ```bash
+   sailor mandate deploy-clone --template boundedApprove --sma <SMA> \
+     --tokens <token,...> --spenders <spender,...> --max <amount>
+   ```
+   or a custom `IPermission` that bounds the approve's spender and amount.
+2. Deploy the protocol `IPermission` (swap/supply/…). Attach both in one signing session.
+3. At runtime, manage the allowance instead of approving every tick: read the on-chain allowance, emit an approve dispatch ONLY when it is insufficient, approving a large amount so subsequent ticks skip it. The DCA example does exactly this — it returns the approve as its own tick's dispatch, then swaps on later ticks once the allowance is set.
+This needs no batch support and works on every kernel.
+## Model B — atomic batch (advanced)
+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.
+- 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`.
+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.
+## Verifying each model
+- **Model A:** `sailor mandate simulate` probes each `IPermission`'s single-call `evaluate()`. See `simulate-calls.md`.
+- **Model B:** `simulate` does NOT cover batch permissions. Validate the exact `[approve, action]` sequence through the kernel's `previewBatch` view (no gas, no signing) — `sailor run --once` exercises this path against a registered batch permission, or call the permission's `evaluateBatch` view directly with `cast call`.
+## Kernel-model corollary (conjunctive only)
+On a conjunctive kernel ALL registered permissions must return true on EVERY call, so two narrow approve permissions (one per token) brick each other. Use ONE approve permission allowing all needed tokens. On selective kernels — all currently bundled chains — each dispatch names exactly one permission, so this does not apply.

package/templates/default/.agents/skills/sail-mandates/references/calls-schema.md ADDED Viewed

@@ -0,0 +1,42 @@
+# calls.json — batch schema for `sailor mandate simulate`
+A non-empty JSON array. Each entry is one sample call probed against the permission's `evaluate()`:
+```json
+[
+  {
+    "target": "0xVenueContract",
+    "calldata": "0x04e45aaf…",
+    "value": "0",
+    "expect": "pass",
+    "label": "swap 100 USDC → WETH within bounds"
+  },
+  {
+    "target": "0xVenueContract",
+    "calldata": "0x04e45aaf…",
+    "expect": "fail",
+    "label": "swap exceeding MAX_AMOUNT_IN — must be rejected"
+  }
+]
+```
+| Field | Required | Meaning |
+|---|---|---|
+| `target` | yes | Call target address (the venue contract) |
+| `calldata` | yes | 0x-prefixed hex calldata (`data` also accepted as the key) |
+| `value` | no | ETH value in wei, integer or numeric string; default `0` |
+| `expect` | no | `"pass"` or `"fail"`. Any mismatch with the actual result makes the command exit non-zero |
+| `label` | no | Human-readable description shown per result; defaults to `call N` |
+## What simulate reports per call
+- `result`: `pass` (evaluate returned true) or `fail`, with `reverted`/`revertReason` when evaluate() reverted rather than returning false.
+- `targetHasCode`: whether the target has contract code on this chain — `false` means a wrong or wrong-chain address; that call would fail on-chain regardless of the permission.
+- `selectorRoutes`: whether the calldata's 4-byte selector is found in the target's bytecode (`null` for proxies, where the check is indeterminate). `false` strongly suggests a wrong selector.
+- `match`: per-call expectation verdict; `mismatches` summarizes. JSON output (`--json`) carries all of the above plus `submitterIsStandIn` (no local manager key — a stand-in submitter was used) and `blockContextStale` (block fetch failed; time/block-gated permissions may show false negatives).
+## Rules of use
+- Derive samples from the user's stated strategy: every call the agent must make → `expect: "pass"`; boundary violations (too-large amount, wrong token, wrong recipient, wrong venue) → `expect: "fail"`.
+- Do not authorize until every sample matches — zero mismatches.
+- Batch permissions: simulate exercises single-call `evaluate()` only. Probe `evaluateBatch(calls, ctx)` directly with `cast call` for batch verification.

package/templates/default/.agents/skills/sail-mandates/references/constructor-args.md ADDED Viewed

@@ -0,0 +1,45 @@
+# Constructor args — per-shell quoting
+`sailor mandate deploy` takes constructor arguments as a JSON array. The CLI validates the array length against the constructor's ABI and coerces each value to its ABI type: `uint*`/`int*` → bigint (pass numbers as strings to avoid precision loss), `bool` → boolean, arrays recursively.
+## Bash / Git Bash / zsh
+Single quotes around the whole array; inner double quotes survive:
+```bash
+sailor mandate deploy --contract <Name> --args '["0xToken","1000000"]' --sma <SMA>
+```
+Nested arrays work the same way:
+```bash
+sailor mandate deploy --contract <Name> --args '["0xSigner",["0xTargetA","0xTargetB"]]' --sma <SMA>
+```
+## PowerShell
+Inline JSON is unreliable in PowerShell — quote stripping mangles the array even with escaped inner quotes. **Do not pass `--args` inline from PowerShell.** Use `--args-file`:
+```powershell
+sailor mandate deploy --contract <Name> --args-file args.json --sma <SMA>
+```
+(If you must inline, the escaped form is `--args '[\"0xToken\",\"1000000\"]'` — but prefer the file.)
+## Any shell — `--args-file` (recommended whenever quoting bites)
+Write the array to a file, no quoting rules at all:
+```json
+["0xToken", "1000000"]
+```
+```bash
+sailor mandate deploy --contract <Name> --args-file args.json --sma <SMA>
+```
+## Errors you will see
+- `Constructor takes no arguments but --args were provided` — drop `--args`.
+- `Constructor expects N argument(s)` — pass exactly N elements, in declaration order.
+- `--args must be a JSON array of N element(s)` — the JSON parsed but the length is wrong, or it is not an array (a shell ate your quotes).

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

@@ -0,0 +1,31 @@
+# examples/permissions/ — index
+Worked reference permissions, one bounding pattern each. They are **not audited, not maintained by Sail core, and not a menu** — adapt them to the user's strategy. Each contract's header documents what is ENFORCED ON-CHAIN vs AGENT-ENFORCED / NOT BOUNDED — read that split before borrowing anything.
+Permissions only bound on-chain actions: venues with off-chain order matching (Polymarket, Hyperliquid) cannot be bounded this way; fully on-chain venues (Uniswap, Aave, GMX, Limitless) can.
+| File | Protocol / chain | Teaches | Key verified selectors |
+|---|---|---|---|
+| `BoundedSwap_UniswapV3_Base.sol` | Uniswap V3 SwapRouter02 · Base | Selector allowlist + amount cap + tokenOut allowlist + min-out slippage floor (MIN_BPS) | `0x04e45aaf` exactInputSingle (SwapRouter02), `0x095ea7b3` approve |
+| `BoundedSwap_UniswapV4_Unichain.sol` | Uniswap V4 Universal Router · Unichain | Decoding command/action bytes: single V4_SWAP command, single SWAP_EXACT_IN_SINGLE action, currency + amount + slippage bounds | `0x3593564c` execute(bytes,bytes[],uint256), `0x24856bc3` execute(bytes,bytes[]) |
+| `BoundedBorrow_AaveV3_Arbitrum.sol` | Aave V3 Pool · Arbitrum | Asset allowlist + borrow cap + `onBehalfOf == ctx.account` binding + rate-mode allowlist (use [2]; stable deprecated in V3.1) | `0xa415bcad` borrow(address,uint256,uint256,uint16,address) |
+| `BoundedSupply_AaveV3_Arbitrum.sol` | Aave V3 Pool · Arbitrum | SailCalldata-based decoding; supply cap + `onBehalfOf == ctx.account`; supply does NOT gate withdrawal, and the prior approve needs its own permission | `0x617ba037` supply(address,uint256,address,uint16) |
+| `BoundedVault_ERC4626_Base.sol` | ERC-4626 standard · any EVM | Vault allowlist; deposit capped + receiver bound; withdraw/redeem receiver+owner bound but amount-unbounded (SMA can always fully exit) | `0x6e553f65` deposit, `0xb460af94` withdraw, `0xba087652` redeem |
+| `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 |
+| `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
+- **Venice — the wrong-selector bug.** The live contract's function is `stake(address,uint256)` = `0xadc9772e`. The intuitive single-arg `stake(uint256)` = `0xa694fc3a` does not exist on the target. Gating the wrong selector fails closed: every legitimate stake silently rejected. Always confirm the selector against the deployed contract.
+- **GMX — versioned ABIs drift.** GMX has multiple ExchangeRouter deployments and the `CreateOrderParams` struct has gained fields over time. Before deploying: pick the exact router the agent calls, read its verified ABI, recompute with `cast sig "createOrder(<exact tuple>)"`, and update the selector and struct if they differ. The committed `0x212234c3` is verified against gmx-io/gmx-synthetics at time of writing — re-verify anyway.
+- **Limitless — unverified ABI as a worked warning.** The exchange address and `buy` signature are inferred from CTF patterns, not verified against the deployed contract. The contract's own header lists the verification steps; do them before any deploy.
+- **Batch permissions and simulate.** `BoundedApproveAndCallBatch` bounds the token/spender/amount and the consuming target+selector, optionally amount-matching the consume to the approve — but it does NOT bound where the consuming call routes funds. Pair it with a recipient-binding single-call permission, or choose consuming selectors that structurally pay msg.sender. `sailor mandate simulate` cannot exercise `evaluateBatch()` — verify with `cast call` pass/fail batches.
+## 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`.
+- `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-mandates/references/simulate-calls.md ADDED Viewed

@@ -0,0 +1,58 @@
+# Designing simulate cases (calls.json)
+## Schema
+`calls.json` is an array of sample calls. Full field reference: [calls-schema.md](calls-schema.md).
+```json
+[
+  {
+    "label": "approve USDC to router at cap",
+    "target": "0xA0b8...USDC",
+    "calldata": "0x095ea7b3...",
+    "expect": "pass"
+  },
+  {
+    "label": "approve over the cap",
+    "target": "0xA0b8...USDC",
+    "calldata": "0x095ea7b3...",
+    "expect": "fail"
+  }
+]
+```
+Fields: `target`, `calldata`, optional `value`, `expect` (`"pass"` or `"fail"`), `label`.
+## Deriving cases from the strategy
+**Must-pass:** one entry per distinct call the agent will make — the approve at its cap, the swap/supply with exact in-bounds parameters, and so on.
+**Must-fail:** mutate each bound one at a time:
+- wrong token, spender, or recipient
+- amount over the cap
+- slippage / minimum-out below the floor
+- wrong target contract; wrong selector
+- nonzero ETH `value` when not allowed
+A permission simulated with no must-fail cases is untested — passing everything is exactly how a broken (too-permissive) permission behaves.
+## Running
+```bash
+# batch
+sailor mandate simulate --address <PermissionOrName> --sma <SMA> --calls calls.json
+# one call inline
+sailor mandate simulate --address <PermissionOrName> --sma <SMA> \
+  --target <addr> --calldata <hex> --expect pass
+```
+- Off-chain `eth_call` — no gas, no signing, uses the same evaluation context as the runner.
+- Flags any target with no contract code (wrong or wrong-chain address).
+- Any `expect` mismatch → non-zero exit → do NOT attach. `--json` for automation.
+## Limits
+- Simulates the single-call `evaluate()` only — batch permissions need a direct `cast call` to their batch view; see `approvals.md`.
+- Proves behavior, not intent: the contract still needs review and forge tests.