@dev.sail.money/sailor 1.3.0-98 → 1.4.0-244

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

@@ -1,100 +0,0 @@
----
-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-sailor/SKILL.md

@@ -1,190 +0,0 @@
----
-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

@@ -1,38 +0,0 @@
----
-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

@@ -1,58 +0,0 @@
-# ─────────────────────────────────────────────────────────────────────────────
-# 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)