@dev.sail.money/sailor 1.0.0-42 → 1.1.0-44

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

@@ -0,0 +1,73 @@
+---
+name: sail-onboarding
+description: Walks the agent through setting up a new Sailor project or resuming a partially set-up one — SMA deployment, agent wallet creation, address prediction, and multi-chain deployment. Use when the project has no SMA yet, when .sail/account.json is missing or incomplete, when the user says "start" or "continue", or when deploying the SMA to an additional chain.
+---
+
+# Sail onboarding
+
+## Running the CLI
+
+The project does not install `sailor` as a dependency, so invoke it with **`npx sailor <command>`** unless it is installed globally (`npm i -g @sail.money/sailor`, then `sailor` works bare). Every `sailor …` command in these skills assumes one of those. Confirm the toolchain up front and pin a recent version — `npx sailor@latest --version` — because an old cached `npx` build can be missing newer commands (e.g. `mandate simulate`); if a documented command reports "unknown command", you are on a stale version, not hitting a missing feature.
+
+Stage machine keyed off `.sail/`. Read the state, enter at the right stage, never re-run completed stages.
+
+## Determine where the user is
+
+| `.sail/` state | Stage |
+|---|---|
+| `config.json` has `chainId: null` | Stage 0 — chain not chosen; ask which chain, write it to `config.json` |
+| No `account.json` | Stage 1 — SMA not deployed |
+| `account.json` exists, `state/mandates.json` empty or absent | SMA live, no permissions — hand off to **sail-mandates** |
+| `account.json` + tracked mandates | Fully onboarded — hand off to **sail-transactions** / running |
+
+Supported chains: Ethereum (1), Base (8453), Arbitrum (42161), Unichain (130), Base Sepolia (84532), Eth Sepolia (11155111). `sailor chains --json` lists them with kernel addresses.
+
+## Stage 1 — Deploy the SMA and create the agent wallet
+
+In the browser. Run `sailor ui start`, open the printed URL, connect the owner wallet, choose the network, deploy the SMA, then create the agent wallet — a separate signing key the agent uses to submit transactions. **Both wallets need gas, and the split is not what it looks like:** the owner *signs* (SMA deployment, mandate authorization) but the **agent wallet submits and pays for every on-chain transaction** — including `mandate deploy` and `mandate attach` during setup, not just dispatches once running. Fund the agent wallet before Stage 3 or attach fails with `gas required exceeds allowance`. The owner wallet needs gas only for transactions it submits directly in the browser (the SMA deployment). The owner key never leaves the browser.
+
+Headless alternative (the agent drives, the owner only signs in the browser):
+
+```bash
+sailor keys generate                 # create the agent wallet (interactive: role + passphrase)
+sailor station start --json &        # signing daemon — BLOCKS; run in background
+sailor owner connect --json          # BLOCKS up to 300s waiting for a wallet to connect in the browser
+sailor scan --json                   # discover the owner's Safes and state
+sailor onboard --new-sma --json      # deploy SMA — BLOCKS waiting for the owner's browser signature
+```
+
+`onboard --new-sma` pushes a `create-sma` signing request to the browser, waits for the owner to approve (default timeout 10 minutes), then persists the SMA to `.sail/account.json`. Tell the user: "approve the request in the signing station in your browser."
+
+## Deterministic address (salt)
+
+Every SMA deployment uses a CREATE2 salt (default `0`). The kernel binds the salt to the owner, the agent (manager) wallet, and the fee policy — so **create the agent wallet first, then predict**:
+
+```bash
+sailor account predict --owner <owner> --manager <agent-wallet> --json
+```
+
+The salt is saved to `.sail/account.json` (`saltNonce`) automatically on deploy. All supported chains share the same protocol addresses via CREATE2, so the same owner, manager, and salt produce the same SMA address on every chain. `predict` reads no keys and spends no gas. Use `--salt <n>` for a non-default salt, `--chain <id>` for one chain only.
+
+If `predict` errors with "depends on the agent (manager) wallet", the agent wallet does not exist yet — generate it first.
+
+## Multi-chain deployment
+
+Once the SMA is live on one chain, deploy it at the same address on another supported chain:
+
+```bash
+sailor account predict --json                  # confirm the address matches first
+sailor account deploy-chain --chain 42161 --json   # BLOCKS waiting for the owner's browser signature
+```
+
+The owner approves in the browser (switch the wallet to the target chain before signing); no new salt or agent wallet is needed. The command is idempotent — if the SMA already has code at the predicted address on the target chain it records the chain and exits cleanly. Deployed chains accumulate in `account.json` `deployedChains`.
+
+If `deploy-chain` refuses with an address mismatch, the SMA was deployed against the old per-chain contracts (pre-CREATE2) and cannot be reproduced cross-chain — the fix it prints is to deploy a fresh SMA with `sailor onboard --new-sma`.
+
+## Gas requirements
+
+- Owner wallet: SMA deployment, mandate signing (EIP-712), any additional-chain deployment.
+- Agent wallet: `mandate deploy`, `mandate attach`, `mandate revoke`, and every dispatch submission once the agent runs, plus permission registration fees on fee-charging chains.
+
+`sailor doctor` — read-only preflight: kernel dispatch model, permission health, RPC reachability, gas balances in both wallets. Do not proceed to Stage 3 with a failing doctor.
+
+During setup, always ask before anything that costs gas.

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

