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

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.

package/templates/default/.agents/skills/sail-templates/catalog.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+// sail-templates / catalog.mjs
+// Tracks the shared permission templates that live in
+//   Protocol/contracts/templates/*.sol
+// These are configurable singletons (extend ConfigurablePermission): deploy once
+// per chain, then every SMA reuses that address via REGISTER + CONFIGURE (attach only
+// registers on the kernel; configure writes the per-account bounds — see SKILL.md).
+// All seven are deployed (2026-07-01, CREATE2 global salt) — same address on every chain.
+// Deployment status is read from deployed.json next to this file.
+//
+// The template LIST is auto-detected from source (so it tracks additions/removals),
+// the rich per-template detail is curated below, and deployment status is read from
+// deployed.json.
+//
+// Usage:
+//   node catalog.mjs                # human view, all detected templates
+//   node catalog.mjs --json         # machine-readable
+//   node catalog.mjs --chain 8453   # deployment status for one chain
+//   node catalog.mjs --protocol /path/to/Protocol   # override Protocol dir
+
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+const CHAIN_NAMES = {
+  1: "Ethereum", 8453: "Base", 42161: "Arbitrum", 10: "Optimism", 130: "Unichain",
+  56: "BSC", 480: "World Chain", 999: "HyperEVM", 4326: "MegaETH",
+  84532: "Base Sepolia", 11155111: "Sepolia",
+};
+
+// Curated detail, keyed by the Solidity contract name. Config blobs are the
+// authoritative abi.encode tuples taken from each contract's `_applyConfig`.
+const META = {
+  SwapPermission: {
+    primitive: "DEX swaps (Uniswap V3 / V3-02 / V2)",
+    skill: "sail-template-swap",
+    config: "(address[] routers, address[] tokensIn, address[] tokensOut, uint256 maxAmountPerTx, uint256 maxSlippageBps, address priceOracle, uint256 maxPriceAgeSec)",
+  },
+  SwapPermissionNoOracle: {
+    primitive: "DEX swaps for tokens with NO oracle — live-pool hallucination band (NOT manipulation-resistant)",
+    skill: "sail-template-swap-no-oracle",
+    config: "(address[] routers, address[] tokensIn, address[] tokensOut, uint256 maxAmountPerTx, ReferencePool[] referencePools) — ReferencePool{address tokenIn, address tokenOut, address pool, PoolKind kind (0=V2,1=V3), uint256 toleranceBps}",
+  },
+  BorrowPermission: {
+    primitive: "Lending borrows (Aave / Morpho / Compound) with LTV check",
+    skill: "sail-template-borrow",
+    config: "(address[] protocols, address[] assets, uint256 maxAmountPerTx, uint256 maxLtvBps, address collateralOracle, address borrowOracle, uint256 maxPriceAgeSec)",
+  },
+  TransferPermission: {
+    primitive: "ERC-20 transfers to a recipient allowlist (from == account)",
+    skill: "sail-template-transfer",
+    config: "(address[] allowedRecipients, address[] allowedTokens, uint256 maxAmountPerTx)",
+  },
+  DepositPermission: {
+    primitive: "Vault / lending deposits (ERC-4626 + Aave v2/v3)",
+    skill: "sail-template-deposit",
+    config: "(address[] targets, address[] tokens, uint256 maxAmountPerTx)",
+  },
+  WithdrawPermission: {
+    primitive: "ERC-20 withdrawals to a single fixed recipient",
+    skill: "sail-template-withdraw",
+    config: "(address[] tokens, address allowedRecipient, uint256 maxAmountPerTx)",
+  },
+  ApproveAndCallBatchPermission: {
+    primitive: "Atomic approve / consuming-call / reset-to-zero batch",
+    skill: "sail-template-approve-batch",
+    config: "Config{ address[] tokens, address[] spenders, ConsumingPair[] consumingPairs /* (address target, bytes4 selector) */, uint256[] maxApprovalAmounts, bool requireAmountMatch, bool allowUnconstrainedRecipient /* default false = recipient pinned to account; true = opt out */ }",
+  },
+};
+
+function argValue(flag) {
+  const i = process.argv.indexOf(flag);
+  return i >= 0 ? process.argv[i + 1] : null;
+}
+const hasFlag = (flag) => process.argv.includes(flag);
+
+function findProtocolDir() {
+  const fromArg = argValue("--protocol");
+  if (fromArg) return resolve(fromArg);
+  if (process.env.SAIL_PROTOCOL_DIR) return resolve(process.env.SAIL_PROTOCOL_DIR);
+  for (const start of [process.cwd(), HERE]) {
+    let dir = start;
+    for (let i = 0; i < 8; i++) {
+      if (existsSync(join(dir, "Protocol", "contracts", "templates"))) return join(dir, "Protocol");
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  }
+  return null;
+}
+
+// Detect concrete templates from source: `contract X is ... ConfigurablePermission ...`
+// (skips `abstract contract`, e.g. the ConfigurablePermission base itself).
+function detectTemplates(protocolDir) {
+  const dir = join(protocolDir, "contracts", "templates");
+  const out = [];
+  for (const file of readdirSync(dir).filter((f) => f.endsWith(".sol"))) {
+    const src = readFileSync(join(dir, file), "utf8");
+    const m = src.match(/^\s*contract\s+(\w+)\s+is\s+([^{]+)\{/m);
+    if (!m) continue;
+    if (!/ConfigurablePermission/.test(m[2])) continue;
+    out.push({ name: m[1], file: `contracts/templates/${file}` });
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function loadDeployed() {
+  const path = join(HERE, "deployed.json");
+  if (!existsSync(path)) return { chains: {} };
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return { chains: {} };
+  }
+}
+
+function statusFor(deployed, name) {
+  const rows = [];
+  for (const [chainId, map] of Object.entries(deployed.chains ?? {})) {
+    const addr = map?.[name];
+    rows.push({ chainId: Number(chainId), name: CHAIN_NAMES[chainId] ?? `chain ${chainId}`, address: addr ?? null });
+  }
+  return rows.sort((a, b) => a.chainId - b.chainId);
+}
+
+function main() {
+  const protocolDir = findProtocolDir();
+  if (!protocolDir) {
+    console.error("Could not locate Protocol/contracts/templates. Pass --protocol <path> or set SAIL_PROTOCOL_DIR.");
+    process.exit(1);
+  }
+  const templates = detectTemplates(protocolDir);
+  const deployed = loadDeployed();
+  const onlyChain = argValue("--chain");
+
+  const catalog = templates.map((t) => ({
+    ...t,
+    ...(META[t.name] ?? { primitive: "(uncurated — see source)", skill: null, config: "(see source)" }),
+    deployments: statusFor(deployed, t.name).filter((r) => !onlyChain || r.chainId === Number(onlyChain)),
+  }));
+
+  // IOracle adapters usable as `priceOracle` in SwapPermission config (deployed.json `oracles`).
+  const oracles = [];
+  for (const [chainId, byLabel] of Object.entries(deployed.oracles ?? {})) {
+    if (onlyChain && Number(chainId) !== Number(onlyChain)) continue;
+    for (const [label, o] of Object.entries(byLabel ?? {})) {
+      oracles.push({ chainId: Number(chainId), name: CHAIN_NAMES[chainId] ?? `chain ${chainId}`, label, ...o });
+    }
+  }
+
+  if (hasFlag("--json")) {
+    console.log(JSON.stringify({ protocolDir, templates: catalog, oracles }, null, 2));
+    return;
+  }
+
+  console.log("Sail shared permission templates — source: Protocol/contracts/templates\n");
+  console.log("Model: configurable singletons. Deploy ONCE per chain, then every SMA reuses the");
+  console.log("address via register (`sailor mandate attach`) + configure (no per-SMA deploy).");
+  console.log("NOTE: `sailor mandate attach` registers ONLY — you must also configure per-account");
+  console.log("(configureDirect today); see SKILL.md / references/reuse-flow.md.\n");
+  const anyUncurated = catalog.some((t) => !META[t.name]);
+  for (const t of catalog) {
+    const flag = META[t.name] ? "" : "  ⚠️ NEW/uncurated — add to META + write a skill";
+    console.log(`━━ ${t.name}${flag} ━━`);
+    console.log(`   primitive: ${t.primitive}`);
+    console.log(`   source:    ${t.file}`);
+    if (t.skill) console.log(`   skill:     ${t.skill}`);
+    console.log(`   config:    ${t.config}`);
+    const live = t.deployments.filter((d) => d.address);
+    if (live.length) {
+      console.log("   deployed:");
+      for (const d of t.deployments) {
+        console.log(`     ${d.name} (${d.chainId}): ${d.address ?? "— not yet deployed"}`);
+      }
+    } else {
+      console.log("   deployed:  not yet on any tracked chain (record in deployed.json once deployed)");
+    }
+    console.log("");
+  }
+  if (oracles.length) {
+    console.log("━━ IOracle adapters (usable as SwapPermission `priceOracle`) ━━");
+    for (const o of oracles) {
+      const pairs = (o.pairs ?? []).map((p) => p.label ?? `${p.base}/${p.quote}`).join(", ");
+      console.log(`   ${o.label} (${o.name} ${o.chainId}): ${o.address}${o.default ? "  [default]" : ""}`);
+      console.log(`     kind: ${o.kind ?? "?"}${o.twapWindowSec ? `, twap=${o.twapWindowSec}s` : ""}, decimals: ${o.priceDecimals ?? "?"}, pairs: ${pairs || "?"}`);
+      if (o.note) console.log(`     ↳ ${o.note}`);
+    }
+    console.log("");
+  }
+  if (anyUncurated) {
+    console.log("⚠️  A source template has no curated metadata above — the source folder changed.");
+  }
+  console.log("⚠️  Shared templates are UNAUDITED EXAMPLES — not part of the trusted core.");
+  console.log("   Always `sailor mandate simulate` against your SMA before authorizing on-chain.");
+}
+
+main();