npm - @dev.sail.money/sailor - Versions diffs - 1.3.0-95 → 1.3.0-98 - Mend

@dev.sail.money/sailor 1.3.0-95 → 1.3.0-98

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

package/packages/ui/dist/assets/{walletconnect-CZkLKWMZ.js → walletconnect-CyuP92jg.js} RENAMED Viewed

@@ -1,4 +1,4 @@
-import{F as l}from"./core-DbkMGSYW.js";import"./index-D6_Zei-R.js";import"./events-CZkVDFih.js";import"./index.es-dZlNPpfR.js";import"./fallback-DWQYKf3l.js";const o=l`<svg fill="none" viewBox="0 0 96 67">
+import{F as l}from"./core-von2c1sc.js";import"./index-DLElIcBr.js";import"./events-C9icG2YB.js";import"./index.es-BaCKS_tW.js";import"./fallback-BTfJeGjh.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-BPTpHB1P.js → warning-circle-BImUCdpG.js} RENAMED Viewed

@@ -1,4 +1,4 @@
-import{F as r}from"./core-DbkMGSYW.js";import"./index-D6_Zei-R.js";import"./events-CZkVDFih.js";import"./index.es-dZlNPpfR.js";import"./fallback-DWQYKf3l.js";const a=r`<svg fill="none" viewBox="0 0 20 20">
+import{F as r}from"./core-von2c1sc.js";import"./index-DLElIcBr.js";import"./events-C9icG2YB.js";import"./index.es-BaCKS_tW.js";import"./fallback-BTfJeGjh.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-D_dEtEDU.js → x-II45JHpV.js} RENAMED Viewed