@@ -0,0 +1,30 @@
+---
+name: sail-project-info
+description: Read-only commands and state files that answer questions about the project, account, mandate, chains, keys, or environment. Use when the user asks "what's the state of…", "is X set up", "which chains…", "what permissions are registered", or before any operation that needs current state.
+---
+
+# Sail project info
+
+Every command here is read-only and supports `--json` for machine reading. Prefer `--json`; parse, don't scrape. None of them block on the browser.
+
+| Command | Reports | Backed by |
+|---|---|---|
+| `sailor status` | One-screen setup progress: keys present, account, signed mandate, session, agent run state | Local: `.sail/account.json`, `mandate.json`, `session.json`, `keys/`, agent pid file |
+| `sailor doctor --json` | Preflight: kernel dispatch model, permission health (per-permission evaluate probes), RPC reachability, gas balances of owner + agent wallets | On-chain reads via the configured RPC; `--account <address>` overrides the SMA |
+| `sailor capabilities --json` | Feasibility map: resolved chain, kernel model, available mandate templates, strategy primitives | `deployments.ts` registry + on-chain typehash detection |
+| `sailor chains --json` | Supported chains and their SailKernel addresses | Static registry; add `--verify` to `eth_getCode` each kernel (one RPC call per configured chain) |
+| `sailor scan --json` | Owner's Safes, which are Sail SMAs, their managers/permissions/sessions, local keys — persisted to `.sail/state/context.json` | Safe Transaction Service + kernel reads; `--owner <address>` overrides the saved owner |
+| `sailor owner show --json` | The saved project owner address | `.sail/state/owner.json` |
+| `sailor keys show` | Address of each stored key (decrypts to derive the address; prompts for passphrase unless `SAIL_PASSPHRASE` is set) | `.sail/keys/*.json` |
+| `sailor mandate list` | Permission contracts deployed from this project, with attachment history | `.sail/state/mandates.json` |
+| `sailor mandate templates --json` | How to author a permission + any community-deployed standalone template addresses on this chain (unaudited, informational) | `deployments.ts` `standaloneTemplates` |
+
+## Which source answers what
+
+- "Is the SMA deployed?" — `account.json` exists and has `safe`; `doctor` confirms on-chain.
+- "What can the agent do right now?" — on-chain `getPermissions()` is the truth; `mandate sign` reconciles against it. `state/mandates.json` is an append-only historical record — a permission revoked on-chain still appears there.
+- "Is the RPC working / is there gas?" — `sailor doctor --json`.
+- "Same address on another chain?" — `account.json` `deployedChains`, verified by `sailor account predict`.
+- "Is anything running?" — `.sail/runtime/ui.json` (dashboard), `.sail/runtime/server.json` (signing station), agent pid via `sailor status`.
+
+Run `sailor doctor` before any operation that spends gas — it is the cheapest way to catch a dead RPC, an unfunded wallet, or a kernel mismatch first.

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

