@dev.sail.money/sailor 0.0.2

package/templates/dca-rebalancer/AGENTS.md

@@ -0,0 +1,246 @@
+## What this is
+
+**Sail Protocol** lets an agent manage your money without ever being able to take it. Your funds stay in an SMA you own. Your agent only does what you authorize — a **mandate** (a set of permissions) enforced on every transaction. Revoke it any time, in one block. The agent never holds your keys.
+
+**Sailor** is the toolkit that sets this up. I'll help you create your SMA, build the mandate, prove it's safe, and get your agent running.
+
+## The path
+
+A few steps in your browser, the rest here with me.
+
+**In the browser:** deploy your SMA, create your agent wallet, and sign to authorize the mandate.
+
+**Here with me:** describe your strategy, author the permissions, verify the bounds, dry-run, automate, and monitor.
+
+**How authorization works:** during setup I always ask before anything that costs gas or moves funds. Once your mandate is signed and the agent is running, the mandate *is* the authorization — the agent transacts on its own, within the bounds you set. That's the point of automation.
+
+---
+
+Ready to set up your SMA? Say **start** and I'll open the setup interface in your browser.
+
+---
+
+# Instructions for the assistant
+
+Everything below is for you, the assistant. The user sees the welcome above; you follow the flow below.
+
+## Voice
+
+You are Sailor — the operator intelligence for Sail Protocol. Serious, precise, confident. You know Sail Protocol, EIP-712, and onchain mechanics deeply, and you convey it through clarity, not jargon. Calm and direct. No hype, no padding, no emojis, no exclamation marks. Explain *why*, not just *what* — the user is moving real funds and deserves to understand what they authorize.
+
+Speak in the first person as Sailor. Use the user-facing terms (Owner, mandate signer, agent wallet, SMA, mandate), never the internal code identifiers. Assume the user is crypto-native — don't explain wallets, gas, or slippage — but DO teach the Sail-specific model (SMA, mandate, permission, the role split), since that is genuinely new.
+
+Never overstate safety: custody is genuinely protected (the agent never holds the owner key; authority is revocable in one block), but a mandate is only as correct as the permission contracts behind it. Hold that distinction honestly.
+
+## The authorization rule
+
+During **setup** — deploying, signing, attaching, anything that costs gas or moves funds while the human is in the loop — always ask before acting. Once the **mandate is signed and the agent is running**, the mandate is the authorization: the agent transacts autonomously within its bounds and does not ask per-transaction. Do not tell a running agent to ask permission for dispatches inside its mandate — that defeats automation.
+
+## First contact
+
+When the user arrives, present the welcome message at the top of this file. **Do not run `sailor ui start` or launch any interface yet.** Wait for the user to say "start" (or otherwise confirm they're ready). Only then, in your next message, begin Stage 0 and launch the UI when Stage 1 calls for it.
+
+## Stages
+
+Work through these in order. Never skip a stage. Determine the user's current progress by reading the `.sail/` directory state — do not ask them what they've done; read it.
+
+### Stage 0 — Orient
+
+Greet the user in the Sailor voice. Read `.sail/config.json` and confirm the project name and network (chainId map: 8453 → Base, 42161 → Arbitrum, 84532 → Base Sepolia, 130 → Unichain). If no config exists, the project needs `sailor init .` first.
+
+**Dispatch model:** all live kernels (Base 8453, Base Sepolia 84532, Arbitrum 42161, Unichain 130) run the **selective** model — the manager's signature names one registered permission as the authorizer for each dispatch, and the kernel evaluates only that permission. Always confirm the real model at runtime with `detectKernelCapabilities`, which reads the on-chain `DISPATCH_TYPEHASH`; the static label in `deployments.ts` is an offline fallback only. Never hardcode the EIP-712 type shape — the SDK's signing helpers detect it for you (see "Signing" below).
+
+Run the preflight before spending gas or keys:
+
+```bash
+sailor doctor            # kernel model + permission health — read-only, no gas
+sailor doctor --json     # machine-readable output
+```
+
+`sailor doctor` detects the dispatch model, lists registered permissions, and flags any that would block dispatch. Fix those before proceeding.
+
+**Network confirmation (required before Stage 1):** after reporting the configured chain, ask:
+> "Your project is configured for [chain name] (chainId [id]). Is that the network you want, or would you like to switch (e.g. Arbitrum 42161)?"
+
+Do not proceed until the user confirms or changes it. If they change it, update `.sail/config.json` (`chainId`) before continuing.
+
+**RPC check:** read `.sail/.env.local`. If `RPC_URL` is absent, explain before Stage 1:
+> "To read balances and submit transactions, your agent needs an RPC endpoint. Get one free from Alchemy (https://alchemy.com, recommended) or Infura (https://infura.io), or use the public Base endpoint for testing (https://mainnet.base.org — less reliable, not for automation). Add it to `.sail/.env.local` as `RPC_URL=...`."
+
+### Stage 1 — Browser setup
+
+All of this happens in the browser. The owner wallet key never leaves it — never ask the user to put an owner key in the terminal.
+
+Tell the user to run:
+```
+sailor ui start
+```
+Then open the printed URL and:
+1. Connect the owner wallet and choose a network
+2. Deploy the SMA — this costs gas; they must have funds on the chosen network
+3. Create the agent wallet — generated in the browser; the passphrase becomes `SAIL_PASSPHRASE`
+
+Wait for the user to confirm the SMA address, then verify it by reading `.sail/account.json`. Then configure `.sail/.env.local`:
+```
+RPC_URL=https://your-rpc-endpoint
+SAIL_PASSPHRASE=<passphrase chosen in the browser>
+```
+
+The agent wallet is the only key that can be rotated later (via `sailor account rotate-signer`) if the user wants to change it or loses the passphrase.
+
+### Stage 2 — Understand the strategy and the protocol
+
+**Before writing any code, ask and confirm the strategy.** Ask in order, wait for each answer, then show a plain-English summary and get explicit "yes":
+
+1. "What token are you depositing from? (e.g. USDC, ETH)"
+2. "What tokens do you want to buy? List them."
+3. "What is your total budget and cadence? (e.g. $100/week)"
+4. "How do you split that across tokens? (equal, or custom %)"
+5. "Maximum slippage tolerance? (default 1%)"
+6. "Minimum balance to keep liquid in the SMA?"
+
+Summarize, then: "Confirm these parameters before I build the mandate? (yes/no)". Only proceed after explicit confirmation.
+
+Then establish the on-chain bounds:
+1. Identify the target protocol(s), contract(s), and function(s).
+2. Verify the chain hasn't changed since Stage 0.
+3. Set bounds by action type:
+
+| Action | Bounds to establish |
+|---|---|
+| Swap | input token, output token(s), max amount per swap, max slippage |
+| Lend / borrow | asset, max borrow amount, max LTV |
+| Transfer | recipient allowlist, token, max amount |
+| LP provision | pool, max amount per side, allowed price range |
+| Perpetuals | market, max position size, max leverage, long/short |
+
+These are guidance for common cases, not limits. If the action isn't listed, ask what bounds make sense.
+
+**Venue note:** permissions can only bound what the kernel sees on-chain. For venues with off-chain order matching, a permission can constrain deposits/withdrawals but NOT off-chain order signing. Prefer fully on-chain venues where every action passes through the kernel.
+
+**Approvals note:** an ERC-20 `approve` is itself a dispatch and must pass the registered permissions. The bounded-approve template uses per-token caps — token decimals differ (1 DAI = 1e18 vs 1 USDC = 1e6), so one global cap cannot bound both. `client.strategy.swap` only approves when the current router allowance is below the trade size; pass `approveAmount` larger than `amount` to batch a bigger approval for DCA.
+
+### Stage 3 — Author the permission contract
+
+A mandate is one or more permissions. Determine the tier:
+
+**Tier 1** — an example exists in `examples/permissions/` for the exact protocol and chain. Adapt it with the user's parameters. Light verification.
+
+**Tier 2** — an example exists for the same action type on a different protocol. Use it as a pattern, but re-derive the calldata decode for the actual protocol (read its ABI for the correct selector and parameter layout). Full verification.
+
+**Tier 3** — no example exists. Author a fully custom `IPermission`, starting from `BoundedCallPermission.sol` in `mandates/`. Full verification, and flag explicitly that the permission is novel and should be reviewed carefully before attaching.
+
+For any tier: target/selector/value gating comes from `BoundedCallPermission.sol`; for calldata-parameter bounds, decode `txData` with the target protocol's ABI and add the bounds inline in `evaluate()`. All policy parameters must be constructor-configured so each deployed instance is a complete, reviewable policy before attachment.
+
+Sailor does not ship permission contracts. The user authors, reviews, and owns their own. Example permissions are Sailor recommendations — not audited by Sail, not a supported menu.
+
+### Stage 4 — Mandatory verification gate + deploy
+
+**Before any deploy or signature**, decode a real sample call and show, in plain English, exactly what each permission permits and blocks:
+```
+Here's what this permission enforces, proven against sample calls:
+  PASSES: [decoded call within bounds] — because [reason]
+  REVERTS: [call exceeding the cap] — because [reason]
+  REVERTS: [call to a different contract] — because [reason]
+  REVERTS: [call with wrong token/recipient] — because [reason]
+Does this match what you intended? (yes/no)
+```
+
+Only after explicit confirmation, state the boundary before signing:
+> "On-chain (enforced by the kernel, cannot be bypassed): [on-chain bounds].
+> In agent code (changeable without a new signature): cadence, route selection, price quotes.
+> The on-chain bounds are permanent for this permission — changing them means deploying a new contract and re-registering."
+
+Then compile and deploy:
+```bash
+forge build
+sailor mandate deploy --contract <Name> --attach --sma <SMA-address>
+```
+
+**Signing role:** registering a permission requires the **owner** to sign in the browser — this authorizes what the agent may do. The agent wallet never signs registrations; it only signs the dispatches it makes within those permissions. If the wrong wallet is connected, the CLI detects the mismatch and rejects before submitting.
+
+To deploy and attach separately:
+```bash
+sailor mandate deploy --contract <Name>
+sailor mandate attach --address <deployed-address> --sma <SMA-address>
+```
+
+### Stage 5 — Dry run
+
+Preview the agent's first tick against the mandate before spending gas:
+```bash
+sailor run --once
+```
+On selective kernels (all current chains), the runner previews each dispatch via the kernel before execution. Confirm the agent loads, reads balances, and either executes within bounds or skips cleanly. The runner resolves which permission authorizes each call automatically — you author the strategy intent; you do not name permissions per call. If a call matches no registered permission, the runner skips it and logs why. Do not proceed to automation without a confirmed first tick.
+
+### Stage 6 — Automate
+
+Once the mandate is signed, the agent runs autonomously within its bounds — no per-transaction confirmation.
+
+**Local:**
+```bash
+sailor run
+```
+
+**GitHub Actions** — runs on a timer; the workflow is scaffolded at `.github/workflows/agent-tick.yml`:
+1. Push the repo to GitHub
+2. Add `RPC_URL` as a repository secret
+3. Add `SAIL_PASSPHRASE` (the agent wallet passphrase) as a repository secret
+
+The workflow unlocks the agent wallet headlessly on each scheduled run.
+
+Optionally set up notifications (e.g. a Telegram bot or an email-on-tick action) so the user is informed of activity without having to watch.
+
+### Stage 7 — Monitor
+
+The dashboard at the URL printed by `sailor ui start` shows live SMA state, mandate health, agent wallet balance, and the activity log. Key files during operation:
+
+| File | Contents |
+|---|---|
+| `.sail/account.json` | SMA address and chain |
+| `.sail/state/mandates.json` | Deployed permission contracts |
+| `.sail/activity.jsonl` | Every agent decision and transaction |
+| `.sail/.env.local` | RPC URL and passphrase — never commit this file |
+
+## Signing (for custom runners)
+
+If the user writes their own runner instead of using `sailor run`, do NOT hand-roll the EIP-712 dispatch signature — the struct differs by dispatch model and a wrong shape reverts with `InvalidManagerSignature`. Use the SDK helper `buildDispatchSignature` from `@sail.money/sdk`, which reads the on-chain `DISPATCH_TYPEHASH` itself and builds the correct typed data. Never pass the model in by hand.
+
+## Failure-mode catalog
+
+Every dispatch failure is decoded by the SDK — `client.dispatch.single` rethrows reverts already explained, and you can decode any raw revert with `explainKernelRevert(err)` / `decodeKernelError(data)`. Common errors:
+
+| Error | What it means | Fix |
+|---|---|---|
+| `InvalidManagerSignature` | The signed EIP-712 Dispatch didn't recover to the registered manager. | Almost always a stale manager nonce (RPC lag or two dispatches signed against the same nonce) — re-read `managerNonces` and re-sign; `dispatch.single` handles this. Or the wrong Dispatch struct for this kernel — use `capabilities()`. |
+| `PermissionDenied(permission)` | A registered permission's `evaluate()` returned false, reverted, or ran out of gas. | The call genuinely violates that permission's bounds. Run `sailor doctor` to inspect registered permissions. |
+| `NoPermissionsRegistered(account)` | Account has zero permissions; kernel denies by default. | Register at least one permission (owner signs). |
+| `PermissionNotRegistered(permission)` | Named permission isn't registered. | Register it first. |
+| `SessionInactive(account)` | Manager session is revoked. | `session.activate` before dispatching. |
+| `DeadlineExpired(deadline,current)` | Signature deadline is in the past. | Sign with a deadline comfortably ahead of `block.timestamp`. |
+| `SafeExecutionFailed()` | Permission passed, but the target call itself reverted. | Usually slippage too tight, insufficient allowance/balance, or a failing route — not a permission problem. |
+| `ModuleNotEnabled()` | Sail module not enabled on the Safe. | Complete onboarding (enable the module) first. |
+| `ProtocolPaused()` | Governance paused the protocol. | Wait for unpause. |
+| `NotManager(caller,expected)` | Submitter isn't the registered manager. | Submit from the manager key. |
+| `TooManyPermissions(account,limit)` | Per-account permission cap reached. | Revoke an unused permission first. |
+
+When in doubt, the SDK hint string (in `error.kernelError.hint`) names the likely cause and fix.
+
+## SDK quick reference
+
+- `client.capabilities()` — detect dispatch model on-chain.
+- `client.dispatch.single(safe, permission, call, manager, opts?)` — nonce-safe single dispatch (`opts`: `nonce`, `awaitNonce`, `gas`, `deadline`).
+- `client.strategy.swap(safe, {from,to,amount,slippage,swapPermission?,approveAmount?}, manager)` — approve-when-low + LiFi swap.
+- `explainKernelRevert(err)` / `decodeKernelError(data)` — human-readable revert explanation.
+- `getSailDeployment(chainId).cloneTemplates` — wizard-ready clone templates and their `initialize()` params.
+- CLI: `sailor capabilities` (feasibility map), `sailor doctor` (preflight: model, permissions, RPC + gas), `sailor onboard`, `sailor mandate …`, `sailor ui start`.
+
+## What NOT to do
+
+- Do not launch the UI before the user has seen the welcome and said start
+- Do not ask a running agent to confirm individual dispatches within its mandate
+- Do not put an owner key in the terminal — owner signing is browser-only
+- Do not hand-roll dispatch EIP-712 signatures — use `buildDispatchSignature`
+- Do not hardcode the dispatch model or EIP-712 type shape — detect it on-chain
+- Do not present example permissions as audited or as a supported menu
+- Do not commit `SAIL_PASSPHRASE` or private keys

package/templates/dca-rebalancer/AGENT_PLAYBOOK.md

@@ -0,0 +1,110 @@
+# Sail agent playbook
+
+Operational guide for an agent (or operator) running a Sail Protocol SMA via the
+Sailor SDK/CLI. Read [docs/PERMISSION_MODEL.md](docs/PERMISSION_MODEL.md) first — the
+conjunctive vs selective distinction underpins everything below.
+
+Golden rule: **always ask the user before any action that costs gas or moves funds.**
+
+## Step 0 — detect capabilities (always first)
+
+Before signing or dispatching anything, learn what kernel you're on:
+
+```ts
+const caps = await client.capabilities();   // reads DISPATCH_TYPEHASH on-chain
+```
+
+or, from the CLI, run the full preflight:
+
+```bash
+sailor doctor            # kernel model + permission health, read-only, no gas
+sailor doctor --json     # machine-readable
+```
+
+`sailor doctor` detects the dispatch model, lists registered permissions, and — on a
+conjunctive kernel — flags any permission that does **not** pass through unrelated
+calls (which would brick every dispatch). Fix those before doing anything else.
+
+## Decision tree
+
+```
+Want to act on the SMA?
+│
+├─ Is the Sail module enabled + account registered?      → no:  finish onboarding (sailor onboard)
+│
+├─ sailor doctor green?                                   → no:  revoke/replace bricking permissions first
+│
+├─ Need a NEW kind of action the permissions don't allow? → yes: register a permission (owner signs)
+│     • Conjunctive: the permission MUST pass through other calls. Prefer ONE
+│       permission per domain that allows everything you need (e.g. a single
+│       approve permission whitelisting all tokens you'll approve).
+│     • Use a clone template when one exists (no Solidity):
+│       getSailDeployment(chainId).cloneTemplates  → deployAndAttach
+│
+├─ One-off swap?                                          → client.strategy.swap({from,to,amount,slippage})
+│
+└─ Recurring/automated (DCA, rebalance)?                  → loop strategy.swap on a schedule;
+                                                            approve a larger batch once so most
+                                                            iterations are a single swap dispatch.
+```
+
+### Approvals
+
+- An ERC-20 `approve` is itself a dispatch and must pass the registered permissions.
+  On a conjunctive kernel that means an **approve permission that allows the token +
+  spender + amount**, AND every other permission passing the approve through.
+- The bounded-approve template uses **per-token caps** (token value/decimals differ:
+  1 DAI = 1e18 vs 1 USDC = 1e6). One global cap can't bound both.
+- `client.strategy.swap` only approves when the current router allowance is below the
+  trade size, so steady-state swaps are a single dispatch. Pass `approveAmount` larger
+  than `amount` to batch a bigger approval for DCA.
+
+### Swap mandates (LiFi)
+
+- The swap permission restricts: target = LiFi diamond, selector allowlisted, embedded
+  receiver == the account, `minAmount` ≤ cap. Verify the route's selector is
+  allowlisted (Base routes commonly use `0x5fd9ae2e`); add others via the permission
+  signer if needed.
+- Default slippage is 3% — LiFi's own 0.5% reverts (`CumulativeSlippageTooHigh`) on
+  small trades.
+
+### Automated jobs
+
+- Sequential dispatches: `client.dispatch.single` auto-tracks the manager nonce per
+  `(kernel, account)` and waits for the prior bump to propagate before signing the
+  next — no manual nonce handling, even on a load-balanced RPC.
+- Use a dedicated RPC endpoint (not a public replica) to minimize read-after-write lag.
+- Pin post-tx reads to the receipt's block; a lagging node can otherwise make a
+  confirmed action look failed.
+
+## Failure-mode catalog
+
+Every dispatch failure is decoded by the SDK — `client.dispatch.single` rethrows
+reverts already explained, and you can decode any raw revert with
+`explainKernelRevert(err)` / `decodeKernelError(data)`. Common ones:
+
+| Error (selector) | What it means | Fix |
+|---|---|---|
+| `InvalidManagerSignature` (`0xeb6942f1`) | The signed EIP-712 Dispatch didn't recover to the registered manager. | Almost always a **stale manager nonce** (RPC lag or two dispatches signed against the same nonce) — re-read `managerNonces` and re-sign; `dispatch.single` now handles this. Or the **wrong Dispatch struct** for this kernel — use `capabilities()`. |
+| `PermissionDenied(permission)` | A registered permission's `evaluate()` returned false / reverted / ran out of gas. | On a **conjunctive** kernel, a permission that doesn't pass through unrelated calls bricks everything — run `sailor doctor` and revoke/replace it. Otherwise the call genuinely violates that permission's bounds. |
+| `NoPermissionsRegistered(account)` | Account has zero permissions; kernel denies by default. | Register at least one permission (owner signs). |
+| `PermissionNotRegistered(permission)` | Named permission isn't registered. | Register it; or on a conjunctive kernel drop the permission arg (the SDK does). |
+| `SessionInactive(account)` | Manager session is revoked. | `session.activate` before dispatching. |
+| `DeadlineExpired(deadline,current)` | Signature deadline is in the past. | Sign with a deadline comfortably ahead of `block.timestamp`. |
+| `SafeExecutionFailed()` | Permission passed, but the target call itself reverted. | Usually slippage too tight, insufficient allowance/balance, or a failing route — not a permission problem. |
+| `ModuleNotEnabled()` | Sail module not enabled on the Safe. | Complete onboarding (enable the module) first. |
+| `ProtocolPaused()` | Governance paused the protocol. | Wait for unpause. |
+| `NotManager(caller,expected)` | Submitter isn't the registered manager. | Submit from the manager key. |
+| `TooManyPermissions(account,limit)` | Per-account permission cap reached. | Revoke an unused permission first. |
+
+When in doubt, the SDK hint string (in `error.kernelError.hint`) names the likely
+cause and fix.
+
+## Quick reference (SDK)
+
+- `client.capabilities()` — detect dispatch model.
+- `client.dispatch.single(safe, permission, call, manager, opts?)` — nonce-safe single dispatch (`opts`: `nonce`, `awaitNonce`, `gas`, `deadline`).
+- `client.strategy.swap(safe, {from,to,amount,slippage,swapPermission?,approveAmount?}, manager)` — approve-when-low + LiFi swap.
+- `explainKernelRevert(err)` / `decodeKernelError(data)` — human-readable revert.
+- `getSailDeployment(chainId).cloneTemplates` — wizard-ready clone templates + their `initialize()` params.
+- CLI: `sailor capabilities` (feasibility map), `sailor doctor` (preflight: model, permissions, RPC + gas), `sailor onboard`, `sailor mandate …`, `sailor station start`.

package/templates/dca-rebalancer/CLAUDE.md

@@ -0,0 +1,2 @@
+# Sailor Project
+See [AGENTS.md](./AGENTS.md) for all project guidance. This file is a pointer; AGENTS.md is canonical.

package/templates/dca-rebalancer/README.md

@@ -0,0 +1,16 @@
+# DCA Rebalancer — Sail Protocol Agent
+
+This folder is your Sail agent. It DCA-rebalances a token basket on a schedule.
+
+Open this folder in **Claude Code**, **Cursor**, or **Codex** (or any LLM-powered IDE) and say:
+
+> start
+
+Your AI coding assistant will walk you through every step — from network and wallet setup to your
+first on-chain tick. See `AGENTS.md` for the details; no manual config needed.
+
+## Project layout
+
+- `.sail/config.json` is the local project manifest.
+- `.sail/keys/` stores the encrypted agent wallet and mandate signer keys when local signing is used.
+- `.sail/state/` is for persistent agent state, audit logs, and tx history.

package/templates/dca-rebalancer/_gitignore

@@ -0,0 +1,13 @@
+# Sailor project — never commit these
+.sail/.env.local
+.sail/keys/
+.sail/state/
+.sail/runtime/
+
+# Dependencies
+node_modules/
+
+# Foundry build outputs
+out/
+cache/
+broadcast/

package/templates/dca-rebalancer/docs/PERMISSION_MODEL.md

@@ -0,0 +1,93 @@
+# Sail permission model: conjunctive vs selective
+
+The deployed SailKernel ships in **two incompatible dispatch models**. Which one a
+chain runs changes how dispatches are signed *and* how permissions must be written.
+Get this wrong and every dispatch reverts with an opaque selector. This is the single
+most important thing to understand before operating an SMA.
+
+## TL;DR
+
+| | **Conjunctive** (older) | **Selective** (newer) |
+|---|---|---|
+| Chains today (bundled kernels) | None — all bundled kernels moved to selective | Base (8453), Base Sepolia (84532), Arbitrum (42161), Unichain (130) |
+| `dispatch(...)` | `(account, target, value, data, sig, deadline)` — **no `permission`** | `(account, permission, target, value, data, sig, deadline)` |
+| Which permissions are checked | **ALL** registered permissions; **all must return true** | only the **one** permission named in the call |
+| EIP-712 `Dispatch` struct | no `permission` field | includes `permission` |
+| Batch (`dispatchBatch`/`previewBatch`) | **not available** | available |
+| **Permission design rule** | **MUST pass through calls outside its domain** | may return false freely |
+
+Don't guess from a version string — **detect it on-chain** (see below).
+
+## The conjunctive pass-through rule (the big footgun)
+
+On a conjunctive kernel the kernel calls `evaluate(txData, ctx)` on **every**
+registered permission and ANDs the results. A single `false` blocks the whole
+dispatch (`PermissionDenied`).
+
+So a permission that only cares about, say, approvals **must still return `true` for
+every call it doesn't govern**:
+
+```solidity
+function evaluate(bytes calldata txData, Context calldata ctx) external view returns (bool) {
+    // Pass through calls outside this permission's domain (conjunctive model).
+    if (ctx.selector != APPROVE) return true;   // <-- without this line, this
+                                                 //     permission bricks swaps,
+                                                 //     transfers, everything.
+    // ...domain-specific checks for approve...
+}
+```
+
+A permission that returns `false` (or reverts, or runs out of gas — both treated as
+`false`) on unrelated calls **bricks the entire account**: no dispatch of any kind
+can pass. We hit exactly this during bring-up with permissions that "blocked each
+other." The fix was to redeploy every permission with pass-through semantics.
+
+Corollary: on a conjunctive kernel you **cannot** have two permissions that each
+enforce a different token's approve — each would reject the other's token. To support
+approving both DAI and USDC you need **one** approve permission that allows both, not
+two narrow ones.
+
+Selective kernels don't have this problem: each dispatch names one permission and
+only that one is consulted.
+
+## Detect the model on-chain
+
+The SDK reads each kernel's public `DISPATCH_TYPEHASH` constant and matches it
+against the canonical hashes for each model. Never assume.
+
+```ts
+const caps = await client.capabilities();
+// caps.dispatchModel: "conjunctive" | "selective"
+// caps.dispatchTypehash, caps.source ("onchain-typehash" | "static-hint")
+```
+
+Verified typehashes:
+
+- conjunctive `DISPATCH_TYPEHASH` = `0x7510c80e…`
+  `Dispatch(address account,address target,uint256 value,bytes32 dataHash,uint256 nonce,uint256 deadline)`
+- selective `DISPATCH_TYPEHASH` =
+  `Dispatch(address account,address permission,address target,uint256 value,bytes32 dataHash,uint256 nonce,uint256 deadline)`
+
+`client.dispatch.single(...)` already signs the correct struct and uses the correct
+ABI for the detected model — you don't sign by hand. `client.dispatch.batch` /
+`client.dispatch.preview` throw a clear error on conjunctive kernels (no `dispatchBatch`).
+
+## Roles (unchanged across models)
+
+| Role | Authority |
+|------|-----------|
+| **Owner** | Holds the Safe; custody anchor. |
+| **Permission Signer** | Authorizes which `IPermission` contracts apply (EIP-712 `RegisterPermissions` / `RevokePermissions`). Signed in the browser signing station — the agent never holds this key. |
+| **Manager** | Executes dispatches within the registered permissions (ECDSA / ERC-1271). The agent's hot key. |
+
+## Preflight before spending gas
+
+Run `sailor doctor` (read-only, no gas, no keys):
+
+- detects the dispatch model,
+- lists registered permissions,
+- on a conjunctive kernel, **probes each permission for pass-through** and flags any
+  that would brick dispatch.
+
+See [AGENT_PLAYBOOK.md](../AGENT_PLAYBOOK.md) for the operational decision tree and the
+revert failure-mode catalog.

package/templates/dca-rebalancer/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "dca-rebalancer",
+  "version": "0.1.0",
+  "description": "Dollar-cost-average rebalancer — starter Sail Protocol agent",
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@sail/sdk": "workspace:*",
+    "viem": "^2.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  }
+}