@@ -1,4 +1,4 @@
-import{F as l}from"./core-DbkMGSYW.js";import"./index-D6_Zei-R.js";import"./events-CZkVDFih.js";import"./index.es-dZlNPpfR.js";import"./fallback-DWQYKf3l.js";const a=l`<svg fill="none" viewBox="0 0 41 40">
+import{F as l}from"./core-von2c1sc.js";import"./index-DLElIcBr.js";import"./events-C9icG2YB.js";import"./index.es-BaCKS_tW.js";import"./fallback-BTfJeGjh.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-D6_Zei-R.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-DZ2C2rHq.css">
+    <script type="module" crossorigin src="/assets/index-DLElIcBr.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-lhNfD4jA.css">
   </head>
   <body>
     <div id="root"></div>

package/scripts/check-docs.mjs CHANGED Viewed

@@ -253,7 +253,7 @@ function main() {
         const line = lineRaw.trim();
         // ── CLI: `sailor <word1> [<word2>]` ──────────────────────────────────
-        for (const m of line.matchAll(/\bsailor\s+([a-z][\w-]*)(?:\s+([a-z][\w-]*))?/g)) {
+        for (const m of line.matchAll(/(?<![\/@])\bsailor\s+([a-z][\w-]*)(?:\s+([a-z][\w-]*))?/g)) {
           const [, w1, w2] = m;
           const two = w2 ? `${w1} ${w2}` : null;
           if (cli.leaves.has(w1) || (two && cli.leaves.has(two))) continue; // top-level leaf

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

@@ -94,6 +94,18 @@ Only now is the permission live. The owner (mandate signer) signs in the browser
 When a strategy needs several permissions (e.g. a bounded-approve alongside the protocol permission), attach them all at once by passing a comma-separated list of addresses — the registration approvals collapse to a **single** browser signature via the kernel's `registerPermissions`. The earlier per-contract deploy approvals (Gate 5) are separate and unavoidable. A single permission attaches exactly as before with `--address <one>`.
+## Registration fee
+Registering a permission charges a **per-permission fee**, paid on-chain by the agent wallet at the moment of registration. It is a public protocol parameter — `permissionRegistrationFee()` on `SailGovernance` — read **live from the chain**, never hardcoded: it is `0` on the current deploy and higher in production, and the same flow surfaces whichever value the connected chain returns.
+- **A mandate is a SET of permissions, so a mandate of N permissions costs `N × fee`.** Three permissions at `0.00001 ETH` each cost `0.00003 ETH` total.
+- **When it's charged:** once per permission, on registration (the `attach` / `deploy-clone` step). Already-registered permissions are not re-charged when you re-run `sailor mandate sign`. Revoking does not refund.
+- **Disclosure before signing:** `sailor mandate prepare` reads the live fee and records it in the draft, and `sailor mandate sign` prints `Registration fee: <total> ETH (<N> permissions × <fee> ETH)` before you confirm. The browser sign-time screen shows the same total.
+- **Preflight:** before requesting the owner's signature, the agent wallet's ETH balance is checked against the total fee; an underfunded wallet fails early with `Insufficient ETH for the <X> ETH registration fee` instead of an on-chain revert. **Fund the agent wallet before attaching.**
+- **Recorded:** each `permission_registered` activity entry carries the fee actually paid (`fee` in wei, `feeEth` formatted), so Recent Activity shows the real cost.
+The fee is read via `readPermissionRegistrationFee()` in `packages/sdk/src/fees.ts` and applied as `fee × N` — the same number used for disclosure, the preflight, the tx `value`, and the activity record.
 ## Maintenance
 - `sailor mandate revoke --address <P> --sma <SMA> --json` (or `--all`) — owner signs `RevokePermissions` in the browser (BLOCKS); agent submits. Revocations are recorded to the activity log; `state/mandates.json` keeps the historical record.

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

@@ -5,47 +5,46 @@ description: Walks the agent through setting up a new Sailor project or resuming
 # Sail onboarding
-## Running the CLI
+## First contact
-**Determine the installation mode first** — read `.sail/config.json → installMode` before running any command:
+On the user's first message (or after `sailor init` completes), present the full onboarding overview below — do NOT launch the UI yet. The goal is for the user to understand every stage before committing.
-- `"local"` (or field absent) — `sailor` is on the PATH. Run commands directly: `sailor <command>`
-- `"docker"` — sailor runs in a container. Read `containerName` from the same config. Prefix every command:
-  `docker exec <containerName> sailor <command>`
-  Project files are on your **local filesystem** (mounted at `/workspace` inside the container) — read and write them normally from local paths. Do NOT use `docker exec` to read files; the volume mount makes them directly accessible.
-### Starting the Docker container
-If the container is not running, start it from the project root:
-```bash
-docker run -d --name agent -P -v "${PWD}:/workspace" sailmoney/sailor
-```
-- `-d` — detached, runs in the background
-- `--name agent` — names the container; use a different name with `-e SAILOR_CONTAINER_NAME=<name>` if needed
-- `-P` — publishes all exposed ports to random available host ports (UI: 3334, station: 3141)
-- `-v "${PWD}:/workspace"` — mounts the current project directory into the container
+---
-After starting, resolve the host port before opening the UI in the browser:
+> **Sail Protocol** is infrastructure for onchain Separately Managed Accounts (SMAs) run by AI agents. You keep full custody; the agent acts only within cryptographically-bound permissions you approve and can always revoke. It cannot exceed them.
+>
+> Here is the complete path. Read it before we begin — each stage requires something from you.
+>
+> ---
+>
+> **Stage 1 — Deploy your SMA and create your agent wallet**
+> We open a browser interface where you connect your owner wallet (MetaMask or any WalletConnect wallet), choose your chain, and deploy your SMA — a smart contract account you own. We also create a separate agent wallet: a signing key the agent uses to submit transactions on your behalf. Both wallets need gas. The owner wallet signs the deployment; the agent wallet pays for everything after that.
+>
+> **Stage 2 — Define your strategy**
+> You tell me what you want the agent to do: which protocol, which tokens, what conditions, what limits. I help you separate the constraints that must be enforced on-chain (amount caps, venue allowlists, slippage floors) from the ones that live in agent logic (cadence, schedule, timing). Nothing is deployed yet — this is design.
+>
+> **Stage 3 — Build, test, and sign your mandate**
+> I write the Solidity permission contracts that encode the strategy bounds from Stage 2. You review them. We run Foundry tests against your actual strategy parameters (must-pass and must-fail cases). We deploy the contracts on-chain and simulate them before you sign anything. You authorize the permission set in the browser — one signature. After this, the agent can act autonomously within those bounds.
+>
+> **Stage 4 — Run your agent**
+> We run the agent locally first (`sailor run --once`) to confirm a full tick works. Then we automate it — GitHub Actions, a self-hosted runner, a local daemon, or Docker — matched to your latency needs and infrastructure comfort.
+>
+> **Stage 5 — Extend**
+> Once the agent is live, I offer to add run and transaction notifications (Telegram, email) and a strategy-specific dashboard. This is optional, but I will offer it — you opt out explicitly if you don't want it.
+>
+> ---
+>
+> Ready to begin? Say **start** and I'll open the setup interface in your browser for Stage 1.
-```bash
-docker port agent 3334
-# → 0.0.0.0:49201   (use 49201, not 3334, in the browser URL)
-```
+---
-All `sailor` commands run via `docker exec`:
+After the user says "start" (or "ready" or any affirmative), THEN run `sailor ui start` — the explanation and the UI launch are two separate beats. Do not skip the explanation. If the user's first message is an npm install command, run it, then present the overview immediately after.
-```bash
-docker exec agent sailor --version
-docker exec agent sailor init
-docker exec agent sailor ui start
-docker exec agent sailor station start --json &
-```
+## Running sailor commands
-The published package is **`@sail.money/sailor`** — always use the scoped name with the registry. The bare name `sailor` is a different, unrelated npm package; never `npx sailor@<version>` or `npm i sailor`. Install it (`npm i -g @sail.money/sailor`, or as a project dep), after which the `sailor` bin works bare (`sailor <command>`) and `npx sailor <command>` resolves the installed bin. Every `sailor …` command in these skills assumes it is installed. Confirm the toolchain up front and pin a recent version — `npx @sail.money/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.
+Before running any command, check how sailor is installed — see **sail-sailor** for the full guide (local vs Docker, `installMode` detection, `docker exec` prefix, `--json` flag, `SAIL_PASSPHRASE`).
-After upgrading the CLI, run `sailor update` from the project root to pull in updated skills, `AGENTS.md`, `Dockerfile`, and other tooling files. User files (`src/`, `mandates/`, `.sail/`, `package.json`) are never touched.
+Short version: read `.sail/config.json → installMode`. If `"docker"`, prefix every command with `docker exec <containerName>`. If `"local"` or absent, run `sailor <command>` directly.
 Stage machine keyed off `.sail/`. Read the state, enter at the right stage, never re-run completed stages.