@@ -0,0 +1,43 @@
+---
+name: sail-servers
+description: Start, stop, and health-check the two local servers — the Sailor dashboard and the signing station. Use when launching the UI, when a signing request needs a browser, when a port or pid question comes up, or when a command appears stuck waiting for a signature.
+---
+
+# Sail servers
+
+Two distinct local servers. Both are per-project, both write state under `.sail/runtime/`, and both start idempotently (starting twice reports "already running" and exits 0).
+
+## Dashboard — `sailor ui`
+
+```bash
+sailor ui start    # spawns a detached Express server, prints the URL, returns immediately
+sailor ui status   # ● running  http://localhost:<port>  (pid N)
+sailor ui stop     # SIGTERM via the pid file
+```
+
+- Port: deterministic per project — `3333 + (hash(projectPath) % 667)`, i.e. somewhere in 3333–3999, bumped to the next free port if taken. **Do not assume 3333** — always use the URL the command prints or read `.sail/runtime/ui.json` (`{ pid, port, startedAt }`).
+- The server serves the pre-built React app (`SERVE_DIST=1`) and a local `/api` that reads `.sail/` state (`SAIL_DIR` env).
+- `ui start` does not block — no `&` needed.
+
+## Signing station — `sailor station`
+
+```bash
+sailor station start --json   # BLOCKS — run in the background
+sailor station status --json  # running / stopped, url, pid
+sailor station stop --json    # SIGTERM, verified against the recorded URL first
+```
+
+- Port: defaults to **3141**, bumped to the next free port if taken. The actual URL is in `.sail/runtime/server.json` (`{ url, wsUrl, port, pid, startedAt, requestSecret }`).
+- Health/discovery endpoint: `GET http://localhost:<port>/config` returns `{ url, wsUrl, port, pid, pendingCount }` — `pendingCount` is the number of signing requests waiting for the owner. All other endpoints require a per-startup secret; do not poll them.
+- `station start` **blocks** (the listening socket keeps the process alive) — run it in the background. It is idempotent: if a reachable daemon exists it reports already-running and exits 0.
+- The URL to give the user is the **dashboard** station route printed by the command: `http://localhost:<ui-port>/#/station`.
+
+## How they relate
+
+Signing-flow commands (`mandate deploy/attach/deploy-clone/revoke`, `onboard`, `account deploy-chain`, `account rotate-signer`, `owner connect`) push requests to a running station daemon if one exists, otherwise they spin up an ephemeral in-process signing server for the duration of the command. Starting a persistent station first means the owner connects their wallet once and approves a whole sequence of requests in the same browser tab — do this before any multi-step signing flow.
+
+## Troubleshooting
+
+- Command stuck "waiting"? It is blocked on a browser signature — check `GET /config` `pendingCount`, and tell the user to open the station URL and approve. Signing requests time out after 10 minutes.
+- Stale pid file (process died): `ui status` / `station stop` clean it up automatically.
+- `sailor ui start` errors about a missing server bundle or UI dist: the package build is incomplete — re-run the sailor build.

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

