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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev.sail.money/sailor",
-  "version": "1.3.0-220",
+  "version": "1.3.0-98",
   "description": "Operator toolkit for Sail Protocol",
   "bin": {
     "sailor": "packages/cli/dist/index.cjs"
@@ -26,6 +26,7 @@
   "scripts": {
     "clean": "node scripts/clean.mjs",
     "build": "pnpm --filter @sail/sdk build && pnpm --filter sailor build && pnpm --filter sailor-ui build",
+    "pack": "pnpm build && npm pack",
     "test": "pnpm --filter sailor-ui test",
     "test:ui": "pnpm --filter sailor-ui test:ui",
     "link:cli": "pnpm link --global",

package/packages/cli/dist/index.cjs

@@ -40816,6 +40816,9 @@ Pass --force to scaffold into it anyway (existing files with the same name are o
     }
   })() : null;
   copyDirSync(templateSrc, dest);
+  if (options.skills === false) {
+    import_node_fs10.default.rmSync(import_node_path8.default.join(dest, ".agents", "skills"), { recursive: true, force: true });
+  }
   const pkgRoot = packageRoot();
   const examplesPermSrc = import_node_path8.default.join(pkgRoot, "examples", "permissions");
   if (import_node_fs10.default.existsSync(examplesPermSrc)) {
@@ -45566,7 +45569,7 @@ function actionWith(fn) {
     closePrompts();
   };
 }