@@ -104,7 +103,7 @@ If `deploy-chain` refuses with an address mismatch, the SMA was deployed against
 ## 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.
+- Agent wallet: `mandate deploy`, `mandate attach`, `mandate revoke`, and every dispatch submission once the agent runs, plus permission registration fees on fee-charging chains. The registration fee is a **per-permission flat charge** (`permissionRegistrationFee()` on `SailGovernance`, read live — currently `0` on this deploy). A mandate of N permissions costs `N × fee` on top of gas; fund the agent wallet for the full amount before attaching. The fee is disclosed at sign time (`Registration fee: X ETH`) and recorded in the activity log. An underfunded agent wallet fails early with `Insufficient ETH for the X ETH registration fee` rather than reverting on-chain.
 `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.

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

@@ -0,0 +1,100 @@
+---
+name: sail-overview
+description: Read this first on every Sailor task. Determines the current project state — installed version, which stage the user is at, what's done and what's next. Also covers the Sail model, the skill router, and the safety invariants. Use on first contact or whenever the user asks "where am I?" or "what's the status?".
+---
+# Sail overview
+Sail Protocol runs onchain Separately Managed Accounts (SMAs) operated by AI agents. The **owner keeps custody**; the agent acts only within cryptographically-bound permissions (the **mandate**) the owner approves and can always revoke. The agent cannot exceed them.
+**Voice:** 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.
+## Step 1 — Read the current project state (do this before anything else)
+Do not ask the user where they are. Read it.
+### Version
+Check `package.json` in the project root for the installed version:
+```bash
+node -e "console.log(require('./package.json').dependencies?.['@sail.money/sailor'] ?? require('./package.json').devDependencies?.['@sail.money/sailor'] ?? 'not found')"
+```
+Or run `sailor --version` (if globally installed) or `npx @sail.money/sailor --version`.
+Report the version to the user. If it is behind the latest (check with `npm show @sail.money/sailor dist-tags.latest`), surface that — stale versions may be missing commands.
+### Stage detection — read `.sail/` in this order
+| What you find | Stage | What it means |
+|---|---|---|
+| No `.sail/` directory | **Not initialized** | Run `sail-setup` |
+| `.sail/config.json` exists, `chainId` is `null` | **Stage 0** | Project initialized, chain not chosen yet |
+| No `.sail/account.json` | **Stage 1** | SMA not deployed — go to `sail-onboarding` |
+| `account.json` exists, `state/mandates.json` absent or empty | **Stage 2 / 3** | SMA live, no permissions — strategy + mandate needed |
+| `state/mandates.json` has entries, no `.sail/mandate.json` | **Stage 3** | Permissions deployed but mandate not signed yet |
+| `.sail/mandate.json` exists, `activity.jsonl` absent or no `dispatch_executed` entries | **Stage 4** | Mandate signed, agent not yet run |
+| `activity.jsonl` contains `dispatch_executed` entries | **Stage 4 complete** | Agent is running — check whether Stage 5 has been offered |
+| Stage 4 complete + user has confirmed Stage 5 (or explicitly declined) | **Done** | All stages complete |
+### What to report to the user
+After reading the state, give the user a concise status summary before doing anything else:
+> **Project:** `<name from config.json>`
+> **Version:** `@sail.money/sailor <version>` _(update available: X.Y.Z)_ ← only if behind
+> **Chain:** `<chainId>` / `<chainName>` (or "not chosen yet")
+> **Current stage:** Stage N — `<stage name>`
+> **Completed:** ✓ Stage 1, ✓ Stage 2, … (list done stages)
+> **Next:** `<one sentence on what comes next>`
+Then lead directly into the next action — do not wait for the user to ask.
+## The 5-stage flow
+1. Deploy the SMA + create the agent wallet
+2. Define the strategy
+3. Build, test, and sign the mandate
+4. Run the agent (locally or scheduled)
+5. Extend — notifications + a custom dashboard (offer by default once live; opt-out only)
+Drive to completion. Track progress by reading `.sail/` — never ask. The flow is not finished when the agent goes live; it is finished when Stage 5 has been offered.
+## `.sail/` file reference
+| File | Tells you |
+|---|---|
+| `config.json` | name, `chainId` (null until chosen), `installMode`, 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 |
+## Which skill when
+| Need | Skill |
+|---|---|
+| Install / readiness / first-time setup | **sail-setup** |
+| How to invoke sailor (local vs Docker, installMode, sailor update) | **sail-sailor** |
+| Deploy SMA, agent wallet, resume setup, run a CLI command | **sail-onboarding** |
+| Read project / account / chain / env state | **sail-project-info** |
+| Start/stop the dashboard or signing station | **sail-servers** |
+| Design / author / test / deploy permission contracts | **sail-mandates** |
+| Build dispatches, run the agent, debug a transaction | **sail-transactions** |
+| Run the agent unattended (cron, runner, daemon) | **sail-automation** |
+| Notifications + custom dashboard (once live) | **sail-extend** |
+## Invariants — apply every turn
+- Never authorize (attach) a permission before **both** `forge test` and `sailor mandate simulate` pass.
+- Never describe, mention, or present code in `src/` or `examples/` as the user's strategy — treat strategy definition as a blank slate; ask what they want.
+- Owner signing is **browser-only** — never put an owner key in the terminal.
+- Detect the dispatch model on-chain (`detectKernelCapabilities`) — do not hardcode it.
+- During setup, ask before anything that costs gas. Once the mandate is signed, the mandate is the
+  authorization — do not ask per-dispatch.
+- Never commit or print `SAIL_PASSPHRASE` or private keys.
+- ERC-20 `approve()` is **not** covered by supply/swap/deposit permissions — cover every approve explicitly (see sail-mandates).

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

@@ -28,3 +28,5 @@ Every command here is read-only and supports `--json` for machine reading. Prefe
 - "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.
+- "What is the permission registration fee?" — `permissionRegistrationFee()` on `SailGovernance` (read live; currently `0` on this deploy). `sailor mandate sign` and `sailor mandate prepare` print the fee before signing. Each `permission_registered` entry in the activity log includes `fee` (wei) and `feeEth` (formatted), so Recent Activity shows the real cost paid per registration.

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

@@ -0,0 +1,190 @@
+---
+name: sail-sailor
+description: How to invoke the Sailor CLI in any environment — local install, global install, npx, or Docker. Covers installMode detection, the correct scoped package name, docker exec prefix, starting the container, the --json flag, SAIL_PASSPHRASE, and sailor update. Read this before running any sailor command if you are unsure how the project is installed.
+---
+# Sail sailor — invoking the CLI
+Every skill in this project runs `sailor` commands. This skill explains how to invoke them correctly regardless of how Sailor is installed.
+## Step 1 — Detect the install mode
+Before running any command, read `.sail/config.json → installMode`:
+```bash
+node -e "const c=require('./.sail/config.json'); console.log(c.installMode ?? 'local')"
+```
+| `installMode` | How to run sailor |
+|---|---|
+| `"local"` (or field absent) | `sailor <command>` — the CLI is on the PATH |
+| `"docker"` | `docker exec <containerName> sailor <command>` — sailor runs inside the container |
+For docker mode, also read `containerName` from the same config (defaults to `"agent"` if absent).
+## Plugin mode vs. project mode
+If you are operating Sailor through the **Claude agent plugin**, sailor is bundled inside the plugin — no separate install is needed. The plugin provides the skills directly; for running CLI commands within a project, the project-level install applies.
+If you are operating a **standalone project** (no plugin), sailor must be available to run commands. Use project-level installation.
+## Local installation
+Sailor is published as **`@sail.money/sailor`** — always use the scoped name. The bare `sailor` on npm is a different, unrelated package.
+### Project-level (recommended)
+`sailor init` adds `@sail.money/sailor` to `package.json` automatically. After `npm install`, invoke it via:
+```bash
+npx sailor <command>
+```
+This is the preferred approach because:
+- The version is **pinned** in `package.json` — reproducible across machines and CI
+- `sailor update` bumps the version and re-syncs agent files (skills, `AGENTS.md`) atomically
+- Multiple projects can run different versions side by side without conflict
+### Global install (for bootstrapping only)
+Use a global install only when sailor needs to run **before a project exists** (e.g. to run `sailor init` in a fresh folder) or for one-off diagnostics outside a project:
+```bash
+npm install -g @sail.money/sailor
+sailor init          # creates the project; package.json now pins the version
+```
+Once the project is initialized, the project-level dep takes over — you do not need the global install again.
+### On-the-fly via npx (no install at all)
+```bash
+npx @sail.money/sailor@latest <command>
+```
+Useful for `sailor init` in a fresh folder without any prior install. Slower on first run (downloads each time unless cached).
+### Dev / pre-release versions
+**Only install the dev build if the user explicitly asks for it.** Default to the stable release for all installs.
+The development build is published under a separate scope (`@dev.sail.money/sailor`). Install it using an npm alias so all skills, imports, and `npx sailor` commands work transparently — nothing in the project needs to know it is a dev build:
+```bash
+npm install "@sail.money/sailor@npm:@dev.sail.money/sailor@dev"
+```
+After this, `npx sailor --version` resolves the dev build, and every skill in this project runs as normal. To go back to stable:
+```bash
+npm install @sail.money/sailor@latest
+```
+If a documented command reports `unknown command`, the installed version is stale — run `sailor update` or reinstall.
+## Docker installation
+### Starting the container
+Run from the project root:
+```bash
+docker run -d --name agent -P -v "${PWD}:/workspace" sailmoney/sailor
+```
+| Flag | Meaning |
+|---|---|
+| `-d` | Detached — runs in the background |
+| `--name agent` | Container name used in all `docker exec` calls |
+| `-P` | Maps container ports (UI: 3334, signing station: 3141) to random host ports |
+| `-v "${PWD}:/workspace"` | Mounts the current project directory into the container |
+Use a different container name with `--name <name>` and set `containerName` in `.sail/config.json` to match.
+### Running commands
+Prefix every sailor command with `docker exec <containerName>`:
+```bash
+docker exec agent sailor --version
+docker exec agent sailor doctor
+docker exec agent sailor run --once
+docker exec agent sailor ui start
+```
+Project files are on your **local filesystem** — read and write them directly from local paths. Only `sailor` commands need the `docker exec` prefix; the volume mount makes all files accessible from both sides.
+### Opening the dashboard (Docker)
+The UI binds to port **3334 inside the container**, but the host port depends on how `-P` mapped it. Always resolve it before giving the user a URL:
+```bash
+docker port agent 3334
+# → 0.0.0.0:49201   (open http://localhost:49201)
+```
+### Stop / restart
+```bash
+docker stop agent    # stop the container
+docker start agent   # restart it (project files are on the host — nothing is lost)
+```
+## Flags that work on every command
+| Flag | Effect |
+|---|---|
+| `--json` | Machine-readable JSON output — prefer this; parse, don't scrape |
+| `--help` | Usage and flags for that command |
+Set `SAIL_PASSPHRASE` in `.sail/.env.local` to unlock the agent wallet non-interactively (CI, headless runs, Docker). Never commit or print this value.
+## Key CLI commands at a glance
+```bash
+# Diagnostics
+sailor --version                   # installed version
+sailor doctor                      # kernel health, RPC reachability, gas balances
+sailor chains                      # supported chains and kernel addresses
+sailor capabilities                # what you can build on the current chain
+# Account
+sailor account predict             # compute deterministic SMA address before deploying
+sailor scan                        # discover owner's Safes and Sail SMAs
+# Mandate lifecycle
+sailor mandate simulate            # probe a permission off-chain before authorizing
+sailor mandate deploy              # deploy a permission contract (owner signs in browser)
+sailor mandate attach              # register a deployed permission on an SMA
+sailor mandate sign                # build and sign the mandate payload
+sailor mandate list                # list permissions deployed from this project
+# Agent
+sailor run --once                  # single tick — confirm before automating
+sailor run                         # continuous agent loop
+sailor keys export-ci              # copy encrypted wallet to ci-keystore.json for CI
+# Unattended execution
+sailor service install             # install as OS daemon (launchd / systemd / Task Scheduler)
+sailor service status              # daemon status
+sailor service logs -f             # follow the agent log
+# Dashboard
+sailor ui start                    # start dashboard, print URL
+sailor ui stop                     # stop dashboard
+sailor ui status                   # running status + URL + pid
+# Maintenance
+sailor update                      # re-sync skills, AGENTS.md, and tooling files after a CLI upgrade
+sailor trigger github              # fire the GitHub Actions agent workflow on demand
+```
+## Keeping the CLI up to date
+After upgrading `@sail.money/sailor` in `package.json`, run:
+```bash
+sailor update
+```
+This re-syncs the agent tooling files — skills, `AGENTS.md`, `Dockerfile` — without touching user code (`src/`, `mandates/`), keys, or runtime state (`.sail/keys/`, `.sail/state/`, `.sail/activity.jsonl`).

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

@@ -0,0 +1,38 @@
+---
+name: sail-setup
+description: First-time environment readiness for Sailor — check the essential toolchain (Node, npm, the sailor CLI), confirm the target folder, then run `sailor init`. Use when the user wants to start a Sailor project or build a DeFi strategy Sailor can run, or when there is no `.sail/` in the current folder. Proceed through setup without step-by-step permission; the only required confirmation is the target directory. Hands off to sail-overview + sail-onboarding.
+---
+# Sail setup
+When the user wants to start a Sailor project — or a DeFi strategy Sailor can run — **proceed through setup; do not ask step-by-step permission.** Only two things need an explicit OK: the **target folder** (step 4) and **installing any system-level tool** (step 3).
+## 1. Detect environment
+- OS + shell (Windows/macOS/Linux; pwsh/bash/zsh).
+- If `.sail/` already exists here, the project is initialized — skip to **sail-onboarding** (resume); do not re-init.
+## 2. Check the toolchain
+**Essential (needed now):** `node -v` (≥ 18), `npm -v`, `npx @sail.money/sailor --version` (scoped name only — bare `npx sailor` is a different package).
+**Use-case tools — probe and note, but do NOT install at setup; each is handled when its stage arrives:**
+| Tool | Needed only for | Handled in |
+|---|---|---|
+| Foundry (`forge --version`) | authoring/building Solidity permission contracts | sail-mandates (Stage 3) |
+| git + GitHub CLI (`git --version`, `gh --version`) | publishing to GitHub / GitHub Actions runs | sail-automation (only if that path is chosen) |
+| Docker (`docker --version`) | running sailor in a container instead of locally | only if docker install mode is picked |
+Report what's missing among these, but don't block setup or install them now — surface them when the matching stage comes up.
+## 3. Install missing tools — confirm before anything system-level
+- sailor itself: run via `npx @sail.money/sailor` (no install), a global `npm i -g @sail.money/sailor`, or docker (`SAILOR_INSTALL_MODE=docker`).
+- **Node, Docker, Foundry, git: ask before installing.** Foundry: `curl -L https://foundry.paradigm.xyz | bash` then `foundryup` (see sail-mandates).
+## 4. Confirm the target folder, then init
+**The one confirmation that matters.** `sailor init` scaffolds into the **current folder of this session** — state its absolute path and confirm it is the right place before running, because it writes scaffold files (`package.json`, `AGENTS.md`, `foundry.toml`, `.sail/`, …) and would overwrite any existing files with those names. Once confirmed, run it — no further step-gating:
+- `sailor init` — standalone
+- `sailor init --no-skills` — under the Sailor plugin (the plugin already provides the skills)
+RPC readiness: `RPC_URL` + `CHAIN_ID` live in `.sail/.env.local` (the chain is chosen in onboarding Stage 1; `SAIL_PASSPHRASE` only for headless/CI).
+## 5. Hand off
+Read **sail-overview** for the operating model, then **sail-onboarding** to deploy the SMA and continue.