@@ -0,0 +1,63 @@
+---
+name: sail-transactions
+description: How dispatches and EVM transactions work in a Sailor project — the selective dispatch model, signing, batching, permission resolution, running the agent, and which CLI commands block on a browser signature. Use when building or debugging dispatches, writing agent tick code, running the agent, or reasoning about why a transaction was denied or reverted.
+---
+
+# Sail transactions
+
+## The dispatch model
+
+The deployed kernels run the **selective** model: every dispatch names one registered permission, and the kernel calls that permission's `evaluate()` (or `evaluateBatch()` for batches) on-chain before executing. A permission returning false, reverting, or exceeding its gas cap is a denial — fail-closed.
+
+Never hardcode the model. `detectKernelCapabilities` (SDK) reads the on-chain `DISPATCH_TYPEHASH()` and is the only reliable source; the static label in `deployments.ts` is an offline fallback.
+
+## Signing
+
+Never hand-roll the EIP-712 dispatch struct. Use `buildDispatchSignature` from the SDK — it reads the on-chain typehash and builds the correct typed data for the detected model.
+
+## Writing agent code
+
+The runner (`sailor run`) calls `agent.tick(ctx)` from `src/agent.ts` and submits each returned `Dispatch`:
+
+- A dispatch is `{ calls: [{ target, value, data }, …] }`. One call = single dispatch; multiple calls = batch dispatch (single on-chain tx, all-or-nothing).
+- You do not name permissions: the runner probes each registered permission in registration order (off-chain `evaluate()` / `previewBatch` via `eth_call`) and routes to the first that accepts. Set `dispatch.permission` only as an explicit override to skip the probe.
+- **Approve + action — two non-mixable models** (details: `../sail-mandates/references/approvals.md`):
+  - **Per-call (default):** two separate single-call dispatches, each gated by its own `IPermission`. Emit the approve only when on-chain allowance is insufficient (the `examples/dca/` pattern).
+  - **Atomic batch (advanced):** one `Dispatch` with `calls: [approveCall, actionCall]` authorized by a single `IBatchPermission`. A normal `IPermission` cannot authorize a batch (`PermissionNotBatchAware`). Do not mix the models.
+- `ctx` provides `read.balance/allowance/decimals`, `publicClient` (arbitrary reads), `log()`, and a persistent `data` slot.
+- Return `[]` to skip a tick — no gas spent.
+
+## Running
+
+```bash
+sailor run --once          # single tick — confirm it works before automating
+sailor run                 # continuous; interval SAILOR_INTERVAL seconds (default 60)
+sailor run --chain <id>    # override CHAIN_ID for this run
+```
+
+`run` needs `.sail/account.json`, `.sail/mandate.json`, a manager key, `CHAIN_ID` and an RPC URL (`.sail/.env.local`). Set `SAIL_PASSPHRASE` in `.env.local` to unlock the agent wallet non-interactively. Neither form blocks on a browser — the signed mandate is the authorization.
+
+## Where results land
+
+Everything appends to `.sail/activity.jsonl` (one JSON per line): `tick_start`/`tick_end`, `dispatch_approved`, `dispatch_executed` (with `txHash`), `dispatch_reverted` (with `txHash`, `gasUsed`), `dispatch_denied` (with `reason`, e.g. `no_permission_match` plus the rejected selector), `error`, and owner-side `owner_signed`/`owner_rejected` events. On stderr, reverts surface as `reverted: <txHash>  (gas used: N)`; denials as `skipped: no registered permission authorizes call to <target> (selector 0x…)`. A failed dispatch never stops the loop.
+
+## Commands that BLOCK on a browser signature
+
+These open a signing channel, push a request, and wait (default timeout 10 minutes) for the owner to approve in the browser. When one is pending, tell the user: "approve the request in the signing station in your browser" and give them the station URL the command printed.
+
+| Command | What the owner signs |
+|---|---|
+| `sailor onboard --new-sma` | `create-sma` transaction (owner pays gas) |
+| `sailor account deploy-chain --chain <id>` | `create-sma` transaction on the target chain |
+| `sailor account rotate-signer` | Delegate rotation + mandate re-approvals |
+| `sailor mandate deploy` | `deploy-mandate` contract-creation transaction (owner pays gas) |
+| `sailor mandate attach` | `RegisterPermission` EIP-712 (off-chain signature; agent submits and pays gas) |
+| `sailor mandate deploy-clone` | `RegisterPermission` EIP-712 for the predicted clone address |
+| `sailor mandate revoke` | `RevokePermissions` EIP-712 (agent submits and pays gas) |
+| `sailor owner connect` | Nothing — blocks up to 300s waiting for a wallet to connect |
+
+All take `--json` for machine-readable output; in `--json` mode the blocking commands emit a `waiting_for_signature` status with the URL before blocking.
+
+## Session control
+
+`sailor session pause` instantly revokes dispatch rights without touching custody; `sailor session resume` restores them.

