npm - @dev.sail.money/sailor - Versions diffs - 0.0.2 → 1.0.0-38 - Mend

@dev.sail.money/sailor 0.0.2 → 1.0.0-38

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

Files changed (199) hide show

package/packages/ui/dist/assets/{walletconnect-8pZBDvVI.js → walletconnect-BiltKqAe.js} RENAMED Viewed

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

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

@@ -1,4 +1,4 @@
-import{F as r}from"./core-Ckx_cyuH.js";import"./index-Q2Yai4Fe.js";import"./events-CiKP71cK.js";import"./index.es-C78cE5SI.js";import"./fallback-Ofl6uSnB.js";const a=r`<svg fill="none" viewBox="0 0 20 20">
+import{F as r}from"./core-tX9kIIDJ.js";import"./index-DZfBh-cg.js";import"./events-DjdZr6no.js";import"./index.es-BEcNQEn-.js";import"./fallback-DJIr_fH3.js";const a=r`<svg fill="none" viewBox="0 0 20 20">
   <path
     fill="currentColor"
     d="M11 6.67a1 1 0 1 0-2 0v2.66a1 1 0 0 0 2 0V6.67ZM10 14.5a1.25 1.25 0 1 0 0-2.5 1.25 1.25 0 0 0 0 2.5Z"

package/packages/ui/dist/assets/{x-C_TBsTMj.js → x-FBttjBWO.js} RENAMED Viewed

@@ -1,4 +1,4 @@
-import{F as l}from"./core-Ckx_cyuH.js";import"./index-Q2Yai4Fe.js";import"./events-CiKP71cK.js";import"./index.es-C78cE5SI.js";import"./fallback-Ofl6uSnB.js";const a=l`<svg fill="none" viewBox="0 0 41 40">
+import{F as l}from"./core-tX9kIIDJ.js";import"./index-DZfBh-cg.js";import"./events-DjdZr6no.js";import"./index.es-BEcNQEn-.js";import"./fallback-DJIr_fH3.js";const a=l`<svg fill="none" viewBox="0 0 41 40">
   <g clip-path="url(#a)">
     <path fill="#000" d="M.8 0h40v40H.8z" />
     <path

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

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

package/scripts/check-init.mjs CHANGED Viewed

@@ -53,9 +53,8 @@ try {
     fail(`\`sailor init ${PROJECT}\` exited non-zero.\n  ${out || err.message}`);
   }