package/templates/default/.gitlab-ci.yml ADDED Viewed

@@ -0,0 +1,58 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# WHEN does your agent run? Two mechanisms — you almost certainly need to tune
+# the first one for your strategy.
+#
+#   1. Scheduled pipelines — a heartbeat / backstop. Schedules are NOT defined
+#      in this file; create them in GitLab UI → CI/CD → Schedules (or via API).
+#      GitLab schedules can drift and be skipped under load, so they are the
+#      wrong PRIMARY driver for anything latency-sensitive. Tune cadence:
+#        • LP / perps / liquidations  → minutes — but don't rely on schedules;
+#          use a pipeline trigger (#2). Schedules are only a safety net here.
+#        • DCA / periodic rebalance    → daily.
+#        • treasury / slow rebalances  → hourly to daily.
+#      When creating the schedule, "0 * * * *" (hourly) is a GENERIC PLACEHOLDER
+#      — change it to match your strategy.
+#
+#   2. Pipeline triggers — an on-demand trigger. Anything that can make an HTTP
+#      call can wake this job instantly (a price band, an on-chain event, a
+#      webhook). Fire it from the CLI:  sailor trigger gitlab
+#      This is how you get low-latency reaction that schedules cannot give you.
+#      Pass an optional REASON variable to label the run in the logs:
+#        curl -X POST "$CI_API_V4_URL/projects/$CI_PROJECT_ID/trigger/pipeline" \
+#          --form "token=<TRIGGER_TOKEN>" \
+#          --form "ref=main" \
+#          --form "variables[REASON]=price alert"
+# ─────────────────────────────────────────────────────────────────────────────
+stages:
+  - tick
+agent-tick:
+  stage: tick
+  image: node:20
+  # Only run on schedules, pipeline triggers, and manual web runs.
+  # Push pipelines are excluded — the agent tick is not a build/test step.
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "schedule"'
+    - if: '$CI_PIPELINE_SOURCE == "trigger"'
+    - if: '$CI_PIPELINE_SOURCE == "web"'
+  script:
+    - mkdir -p .sail/keys
+    - cp ci-keystore.json .sail/keys/manager.json
+    - npm ci
+    - |
+      export CHAIN_ID="${CHAIN_ID:-8453}"
+      export SAIL_RUN_REASON="${REASON:-$CI_PIPELINE_SOURCE}"
+      npx sailor run --once
+  # Required CI/CD variables (Settings → CI/CD → Variables):
+  #   RPC_URL          — your chain RPC endpoint            [masked]
+  #   SAIL_PASSPHRASE  — keystore decryption passphrase     [masked]
+  #
+  # Optional CI/CD variables (override defaults):
+  #   CHAIN_ID         — chain ID if not Base (default: 8453)
+  #
+  # Trigger variables (passed per-run via API or sailor trigger gitlab):
+  #   REASON           — why this run fired (recorded in SAIL_RUN_REASON)