package/templates/default/AGENTS.md

@@ -1,3 +1,7 @@
+This guide is for agents operating a scaffolded Sailor project. (Contributors to the Sailor codebase: see AGENTS.md at the monorepo root.)
+
+---
+
 Sail Protocol is infrastructure for onchain Separately Managed Accounts run by AI agents. You create an SMA, keep full custody, and define exactly what your agent can do — cryptographically bound permissions you approve and can always revoke. The agent executes within those bounds on every transaction. It cannot exceed them.
 
 I'm Sailor, the operator that sets this up. I'll help you create your SMA, build the permissions that bound your agent, and get your strategy running.
@@ -32,140 +36,47 @@ During **setup**, always ask before anything that costs gas. Once the **mandate
 
 When the user says start (or any first message), present the welcome above in full — definition, stage list, handoff line — before doing anything else. Do not launch the UI yet. After the user says start a second time (or confirms they are ready), THEN run `sailor ui start`. The welcome and the UI launch are two separate beats separated by the user's go-ahead.
 
-Determine the user's progress by reading `.sail/` — do not ask; read it.
-
 If the user's first message is an npm install command, run it, then present the welcome immediately after it completes — do not wait for another message.
 
-## Stage 1 — Deploy your SMA and create your agent wallet
-
-In the browser. Run `sailor ui start`, open the printed URL, connect your owner wallet, choose your network, and deploy your SMA. Then create your agent wallet — a separate signing key I use to submit transactions on your behalf. You need gas in both: the owner wallet to deploy and sign the mandate; the agent wallet to submit transactions once the agent is running. The owner key never leaves the browser.
-
-**Deterministic address (salt):** every SMA deployment uses a CREATE2 salt. The CLI defaults to salt `0`, giving you a predictable address you can verify before spending gas: `sailor account predict --owner <your-wallet> --manager <agent-wallet>`. The kernel binds the salt to your owner wallet, agent (manager) wallet, and fee policy — create your agent wallet first, then predict. The salt is saved in `.sail/account.json` automatically. All supported chains (Ethereum, Base, Arbitrum, Unichain, plus testnets) share the same protocol addresses via CREATE2, so the same owner, manager, and salt produce the **same SMA address on every chain**.
-
-**Multi-chain deployment:** once your SMA is live on one chain, deploy it at the same address on any other supported chain with `sailor account deploy-chain --chain <id>` (e.g. `--chain 42161` for Arbitrum). The owner approves the deployment in the browser; no new salt or agent wallet needed. Run `sailor account predict` first to confirm the address matches.
-
-## Stage 2 — Define your strategy
-
-Tell me what you want your agent to do. I'll ask the right questions, establish the on-chain bounds with you (tokens, amounts, slippage, venues), and set up your RPC endpoint once you've chosen your chain. Blank slate — you define the strategy.
-
-For a worked end-to-end example (DCA / Uniswap V3 / Base), consult `examples/dca/` — reference only; not your strategy.
-
-## Stage 3 — Build, test, and sign your mandate
-
-I'll write the permission contracts that bound your agent, prove in plain English what each one permits and blocks against sample calls, deploy them, and walk you through signing to authorize. Author, verify, sign — one step.
-
-Permission contracts live in `mandates/`. The user authors, reviews, and owns them. For examples by protocol and chain, see `examples/permissions/`.
-
-**Prerequisite — Foundry:** `forge build` requires the Foundry toolchain. If `forge` is not found, install it:
-```bash
-curl -L https://foundry.paradigm.xyz | bash   # then restart shell
-foundryup
-```
-
-**Approve coverage — mandatory:** ERC-20 `approve()` calls are NOT covered by supply or deposit permission contracts. If your strategy approves a token before supplying, you MUST deploy a separate bounded-approve permission that covers that specific `(token, spender, maxAmount)` combination, and authorize it alongside the supply permission. An agent that calls `approve()` without a matching permission will be rejected by the kernel.
-
-**Batching:** if a strategy tick needs to approve before supplying, build both calls into a single dispatch array — `[approveCall, supplyCall]` — not two separate ticks. Splitting them wastes a tick and the approval sits exposed until the next run.
-
-```bash
-forge build
-sailor mandate deploy --contract <Name> --sma <SMA>   # deploy only — do NOT --attach yet
-```
-
-**Constructor args:** quoting rules differ by shell.
+## Project state — read `.sail/`, never ask
 