-  // A successful fresh init prints the welcome + next steps, ending with the
-  // `Say: "start"` call-to-action. (Older builds printed "Done!".)
-  if (!/Say: "start"/.test(stdout)) {
+  // A successful fresh init prints the AGENTS.md onboarding banner.
+  if (!/AGENTS\.md/i.test(stdout)) {
     fail(`init did not report success.\n  stdout: ${stdout.trim()}`);
   }

package/templates/custom-mandate/README.md CHANGED Viewed

@@ -78,8 +78,39 @@ Both attach paths open the browser signing station so the owner authorizes the r
 > contract address you provide. A bug can block all agent activity or authorize transactions you did
 > not intend. Review carefully before attaching.**
+## Extracting calldata parameters safely
+When you need to bound a specific call argument (amount cap, recipient check, slippage floor),
+use `SailCalldata` instead of manual `abi.decode`. The two common bugs it prevents:
+1. **Forgetting the length check** — decoding before checking `txData.length` can revert or
+   silently return wrong values. `SailCalldata.hasParams(txData, N)` is the one-line guard.
+2. **Wrong slot index** — off-by-one decodes the wrong parameter. Named helpers make the
+   intent explicit: `asAddress(txData, 0)`, `asUint256(txData, 1)`, `asAddress(txData, 2)`.
+```solidity
+import {SailCalldata} from "./SailCalldata.sol";
+function evaluate(bytes calldata txData, Context calldata ctx) external view returns (bool) {
+    if (ctx.target != POOL)        return false;
+    if (ctx.selector != SEL_SUPPLY) return false;
+    // supply(address asset, uint256 amount, address onBehalfOf, uint16 referralCode)
+    if (!SailCalldata.hasParams(txData, 4)) return false;
+    address asset      = SailCalldata.asAddress(txData, 0);
+    uint256 amount     = SailCalldata.asUint256(txData, 1);
+    address onBehalfOf = SailCalldata.asAddress(txData, 2);
+    // ...
+}
+```
+Available helpers: `asAddress`, `asUint256`, `asInt256`, `asBytes32`, `asBool`,
+`asUint128`, `asUint64`, `asUint32`, `asUint24`, `asUint16`, `asBytes4`.
+Only covers static (fixed-size) types. For `bytes`, `string`, or dynamic arrays,
+use `abi.decode(txData[4:], ...)` after the `hasParams` guard.
 ## Structure
 - `foundry.toml` — Foundry config with `@sail/` remapping to `.sail/contracts/`
 - `.sail/contracts/interfaces/IPermission.sol` — interface copy (matches SailProtocol)
 - `mandates/BoundedCallPermission.sol` — general primitive: allowlisted targets, optional selector filter, max ETH value
+- `mandates/SailCalldata.sol` — safe calldata parameter extraction helpers

package/templates/custom-mandate/mandates/BoundedCallPermission.sol CHANGED Viewed

@@ -2,12 +2,18 @@
 pragma solidity 0.8.26;
 import {IPermission, Context} from "@sail/interfaces/IPermission.sol";
+// SailCalldata: safe helpers for extracting calldata parameters inside evaluate().
+// Use SailCalldata.hasParams(txData, N) + SailCalldata.asAddress/asUint256/... instead of
+// manual abi.decode when you need to bound specific call arguments (amounts, recipients, etc.).
+// See SailCalldata.sol for the full API and examples/permissions/ for protocol examples.
+import {SailCalldata} from "./SailCalldata.sol";
 /// @title BoundedCallPermission
 /// @notice General-purpose IPermission primitive. Bounds the universal properties of any call:
 ///         allowed targets, allowed selectors, and max ETH value. Protocol-agnostic.
-///         For calldata-parameter bounds (amount caps, recipient checks, slippage), write a
-///         protocol-specific permission — see examples/permissions/ for the pattern per protocol.
+///         For calldata-parameter bounds (amount caps, recipient checks, slippage), use
+///         SailCalldata (imported above) and write a protocol-specific permission —
+///         see examples/permissions/ for the pattern per protocol.
 /// @dev Deploy one instance per SMA with constructor-configured parameters.
 contract BoundedCallPermission is IPermission {
     bytes32 private constant DISCRIMINATOR = keccak256("BoundedCallPermission");

package/templates/custom-mandate/mandates/SailCalldata.sol ADDED Viewed

@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+// ─────────────────────────────────────────────────────────────────────────────
+// SailCalldata — safe static-parameter extraction for IPermission.evaluate()
+//
+// PROBLEM
+//   evaluate(bytes calldata txData, Context calldata ctx) receives raw ABI-
+//   encoded calldata. Extracting parameters by hand is the most dangerous part
+//   of permission writing:
+//     • Forgetting the length check before decoding → silent wrong value or
+//       revert instead of clean `return false`.
+//     • Wrong slot index → decoding the wrong parameter (type-checks, still wrong).
+//     • Truncation bugs when casting uint256 slots to address (padding bits).
+//
+// SOLUTION
+//   This library centralises the three operations into named helpers:
+//     1. hasParams()  — explicit length guard (call once, at the top of evaluate)
+//     2. asAddress()  — extract + mask to 20 bytes
+//     3. asUint256(), asInt256(), asBytes32(), asBool(), asUint128() — typed slots
+//
+//   All helpers are view/pure and add zero gas overhead beyond the slice itself.
+//
+// USAGE (replace abi.decode pattern)
+//
+//   // Before:
+//   if (txData.length < 4 + 3 * 32) return false;
+//   (address asset, uint256 amount, address onBehalfOf) =
+//       abi.decode(txData[4:], (address, uint256, address));
+//
+//   // After:
+//   if (!SailCalldata.hasParams(txData, 3)) return false;
+//   address  asset      = SailCalldata.asAddress(txData, 0);
+//   uint256  amount     = SailCalldata.asUint256(txData, 1);
+//   address  onBehalfOf = SailCalldata.asAddress(txData, 2);
+//
+// LIMITATIONS
+//   Only covers static (fixed-size) ABI types. Dynamic types (bytes, string,
+//   arrays) use pointer indirection — decode them with abi.decode(txData[4:], ...)
+//   after the hasParams() guard, or write a dedicated extractor.
+//
+// SLOT INDEXING
+//   Slots are 0-indexed from the first constructor parameter (after the 4-byte
+//   selector). Slot 0 = bytes [4..35], slot 1 = bytes [36..67], etc.
+// ─────────────────────────────────────────────────────────────────────────────
+library SailCalldata {
+    // ── Guards ────────────────────────────────────────────────────────────────
+    /// @notice Returns true when txData is long enough to hold `params` static
+    ///         32-byte ABI slots after the 4-byte selector.
+    /// @dev    Call this once at the top of evaluate() before any slot access.
+    ///         Returns false (not revert) so evaluate() can return false cleanly.
+    function hasParams(bytes calldata txData, uint256 params) internal pure returns (bool) {
+        return txData.length >= 4 + params * 32;
+    }
+    // ── Static-type extractors ────────────────────────────────────────────────
+    // All assume hasParams() has already been checked for the relevant slot.
+    // Accessing an out-of-bounds slot will cause the calldata slice to revert —
+    // always guard with hasParams() first.
+    /// @notice Extract an address from ABI slot `i` (0-indexed after selector).
+    ///         Masks to 20 bytes, discarding the ABI zero-padding in the upper 12.
+    function asAddress(bytes calldata txData, uint256 i) internal pure returns (address) {
+        return address(uint160(uint256(bytes32(txData[4 + i * 32 : 4 + (i + 1) * 32]))));
+    }
+    /// @notice Extract a uint256 from ABI slot `i`.
+    function asUint256(bytes calldata txData, uint256 i) internal pure returns (uint256) {
+        return uint256(bytes32(txData[4 + i * 32 : 4 + (i + 1) * 32]));
+    }
+    /// @notice Extract an int256 from ABI slot `i`.
+    function asInt256(bytes calldata txData, uint256 i) internal pure returns (int256) {
+        return int256(uint256(bytes32(txData[4 + i * 32 : 4 + (i + 1) * 32])));
+    }
+    /// @notice Extract a bytes32 from ABI slot `i`.
+    function asBytes32(bytes calldata txData, uint256 i) internal pure returns (bytes32) {
+        return bytes32(txData[4 + i * 32 : 4 + (i + 1) * 32]);
+    }
+    /// @notice Extract a bool from ABI slot `i` (true when slot value is non-zero).
+    function asBool(bytes calldata txData, uint256 i) internal pure returns (bool) {
+        return asUint256(txData, i) != 0;
+    }
+    /// @notice Extract a uint128 from ABI slot `i` (lower 128 bits of the slot).
+    function asUint128(bytes calldata txData, uint256 i) internal pure returns (uint128) {
+        return uint128(asUint256(txData, i));
+    }
+    /// @notice Extract a uint64 from ABI slot `i`.
+    function asUint64(bytes calldata txData, uint256 i) internal pure returns (uint64) {
+        return uint64(asUint256(txData, i));
+    }
+    /// @notice Extract a uint32 from ABI slot `i`.
+    function asUint32(bytes calldata txData, uint256 i) internal pure returns (uint32) {
+        return uint32(asUint256(txData, i));
+    }
+    /// @notice Extract a uint24 from ABI slot `i` (e.g. Uniswap fee tier).
+    function asUint24(bytes calldata txData, uint256 i) internal pure returns (uint24) {
+        return uint24(asUint256(txData, i));
+    }
+    /// @notice Extract a uint16 from ABI slot `i` (e.g. Aave referral code).
+    function asUint16(bytes calldata txData, uint256 i) internal pure returns (uint16) {
+        return uint16(asUint256(txData, i));
+    }
+    /// @notice Extract bytes4 (a function selector) from ABI slot `i`.
+    function asBytes4(bytes calldata txData, uint256 i) internal pure returns (bytes4) {
+        return bytes4(asBytes32(txData, i));
+    }
+}

package/templates/default/.env.example ADDED Viewed

@@ -0,0 +1,20 @@
+# Sailor agent environment
+#
+# RPC configuration — two patterns, pick one:
+#
+# Option A: single active chain (simplest)
+RPC_URL=https://your-rpc-endpoint
+CHAIN_ID=8453
+#
+# Option B: per-chain endpoints (multi-chain projects, or if you prefer explicit names)
+# Set CHAIN_ID to the chain sailor run uses; omit RPC_URL if all chains have a specific var.
+# CHAIN_ID=8453
+# BASE_RPC_URL=https://your-base-endpoint
+# ARBITRUM_RPC_URL=https://your-arbitrum-endpoint
+# UNICHAIN_RPC_URL=https://your-unichain-endpoint
+# ETH_MAINNET_RPC_URL=https://your-mainnet-endpoint
+# BASE_SEPOLIA_RPC_URL=https://your-base-sepolia-endpoint
+# SEPOLIA_RPC_URL=https://your-sepolia-endpoint
+# Optional: non-interactive passphrase (CI, GitHub Actions, launchd, systemd)
+# SAIL_PASSPHRASE=change-me-to-a-strong-passphrase

package/templates/{dca-rebalancer → default}/.github/workflows/agent-tick.yml RENAMED Viewed

@@ -12,21 +12,22 @@ jobs:
     steps:
       - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v4
-        with:
-          version: 9
       - uses: actions/setup-node@v4
         with:
           node-version: 20
-          cache: "pnpm"
+          cache: "npm"
       - name: Install dependencies
-        run: pnpm install --frozen-lockfile
+        run: npm ci
+      - name: Copy keystore to expected path
+        run: |
+          mkdir -p .sail/keys
+          cp ci-keystore.json .sail/keys/manager.json
       - name: Run agent tick
         env:
           RPC_URL: ${{ secrets.RPC_URL }}
-          MANAGER_KEY: ${{ secrets.MANAGER_KEY }}
+          SAIL_PASSPHRASE: ${{ secrets.SAIL_PASSPHRASE }}
           CHAIN_ID: ${{ vars.CHAIN_ID || '8453' }}
         run: npx sailor run --once

package/templates/{dca-rebalancer → default}/.sail/config.json RENAMED Viewed

@@ -1,7 +1,7 @@
 {
   "version": 1,
-  "name": "dca-rebalancer",
-  "chainId": 8453,
+  "name": "sail-agent",
+  "chainId": null,
   "stateDir": ".sail/state",
   "contracts": {
     "kernel": "",

package/templates/default/AGENTS.md ADDED Viewed

@@ -0,0 +1,171 @@
+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.
+Here's where we're headed:
+1. Deploy your SMA and create your agent wallet
+2. Define your strategy
+3. Build, test, and sign your mandate
+4. Run your agent — locally or on a schedule
+5. Extend with notifications and a custom dashboard
+Ready? 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. Serious, precise, confident. No hype, no emojis, no exclamation marks. Explain *why*, not just *what* — the user is moving real funds. Use user-facing terms (SMA, mandate, permissions, agent wallet, owner). Assume crypto-native; teach the Sail-specific model.
+Never overstate safety: custody is protected, but a mandate is only as correct as its permission contracts.
+## Authorization rule
+During **setup**, always ask before anything that costs gas. Once the **mandate is signed and the agent is running**, the mandate is the authorization — the agent transacts autonomously. Do not ask per-dispatch.
+## First contact
+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.
+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.
+## What NOT to do
+- 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 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 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
+- Do not pass `--args` inline JSON from PowerShell — use `--args-file` instead

package/templates/default/README.md ADDED Viewed

@@ -0,0 +1,16 @@
+# Sail Protocol Agent
+A blank Sail Protocol agent project. Open this folder in your AI coding assistant and say:
+> start
+Your assistant will walk you through every step — chain selection, SMA deployment, strategy design, mandate authoring, and automation.
+## Project layout
+- `src/agent.ts` — your agent's tick loop (implement your strategy here)
+- `src/mandate.ts` — your strategy parameters and contract addresses
+- `mandates/` — Foundry workspace for your IPermission contracts
+- `examples/dca/` — worked reference: DCA (USDC→WETH) on Base via Uniswap V3
+- `examples/permissions/` — protocol-specific permission examples
+- `.sail/` — local project state (keys, account, activity log)

package/templates/default/examples/dca/README.md ADDED Viewed

@@ -0,0 +1,16 @@
+# DCA reference example
+**Reference only — not your strategy.** This shows a complete worked implementation of a dollar-cost-averaging agent (USDC → WETH via Uniswap V3 on Base). Consult it for patterns when authoring your own strategy in `src/`.
+## What it shows
+| File | Purpose |
+|---|---|
+| `mandate.ts` | Token addresses, swap parameters, and contract addresses for Base mainnet |
+| `agent.ts` | Full tick loop: check balance → approve if needed → quote → swap with slippage protection |
+## How to use it
+In Stage 2 (strategy), when you describe what you want, your assistant will adapt these patterns for your protocol, chain, and parameters — not copy them as-is.
+The on-chain permission contract that authorizes these dispatches must be authored separately (Stage 3). The agent code here is only the intent-building side; the mandate enforces the on-chain bounds.