-program2.command("init [dir]").description("Scaffold a new Sail agent into the current directory (or [dir] subdirectory)").option("--template <name>", "Template to scaffold from (default: default)").option("--chain <id>", "Default EVM chain id written to .sail/config.json and .env.example").option("--rpc-url <url>", "Default RPC_URL written to .sail/.env.local").option("--force", "Re-initialize even if already initialized (overwrites scaffold files; keys/ and state/ are preserved)").action(
+program2.command("init [dir]").description("Scaffold a new Sail agent into the current directory (or [dir] subdirectory)").option("--template <name>", "Template to scaffold from (default: default)").option("--chain <id>", "Default EVM chain id written to .sail/config.json and .env.example").option("--rpc-url <url>", "Default RPC_URL written to .sail/.env.local").option("--force", "Re-initialize even if already initialized (overwrites scaffold files; keys/ and state/ are preserved)").option("--no-skills", "Skip scaffolding the sailor skills (use under the Sailor plugin, which already provides them to the agent)").action(
   async (name, opts) => {
     try {
       await initCommand(name, opts);

package/packages/sdk/dist/intelligence.d.ts

@@ -5,7 +5,7 @@
  * Do not edit manually — run `pnpm build` to regenerate.
  *
  * Spec version : 1.2.1
- * Generated at : 2026-06-29T14:55:18.194Z
+ * Generated at : 2026-06-29T17:17:50.187Z
  */
 export declare const SAIL_INTELLIGENCE_BASE_URL = "https://api.sail.money";
 export declare const SAIL_INTELLIGENCE_DOCS_URL = "https://api.sail.money/docs";

package/packages/sdk/dist/intelligence.js

@@ -5,7 +5,7 @@
  * Do not edit manually — run `pnpm build` to regenerate.
  *
  * Spec version : 1.2.1
- * Generated at : 2026-06-29T14:55:18.194Z
+ * Generated at : 2026-06-29T17:17:50.187Z
  */
 export const SAIL_INTELLIGENCE_BASE_URL = "https://api.sail.money";
 export const SAIL_INTELLIGENCE_DOCS_URL = "https://api.sail.money/docs";

package/scripts/check-docs.mjs

@@ -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/scripts/pack.mjs

@@ -0,0 +1,21 @@
+// Build the publishable npm package as a .tgz archive — the npm analog of `docker build`.
+// Packs under the canonical published name (@sail.money/sailor) so the artifact installs and
+// resolves exactly like the registry package; CI applies the same rename at publish time.
+// ponytail: .tgz is npm's native archive (install offline with `npm i ./<file>.tgz`). For a
+// literal .zip, unpack the tgz and re-zip — not added until something actually needs it.
+import { execSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+
+const PKG = "package.json";
+const CANONICAL = "@sail.money/sailor";
+
+const original = readFileSync(PKG, "utf8");
+try {
+  const manifest = JSON.parse(original);
+  if (manifest.name !== CANONICAL) {
+    writeFileSync(PKG, `${JSON.stringify({ ...manifest, name: CANONICAL }, null, 2)}\n`);
+  }
+  execSync("npm pack", { stdio: "inherit" }); // emits sail.money-sailor-<version>.tgz
+} finally {
+  writeFileSync(PKG, original); // restore the working manifest verbatim
+}

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

@@ -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.
 

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

@@ -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-sailor/SKILL.md

@@ -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

@@ -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

@@ -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)

package/templates/default/AGENTS.md

@@ -1,101 +1,26 @@
-This guide is for agents operating a scaffolded Sailor project. (Contributors to the Sailor codebase: see AGENTS.md at the monorepo root.)
+This is **your** Sailor project — for defining and running your agent's strategy. It is yours to edit; `sailor update` will not overwrite it.
 
-> **This is a standalone project, not a clone of the Sailor repo.** `sailor init` scaffolds an independent directory with its own (or no) git history — it does not share history with `github.com/sail-money/Sailor`. Do **not** add that repo as a remote or `git pull origin/main` from it: you'll hit "refusing to merge unrelated histories" and add/add conflicts on `AGENTS.md`, `README.md`, `package.json`, `.gitignore`, and `docs/`. To update the tooling, bump the `@sail.money/sailor` dependency (`npm i @sail.money/sailor@latest`), not by pulling the source repo.
+**How to operate Sailor** — set up the environment, onboard, build mandates, run the agent — lives in the skills below, not in this file. Start with `sail-overview`. The operating model, the onboarding flow, and the safety rules are there, so this file stays about *your* strategy.
 
----
-
-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.
-
-## Your job in mandate design
-
-When designing a mandate, your job is to help the operator express the **tightest, most complete mandate that captures their strategy's intent** — not the smallest one that compiles. Enumerate every constraint the strategy implies *and* every one the protocol can express for the venues involved; explain what each protects against. Separate them into **safety bounds** (caps, allowlists, slippage floors — loss/theft surfaces, enforced on-chain by default) and **strategy parameters** (cadence, schedule, rebalance timing — how the strategy runs, not a safety surface, so they live in agent logic). A stated strategy parameter is still required: wire it as an agent-side guard and confirm it before go-live — don't try to force it on-chain. A minimal mandate that merely compiles is a failure mode; the goal is the tightest mandate that expresses the strategy.
-
-## 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.
-
-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 flow — track to completion
-
-The five stages above are a checklist you drive to completion, not a list you mention once. Track which stages are done (read `.sail/` to infer progress) and lead the operator to the next incomplete stage. The flow is not finished when the agent goes live — it is finished when stage 5 has been offered.
-
-- [ ] 1. SMA + agent wallet deployed
-- [ ] 2. Strategy defined
-- [ ] 3. Mandate built, tested, signed
-- [ ] 4. Agent running (locally or scheduled)
-- [ ] 5. Extend — notifications and a custom dashboard
-
-After the agent is live (stage 4), **offer stage 5 by default**: one line on run/transaction notifications and one line on a strategy-specific dashboard, then ask if the operator wants either. Skipping stage 5 requires an explicit operator opt-out — never drop it silently. Hand off to **sail-extend** to build whatever they accept.
-
-## Project state — read `.sail/`, never ask
-
-Determine the user's progress by reading `.sail/` — do not ask; read it.
-
-| 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 |
+> Standalone project — not a clone of the Sailor repo. To update the tooling, bump the dependency (`npm i @sail.money/sailor@latest`); do not add that repo as a git remote.
 
 ## Skills
 
-Detailed procedures live in skills. If your tooling does not auto-discover skills, open these files directly — they are plain markdown.
+Detailed procedures live in skills under `.agents/skills/`. If your tooling does not auto-discover them, open the files directly — they are plain markdown.
 
 | Skill | Load when | Path |
 |---|---|---|
-| sail-onboarding | New project setup, or resuming a partially set-up project, documentation of sailor commands | `.agents/skills/sail-onboarding/SKILL.md` |
+| sail-setup | First-time environment readiness — dependencies, install mode, then `sailor init` | `.agents/skills/sail-setup/SKILL.md` |
+| sail-overview | How Sailor works, which skill to use when, and the safety invariants — read this first | `.agents/skills/sail-overview/SKILL.md` |
+| sail-sailor | How to invoke sailor — local vs Docker, installMode detection, all CLI commands, `sailor update` | `.agents/skills/sail-sailor/SKILL.md` |
+| sail-onboarding | New project setup, resuming a partially set-up project, or running a CLI command | `.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-automation | Automating the agent — GitHub Actions, self-hosted runner, Docker, or local daemon | `.agents/skills/sail-automation/SKILL.md` |
+| sail-transactions | Building dispatches, running the agent, or debugging a transaction | `.agents/skills/sail-transactions/SKILL.md` |
+| sail-automation | Running the agent unattended — GitHub Actions, self-hosted runner, Docker, or daemon | `.agents/skills/sail-automation/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
+## Your strategy
 
-- 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 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` 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
-- 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
-- Operator intent and the strategy's stated bounds outrank any example. If the operator asks for a bound an example omits, include it. Never let an example's shape narrow a mandate below what the operator requested
+Use the space below for notes about *your* strategy — what the agent should do, its bounds, and any project-specific context. This section is yours.