-Bash / Git Bash:
-```bash
-sailor mandate deploy --contract <Name> --args '["0xToken","1000000"]' --sma <SMA>
-```
-
-PowerShell — use escaped inner quotes inside single quotes:
-```powershell
-sailor mandate deploy --contract <Name> --args '[\"0xToken\",\"1000000\"]' --sma <SMA>
-```
-
-Any shell — `--args-file` avoids quoting entirely:
-```json
-["0xToken", "1000000"]
-```
-```bash
-sailor mandate deploy --contract <Name> --args-file args.json --sma <SMA>
-```
-
-Before AUTHORIZING (attaching) the permission, BACK the plain-English claims with an actual on-chain probe. `evaluate()` lives on the deployed contract, so deploy first, then — before the irreversible authorization — generate sample calls from the user's stated strategy (ones the permission MUST accept and ones it MUST reject) and run them through `sailor mandate simulate`. This is an off-chain `eth_call` (no gas, no signing) that reports what the permission's `evaluate()` returns for each call, and flags any target with no contract code (a wrong or wrong-chain address):
-
-```bash
-# one call inline, or a batch via JSON
-sailor mandate simulate --address <PermissionOrName> --sma <SMA> \
-  --target <addr> --calldata <hex> --expect pass
-sailor mandate simulate --address <PermissionOrName> --sma <SMA> --calls calls.json
-```
-
-`calls.json` is an array of `{ target, calldata, value?, expect: "pass"|"fail", label }`. A mismatch between `expect` and the actual result exits non-zero — do not authorize until every sample matches. Simulate proves what the permission DOES; it does not guarantee it is correct.
-
-```bash
-sailor mandate attach --address <PermissionOrName> --sma <SMA>   # authorize, once simulate is clean
-```
-
-Registration requires the owner to sign in the browser. If the wrong wallet is connected, the CLI rejects it.
-
-## Stage 4 — Run
-
-Your agent starts executing within its mandate — locally on a schedule or via GitHub Actions. No per-transaction confirmation. The mandate is the authorization.
-
-```bash
-sailor run           # local, continuous
-sailor run --once    # single tick — confirm it works before automating
-```
-
-For GitHub Actions:
-
-1. Run `sailor keys export-ci` — copies your encrypted agent wallet to `ci-keystore.json` in the project root and adds it to `.gitignore` as an allowed file. The keystore is geth v3 encrypted; the raw private key is never exposed.
-2. Commit the required files. CI needs these non-secret files to be 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` (used in the workflow). `.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 two secrets in GitHub (Settings → Secrets → Actions):
-   - `SAIL_PASSPHRASE` — the passphrase that encrypts your agent wallet
-   - `RPC_URL` — your RPC endpoint
-4. Install the `gh` CLI — required to manage the workflow from the terminal (trigger runs, check logs, add secrets without opening the browser):
-   - macOS: `brew install gh`
-   - Windows: `winget install --id GitHub.cli` or `scoop install gh`
-   - Linux: see https://github.com/cli/cli/blob/trunk/docs/install_linux.md
-   Then authenticate with the `workflow` scope:
-   ```bash
-   gh auth login --scopes workflow
-   ```
-   The `workflow` scope is required — without it, `gh` cannot trigger or inspect Actions runs. Verify with:
-   ```bash
-   gh auth status          # confirm workflow scope is listed
-   gh workflow run agent-tick.yml   # manual trigger
-   gh run list --workflow agent-tick.yml   # check run history
-   ```
-
-The scaffolded workflow at `.github/workflows/agent-tick.yml` picks up `ci-keystore.json`, unlocks it with `SAIL_PASSPHRASE`, and runs on the configured schedule. No private key ever appears in the workflow or in secrets.
-
-## Stage 5 — Extend
-
-I can set up notifications (Telegram, email, or other) for runs and transactions, and build you a custom dashboard tailored to your strategy — a price chart and portfolio view for a trading agent, health-factor and yield for a lending agent.
-
-These are things the coding assistant builds on request — not Sailor features. Raise them once the agent is live; build on request.
-
-## Signing (for custom runners)
-
-Use `buildDispatchSignature` from `@sail.money/sdk` — it reads the on-chain `DISPATCH_TYPEHASH` and builds the correct typed data. Never hand-roll the EIP-712 struct or hardcode the dispatch model.
+Determine the user's progress by reading `.sail/` — do not ask; read it.
 
-## What NOT to do
+| File | What it tells you |
+|---|---|
+| `config.json` | Project manifest: name, `chainId` (null until the user picks a chain), contract addresses |
+| `account.json` | Active SMA: safe, owner, manager (agent wallet), chainId, saltNonce, deployedChains |
+| `mandate.json` | The signed mandate the runner executes against (absent = not signed yet) |
+| `keys/` | Encrypted geth-v3 keystores (agent wallet, mandate signer) — never read or print contents |
+| `state/mandates.json` | Append-only record of every permission deployed/attached from this project |
+| `runtime/` | Live process state: `ui.json` (dashboard pid/port), `server.json` (signing station url/pid) |
+| `activity.jsonl` | Unified activity log — agent dispatches and owner signing decisions, one JSON per line |
+| `.env.local` | RPC_URL / CHAIN_ID / per-chain RPC vars / SAIL_PASSPHRASE — never commit or print |
+
+## Skills
+
+Detailed procedures live in skills. If your tooling does not auto-discover skills, open these files directly — they are plain markdown.
+
+| Skill | Load when | Path |
+|---|---|---|
+| sail-onboarding | New project setup, or resuming a partially set-up project | `.agents/skills/sail-onboarding/SKILL.md` |
+| sail-project-info | Any question about project, account, mandate, chain, or environment state | `.agents/skills/sail-project-info/SKILL.md` |
+| sail-servers | Starting, stopping, or health-checking the dashboard or signing station | `.agents/skills/sail-servers/SKILL.md` |
+| sail-transactions | Building dispatches or any EVM transaction for the agent | `.agents/skills/sail-transactions/SKILL.md` |
+| sail-mandates | Designing, authoring, testing, deploying, or authorizing permission contracts | `.agents/skills/sail-mandates/SKILL.md` |
+| sail-ci | Automating the agent on a schedule via GitHub Actions | `.agents/skills/sail-ci/SKILL.md` |
+| sail-extend | Notifications or a custom dashboard, once the agent is live | `.agents/skills/sail-extend/SKILL.md` |
+
+## Invariants — apply to every turn
 
 - Do not present the welcome and immediately launch the UI — wait for the second "start"
-- Do not describe, mention, or present any code in `src/` or `examples/` as the user's strategy — treat Stage 2 as a blank slate; ask what they want
+- Do not describe, mention, or present any code in `src/` or `examples/` as the user's strategy — treat strategy definition as a blank slate; ask what they want
 - 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 — detect it on-chain
+- Do not hand-roll dispatch EIP-712 signatures — use `buildDispatchSignature` from the SDK
+- Do not hardcode the dispatch model — detect it on-chain with `detectKernelCapabilities`
 - Do not present example permissions as audited or as a supported menu
 - Do not commit `SAIL_PASSPHRASE` or private keys
-- Do not write a supply or deposit permission without also deploying a bounded-approve permission for each token the agent will approve — approve calls have no mandate coverage otherwise
+- ERC-20 `approve()` calls are NOT covered by supply, swap, or deposit permissions — every approve the strategy makes needs explicit coverage. Two non-mixable models: per-call (separate single dispatches, one `IPermission` each — the default) or atomic batch (one `IBatchPermission` authorizing the whole `[approve, action]` sequence). A normal `IPermission` cannot authorize a batch. Details: `.agents/skills/sail-mandates/references/approvals.md`
+- Never authorize (attach) a permission before `forge test` and `sailor mandate simulate` both pass against samples derived from the user's strategy
 - Do not pass `--args` inline JSON from PowerShell — use `--args-file` instead

package/templates/default/test/BoundedCallPermission.t.sol

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+import {Context} from "@sail/interfaces/IPermission.sol";
+import {BoundedCallPermission} from "../mandates/BoundedCallPermission.sol";
+
+/// Foundry tests for the scaffolded example permission. Runs with `forge test`
+/// and needs no external libraries: a failed `require` reverts, and a reverting
+/// test function is a test failure. (Add forge-std with `forge install
+/// foundry-rs/forge-std` if you want richer assertions and cheatcodes.)
+///
+/// When you author a permission in mandates/, copy this file and derive the
+/// cases from the user's strategy: every call the agent must be able to make
+/// (evaluate returns true) and every bound it must not cross (returns false).
+/// `forge test` must pass BEFORE `sailor mandate deploy`, and simulate must
+/// pass before `sailor mandate attach`.
+contract BoundedCallPermissionTest {
+    address internal constant ROUTER = 0x1111111111111111111111111111111111111111;
+    address internal constant UNKNOWN = 0x2222222222222222222222222222222222222222;
+    bytes4 internal constant ALLOWED_SELECTOR = bytes4(keccak256("exactInputSingle((address,address,uint24,address,uint256,uint256,uint256,uint160))"));
+    bytes4 internal constant OTHER_SELECTOR = bytes4(keccak256("transfer(address,uint256)"));
+
+    BoundedCallPermission internal permission;
+
+    function setUp() public {
+        address[] memory targets = new address[](1);
+        targets[0] = ROUTER;
+        bytes4[] memory selectors = new bytes4[](1);
+        selectors[0] = ALLOWED_SELECTOR;
+        permission = new BoundedCallPermission(targets, selectors, 0);
+    }
+
+    function _ctx(address target, bytes4 selector, uint256 value) internal view returns (Context memory) {
+        return Context({
+            account: address(0xACC0), // the Safe
+            manager: address(0xA9E7), // the agent wallet
+            submitter: address(0xA9E7),
+            target: target,
+            selector: selector,
+            value: value,
+            blockTimestamp: block.timestamp,
+            blockNumber: block.number
+        });
+    }
+
+    function test_AllowsBoundedCall() public view {
+        require(
+            permission.evaluate("", _ctx(ROUTER, ALLOWED_SELECTOR, 0)),
+            "must allow allowlisted target + selector with no ETH"
+        );
+    }
+
+    function test_RejectsUnknownTarget() public view {
+        require(
+            !permission.evaluate("", _ctx(UNKNOWN, ALLOWED_SELECTOR, 0)),
+            "must reject a target outside the allowlist"
+        );
+    }
+
+    function test_RejectsUnknownSelector() public view {
+        require(
+            !permission.evaluate("", _ctx(ROUTER, OTHER_SELECTOR, 0)),
+            "must reject a selector outside the allowlist"
+        );
+    }
+
+    function test_RejectsEthValueAboveMax() public view {
+        require(
+            !permission.evaluate("", _ctx(ROUTER, ALLOWED_SELECTOR, 1)),
+            "must reject ETH value above MAX_VALUE"
+        );
+    }
+}

package/packages/ui/dist/assets/cursor-Dk5BeeUC.js

@@ -1,3 +0,0 @@
-import{F as o}from"./core-BJ5Wn_0H.js";import"./index-Bj9jEvxf.js";import"./events-HAbmebGY.js";import"./index.es-DIo7ubqt.js";import"./fallback-CUotDuSc.js";const l=o` <svg fill="none" viewBox="0 0 13 4">
-  <path fill="currentColor" d="M.5 0h12L8.9 3.13a3.76 3.76 0 0 1-4.8 0L.5 0Z" />
-</svg>`;export{l as cursorSvg};