@dev.sail.money/sailor 1.2.0-83 → 1.2.1-197

package/README.md

@@ -143,7 +143,7 @@ sailor onboard --new-sma   # deploy SMA and optionally attach a mandate
 sailor mandate simulate    # probe a permission off-chain (no gas) before registering
 sailor mandate sign        # sign the mandate — reconciles against live on-chain state
 sailor mandate deploy      # deploy a Foundry-compiled permission contract
-sailor mandate attach      # register an already-deployed permission on an SMA
+sailor mandate attach      # register a deployed permission on an SMA (or a comma-separated list, in one signature)
 
 # Agent operation
 sailor run --once          # single tick — confirm it works before automating

package/examples/custom-mandate/README.md

@@ -64,7 +64,14 @@ sailor mandate deploy --contract <Name>            # prints the deployed address
 sailor mandate attach --address <deployedAddress> --sma <SMA>
 ```
 
-Both attach paths open the browser signing station so the owner authorizes the registration
+To attach several permissions, deploy each one first, then register them all in a single
+signature by passing a comma-separated list:
+
+```bash
+sailor mandate attach --address <addr1>,<addr2>,<addr3> --sma <SMA>
+```
+
+These attach commands open the browser signing station so the owner authorizes the registration
 (EIP-712 `RegisterPermission`); the agent submits the on-chain transaction.
 
 ## Prerequisites

package/examples/permissions/README.md

@@ -74,6 +74,9 @@ To deploy within a Sailor project (copy the .sol file to `mandates/` first):
 sailor mandate deploy --contract <Name> --args '[...]' --attach --sma <SMA>
 ```
 
+For several permissions, deploy each one (without `--attach`), then register them together in
+one signature: `sailor mandate attach --address <addr1>,<addr2> --sma <SMA>`.
+
 ## Verify before you authorize
 
 Prove a permission accepts the calls you want and rejects the ones you don't — before paying

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev.sail.money/sailor",
-  "version": "1.2.0-83",
+  "version": "1.2.1-197",
   "description": "Operator toolkit for Sail Protocol",
   "bin": {
     "sailor": "packages/cli/dist/index.cjs"
@@ -24,6 +24,7 @@
     "AGENTS.md"
   ],
   "scripts": {
+    "clean": "node scripts/clean.mjs",
     "build": "pnpm --filter @sail/sdk build && pnpm --filter sailor build && pnpm --filter sailor-ui build",
     "test": "pnpm --filter sailor-ui test",
     "test:ui": "pnpm --filter sailor-ui test:ui",

package/packages/cli/dist/index.cjs

@@ -38596,7 +38596,7 @@ var import_websocket2 = __toESM(require_websocket2(), 1);
 var import_websocket_server2 = __toESM(require_websocket_server2(), 1);
 
 // src/signing/server.ts
-var DEFAULT_SIGNING_PORT = 3141;
+var DEFAULT_SIGNING_PORT = Number(process.env.SAILOR_STATION_PORT ?? 3141);
 var RUNTIME_SUBDIR = (0, import_node_path4.join)(".sail", "runtime");
 var SERVER_STATE_FILE = "server.json";
 var REQUEST_SECRET_HEADER = "x-sailor-secret";
@@ -40770,6 +40770,8 @@ function scaffoldProjectWorkspace(dest, name, options) {
   import_node_fs9.default.mkdirSync(import_node_path8.default.join(sailDir2, "keys"), { recursive: true });
   import_node_fs9.default.mkdirSync(import_node_path8.default.join(sailDir2, "runtime"), { recursive: true });
   import_node_fs9.default.mkdirSync(import_node_path8.default.join(sailDir2, "state"), { recursive: true });
+  const installMode = process.env.SAILOR_INSTALL_MODE === "docker" ? "docker" : "local";
+  const containerName = process.env.SAILOR_CONTAINER_NAME ?? "agent";
   import_node_fs9.default.writeFileSync(
     import_node_path8.default.join(sailDir2, "config.json"),
     `${JSON.stringify(
@@ -40780,6 +40782,8 @@ function scaffoldProjectWorkspace(dest, name, options) {
         // null = chain not yet chosen; Stage 1 will set this
         stateDir: ".sail/state",
         createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+        installMode,
+        ...installMode === "docker" ? { containerName } : {},
         contracts: {
           kernel: "",
           mandateFactory: ""
@@ -40871,6 +40875,14 @@ Pass --force to scaffold into it anyway (existing files with the same name are o
       "This project is already initialized.\nRun `sailor update` to re-sync template files, or `sailor init --force` to re-initialize (overwrites scaffold files; your .sail/keys/ and .sail/state/ are left in place)."
     );
   }
+  const existingConfigPath = import_node_path8.default.join(dest, ".sail", "config.json");
+  const previousConfig = import_node_fs9.default.existsSync(existingConfigPath) ? (() => {
+    try {
+      return JSON.parse(import_node_fs9.default.readFileSync(existingConfigPath, "utf-8"));
+    } catch {
+      return null;
+    }
+  })() : null;
   copyDirSync(templateSrc, dest);
   const pkgRoot = packageRoot();
   const examplesPermSrc = import_node_path8.default.join(pkgRoot, "examples", "permissions");
@@ -40910,6 +40922,18 @@ Pass --force to scaffold into it anyway (existing files with the same name are o
   }
   scaffoldProjectWorkspace(dest, name, options);
   scaffoldFoundryWorkspace(dest);
+  const newMode = process.env.SAILOR_INSTALL_MODE === "docker" ? "docker" : "local";
+  if (previousConfig?.installMode === "docker" && newMode === "local") {
+    const prev = previousConfig.containerName ?? "agent";
+    console.log(`
+Switched to local install. If the Docker container is still running:`);
+    console.log(`  docker stop ${prev}`);
+    console.log(`You can restart it anytime with the standard docker run command.`);
+  } else if (previousConfig?.installMode === "local" && newMode === "docker") {
+    const containerName = process.env.SAILOR_CONTAINER_NAME ?? "agent";
+    console.log(`
+Switched to Docker install (container: ${containerName}).`);
+  }
   printWelcome(
     dest,
     name,
@@ -41020,6 +41044,12 @@ Created ${name}/`);
     "\u2551  If you skip this step, setup WILL break and you will have to        \u2551",
     "\u2551  restart. There are no shortcuts.                                    \u2551",
     "\u2551                                                                      \u2551",
+    "\u2551  IF SAILOR IS RUNNING IN DOCKER:                                     \u2551",
+    "\u2551    \u2022 Read project files from your local filesystem \u2014 they are        \u2551",
+    "\u2551      shared via volume mount, do NOT use docker exec to read them.   \u2551",
+    "\u2551    \u2022 Prefix every sailor command with:                               \u2551",
+    "\u2551      docker exec <containerName> sailor <command>                    \u2551",
+    "\u2551                                                                      \u2551",
     "\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D",
     ""
   ].join("\n"));
@@ -41073,6 +41103,39 @@ async function updateCommand() {
   }
   const added = [];
   copyDirSyncIfMissing(templateSrc, dest, added);
+  const configPath = import_node_path9.default.join(dest, ".sail", "config.json");
+  try {
+    const config = JSON.parse(import_node_fs10.default.readFileSync(configPath, "utf-8"));
+    const newMode = process.env.SAILOR_INSTALL_MODE === "docker" ? "docker" : "local";
+    const containerName = process.env.SAILOR_CONTAINER_NAME ?? "agent";
+    if (config.installMode !== newMode) {
+      const previousMode = config.installMode;
+      const previousContainer = config.containerName;
+      config.installMode = newMode;
+      if (newMode === "docker") {
+        config.containerName = containerName;
+      } else {
+        delete config.containerName;
+      }
+      import_node_fs10.default.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}
+`, "utf-8");
+      if (previousMode === "docker" && newMode === "local") {
+        const prev = previousContainer ?? "agent";
+        console.log(`
+Switched to local install. If the Docker container is still running:`);
+        console.log(`  docker stop ${prev}`);
+        console.log(`You can restart it anytime with the standard docker run command.`);
+      } else if (newMode === "docker") {
+        console.log(`
+Switched to Docker install (container: ${containerName}).`);
+      }
+    } else if (newMode === "docker" && config.containerName !== containerName) {
+      config.containerName = containerName;
+      import_node_fs10.default.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}
+`, "utf-8");
+    }
+  } catch {
+  }
   if (removed.length === 0 && updated.length === 0 && added.length === 0) {
     console.log("Nothing to update.");
     return;
@@ -42343,6 +42406,10 @@ async function runAttach(project, channel, options) {
   if (!isAddress(options.sma, { strict: false })) throw new Error(`Invalid --sma address: ${options.sma}`);
   const sma = getAddress(options.sma);
   const store = new MandateStore();
+  if (options.address.includes(",")) {
+    await runAttachBatch(project, channel, options, sma, store);
+    return;
+  }
   const tracked = store.find(options.address);
   const rawAddress = tracked?.address ?? options.address;
   if (!isAddress(rawAddress, { strict: false })) {
@@ -42370,6 +42437,21 @@ async function runAttach(project, channel, options) {
     attached: { sma, mandate: mandateAddress, txHash }
   });
 }
+async function runAttachBatch(project, channel, options, sma, store) {
+  const json = !!options.json;
+  const permissions = [...new Set(parseAddressList(options.address, "--address"))];
+  const publicClient = publicClientFor(project);
+  announceSigningUrl(json);
+  const txHash = await attachBatchToSma(project, channel, publicClient, sma, permissions, json);
+  for (const permission of permissions) {
+    if (store.find(permission)) store.recordAttachment(permission, { sma, txHash });
+  }
+  emit(json, () => {
+  }, {
+    status: "ok",
+    attached: permissions.map((mandate2) => ({ sma, mandate: mandate2, txHash }))
+  });
+}
 async function mandateRevoke(options) {
   const project = requireProject();
   const channel = await createSigningChannel(process.cwd());
@@ -42559,6 +42641,123 @@ async function attachToSma(project, channel, publicClient, sma, mandate2, label,
   });
   return txHash;
 }
+async function attachBatchToSma(project, channel, publicClient, sma, permissions, json = false) {
+  const say = (fn) => {
+    if (!json) fn();
+  };
+  const agentSigner = await loadManagerSigner2();
+  const registered = await publicClient.readContract({
+    address: project.contracts.kernel,
+    abi: SailKernelAbi,
+    functionName: "registered",
+    args: [sma]
+  });
+  if (!registered) {
+    throw new Error(`SMA ${sma} is not registered with SailKernel; cannot register permissions.`);
+  }
+  const kernelConfig = await publicClient.readContract({
+    address: project.contracts.kernel,
+    abi: SailKernelAbi,
+    functionName: "configs",
+    args: [sma]
+  });
+  const permissionSigner = kernelConfig[0];
+  const caps = await detectKernelCapabilities(publicClient, project.contracts.kernel, {
+    chainId: project.chainId
+  });
+  if (caps.dispatchModel !== "selective") {
+    throw new Error(
+      `Batch attach requires a selective kernel, but ${project.contracts.kernel} reports dispatchModel="${caps.dispatchModel}". Attach permissions one at a time instead (sailor mandate attach --address <one> --sma ${sma}).`
+    );
+  }
+  const nonce = await publicClient.readContract({
+    address: project.contracts.kernel,
+    abi: SailKernelAbi,
+    functionName: "signerNonces",
+    args: [sma]
+  });
+  const deadline = BigInt(Math.floor(Date.now() / 1e3) + 600);
+  const typedData = buildRegisterPermissionsBatchTypedData({
+    chainId: project.chainId,
+    kernel: project.contracts.kernel,
+    account: sma,
+    permissions,
+    nonce,
+    deadline
+  });
+  say(
+    () => console.log(
+      `
+Attaching ${permissions.length} permissions in one signature \u2014 the mandate signer (${permissionSigner}) signs in the browser\u2026`
+    )
+  );
+  const response = await channel.requestSignature({
+    type: "typed-data",
+    kind: "register-permission",
+    title: `Authorize ${permissions.length} permissions`,
+    description: `Sign once to authorize ${permissions.length} permissions on your SMA. The agent submits the registration transaction and pays gas plus the registration fee.`,
+    chainId: project.chainId,
+    details: [
+      { label: "SMA", value: sma },
+      { label: "Permissions", value: String(permissions.length) },
+      { label: "Mandate signer", value: permissionSigner }
+    ],
+    typedData
+  });
+  if (response.status === "rejected") {
+    throw new Error(`User rejected mandate authorization: ${response.reason ?? "no reason given"}`);
+  }
+  if (response.status !== "signature") {
+    throw new Error(`Expected an EIP-712 signature response, got: ${response.status}`);
+  }
+  let fee = 0n;
+  for (const permission of permissions) {
+    fee += await estimatePermissionFee(publicClient, project.contracts.governance, permission);
+  }
+  const chain2 = getChainById(project.chainId);
+  const walletClient = createWalletClient({
+    account: agentSigner.viemAccount,
+    chain: chain2,
+    transport: http(getRpcUrl(project.chainId))
+  });
+  const registerData = encodeFunctionData({
+    abi: SailKernelAbi,
+    functionName: "registerPermissions",
+    args: [sma, permissions, deadline, response.signature]
+  });
+  say(() => console.log(`Submitting batch registration (agent pays gas; fee ${fee} wei)\u2026`));
+  const txHash = await walletClient.sendTransaction({
+    to: project.contracts.kernel,
+    data: registerData,
+    value: fee,
+    account: agentSigner.viemAccount,
+    chain: chain2
+  });
+  const receipt = await publicClient.waitForTransactionReceipt({ hash: txHash });
+  if (receipt.status !== "success") {
+    throw new Error(`registerPermissions reverted (tx ${txHash})`);
+  }
+  for (const permission of permissions) {
+    const present = await pollForPermission(publicClient, project.contracts.kernel, sma, permission);
+    appendActivity({
+      ts: nowIso(),
+      actor: "agent",
+      type: "permission_registered",
+      permission,
+      sma,
+      txHash,
+      chainId: project.chainId
+    });
+    say(() => {
+      if (!present) {
+        console.log(`\u26A0  ${permission} not yet visible in the permission set \u2014 verify on-chain.`);
+      } else {
+        console.log("\u2713", `${permission} present in getPermissions(${sma})`);
+      }
+    });
+  }
+  return txHash;
+}
 async function pollForPermission(publicClient, kernel, account2, permission, attempts = 6) {
   const needle = permission.toLowerCase();
   for (let i = 0; i < attempts; i++) {
@@ -45089,7 +45288,7 @@ async function uiCommand() {
   const serverBundle = import_node_path16.default.resolve(distDir, "server.cjs");
   const projectRoot = process.cwd();
   const sailDir2 = import_node_path16.default.join(projectRoot, ".sail");
-  const port = await findFreePort(projectPort(projectRoot));
+  const port = await findFreePort(process.env.PORT ? Number(process.env.PORT) : projectPort(projectRoot));
   if (!import_node_fs20.default.existsSync(serverBundle)) {
     throw new Error(`Server bundle not found at ${serverBundle}. Re-run the sailor build.`);
   }
@@ -45238,7 +45437,10 @@ var mandate = program2.command("mandate").description("Manage mandates");
 mandate.command("prepare").description("Prepare a mandate draft for review and signing in the UI (MetaMask)").action(action(mandatePrepare));
 mandate.command("sign").description("Review and confirm the permissions authorized for your SMA").option("--yes", "Skip the confirmation prompt (for non-interactive / CI use)").action(actionWith(mandateSign));
 mandate.command("deploy").description("Deploy a Foundry-compiled permission contract via the browser signing UI").option("--artifact <path>", "Path to the Foundry artifact JSON (out/<Name>.sol/<Name>.json)").option("--contract <name>", "Contract name; resolves to <out>/<name>.sol/<name>.json").option("--out <dir>", "Foundry output directory", "out").option("--name <label>", "Label to track this permission under (defaults to contract name)").option("--args <json>", `Constructor args as JSON array. Bash: '["0x..","1"]'. PowerShell: '[\\"0x..\\",\\"1\\"]'. Use --args-file to avoid quoting.`).option("--args-file <path>", "Path to a JSON file containing constructor args array (recommended on PowerShell)").option("--build", "Run `forge build` before deploying").option("--attach", "After deploy, register the permission on --sma").option("--sma <address>", "SMA to register on (required with --attach)").option("--json", "Emit machine-readable JSON").action(actionWith(mandateDeploy));
-mandate.command("attach").description("Register an already-deployed permission on an SMA (EIP-712 RegisterPermission)").requiredOption("--address <mandateOrName>", "Permission address, or a name tracked locally").requiredOption("--sma <address>", "SMA to register the permission on").option("--label <label>", "Human-readable label shown in the signing UI").option("--json", "Emit machine-readable JSON").action(actionWith(mandateAttach));
+mandate.command("attach").description("Register one or more already-deployed permissions on an SMA (EIP-712 RegisterPermission; a comma-separated list registers all in one signature)").requiredOption(
+  "--address <mandateOrName>",
+  "Permission address or locally-tracked name; or a comma-separated list of addresses to register together in one signature"
+).requiredOption("--sma <address>", "SMA to register the permission on").option("--label <label>", "Human-readable label shown in the signing UI").option("--json", "Emit machine-readable JSON").action(actionWith(mandateAttach));
 mandate.command("deploy-clone").description("[currently unavailable \u2014 no clone templates deployed on any chain; use `mandate deploy`] Deploy + register a standalone clone permission via the signing UI").requiredOption("--template <key>", "Standalone clone template key (e.g. boundedApprove)").requiredOption("--sma <address>", "SMA to deploy the clone for and register it on").option("--tokens <csv>", "Comma-separated allowed token addresses").option("--spenders <csv>", "Comma-separated allowed spender addresses").option("--max <amount>", "Max amount per tx in base units (default: uint256 max)").option("--label <label>", "Human-readable label to track this permission under").option("--json", "Emit machine-readable JSON").action(actionWith(mandateDeployClone));
 mandate.command("revoke").description("Revoke permission(s) from an SMA (EIP-712 RevokePermissions, owner-authorized)").option("--address <permissionOrName>", "Permission address, or a name tracked locally").requiredOption("--sma <address>", "Safe (SMA) to revoke the permission(s) from").option("--all", "Revoke every permission currently registered on the SMA").option("--json", "Output JSON").action(actionWith(mandateRevoke));
 mandate.command("templates").description("Show how to author your own permission contract (and any community-deployed addresses)").option("--json", "Emit machine-readable JSON").action(actionWith(mandateTemplates));

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

@@ -5,7 +5,7 @@
  * Do not edit manually — run `pnpm build` to regenerate.
  *
  * Spec version : 1.2.0
- * Generated at : 2026-06-19T07:40:34.907Z
+ * Generated at : 2026-06-20T11:04:54.885Z
  */
 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.0
- * Generated at : 2026-06-19T07:40:34.907Z
+ * Generated at : 2026-06-20T11:04:54.885Z
  */
 export const SAIL_INTELLIGENCE_BASE_URL = "https://api.sail.money";
 export const SAIL_INTELLIGENCE_DOCS_URL = "https://api.sail.money/docs";

package/scripts/clean.mjs

@@ -0,0 +1,17 @@
+import { rmSync } from "node:fs";
+
+const targets = [
+  "node_modules",
+  "packages/sdk/node_modules",
+  "packages/sdk/dist",
+  "packages/sdk/tsconfig.tsbuildinfo",
+  "packages/cli/node_modules",
+  "packages/cli/dist",
+  "packages/ui/node_modules",
+  "packages/ui/dist",
+];
+
+for (const p of targets) {
+  rmSync(p, { recursive: true, force: true });
+  console.log(`  removed ${p}`);
+}

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

@@ -1,11 +1,11 @@
 ---
 name: sail-extend
-description: Recipes for extending a live agent with notifications (Telegram, email) and a strategy-specific dashboard. Use when the agent is running and the user asks for run/transaction alerts, monitoring, or a custom view of their strategy.
+description: Recipes for extending a live agent with notifications (Telegram, email) and a strategy-specific dashboard. Use once the agent is live to offer and build run/transaction alerts, monitoring, or a custom view of the strategy — stage 5 of onboarding. Offer this proactively when the agent goes live, not only when the operator asks; the operator may opt out.
 ---
 
 # Sail extend — notifications and custom dashboards
 
-These are user-land code the assistant writes into this project on request — not Sailor features. Build them only once the agent is live.
+These are user-land code the assistant writes into this project — not Sailor features. Once the agent is live (stage 5 of onboarding), proactively offer the operator run/transaction notifications and a strategy-specific dashboard — one line on each — and build whatever they accept. Build only once the agent is live; the operator may decline, but the offer is not optional.
 
 ## Notifications
 

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

@@ -9,7 +9,16 @@ The lifecycle is an ordered set of gates. **The order is the correctness model**
 
 ## Gate 1 — Pin the strategy bounds with the user
 
-Establish, explicitly: tokens, amounts, venues, slippage, recipients. Philosophy: **every meaningful financial bound is enforced on-chain in Solidity**; only frequency/cadence lives in agent TypeScript. If a bound matters and it is not in a permission contract, it is not a bound.
+Every constraint a strategy needs is one of two kinds, and you must tell the operator which is which so they sign knowing what is enforced where:
+
+- **Safety bounds** — protect against loss or theft: amount caps, recipient allowlists, venue/router allowlists, slippage/min-out floors, LTV ceilings, and the like. These are enforced **on-chain in a permission contract, default-ON**. Dropping one requires an explicit, stated justification — never a silent omission. **If a bound matters and it is not in a permission contract, it is not a bound.**
+- **Strategy parameters** — express *how* the strategy runs, not a theft/loss surface: cadence/frequency, schedule, rebalance timing. These live in **agent logic** by nature — permissions are stateless, and these are not safety surfaces (the safety bounds hold regardless of timing). If the operator states one (e.g. a cadence), it is a required agent-side guard that must be **wired and confirmed before go-live** — not optional, never silently dropped — but do not try to push it on-chain.
+
+**Enumerate** from the operator's stated strategy *and* from what the protocol can express for the venues involved — do not work from a fixed checklist. Explain what each constraint protects against, classify it as a safety bound (on-chain) or a strategy parameter (agent-side), and say so to the operator.
+
+**Precedence.** Operator intent and the strategy's stated bounds outrank any example. If the operator asks for a constraint an example omits, include it — never let an example's shape narrow the mandate below what the operator requested.
+
+Examples are illustrations, not the supported set. Sail supports any token, venue, protocol, pool, or contract expressible as a permission — never treat an example's specific addresses as the only ones available. When the operator names something not in your examples, resolve it from authoritative sources (official docs, canonical lists, block explorers) and verify on-chain before binding a mandate to it. Caps are denominated in base units — a token decimals mismatch (USDC is 6, most ERC-20s are 18) silently mis-sizes every bound; confirm decimals on-chain before sizing caps.
 
 ## Gate 2 — Enumerate approvals and pick the execution model
 
@@ -56,6 +65,8 @@ sailor mandate deploy --contract <Name> --sma <SMA> --json   # BLOCKS — owner
 
 The owner pays gas; the deployed address is read from the receipt and tracked in `.sail/state/mandates.json`. Add `--build` to run `forge build` first.
 
+When a strategy needs several permissions, **deploy all of them first** (don't `--attach` yet). Each deploy is its own owner-signed contract-creation transaction — those cannot be combined — but attaching them is a single signature (Gate 7), so deploy the full set, then attach it in one step.
+
 Constructor args: `--args '["0xToken","1000000"]'` (JSON array, inline, bash) or `--args-file args.json` (any shell — required on PowerShell). Full per-shell quoting rules: [references/constructor-args.md](references/constructor-args.md). Values are coerced to the constructor's ABI types (uint→bigint, etc.) and the array length is validated.
 
 ## Gate 6 — Simulate against must-pass AND must-fail samples
@@ -75,10 +86,13 @@ This is an off-chain `eth_call` — no gas, no signing. It reports what `evaluat
 ## Gate 7 — Attach (authorize)
 
 ```bash
-sailor mandate attach --address <PermissionOrName> --sma <SMA> --json   # BLOCKS — owner signs RegisterPermission EIP-712 in the browser
+sailor mandate attach --address <PermissionOrName> --sma <SMA> --json              # one permission, one signature
+sailor mandate attach --address <addr1>,<addr2>,<addr3> --sma <SMA> --json          # many permissions, ONE signature
 ```
 
-Only now is the permission live. The owner (mandate signer) signs in the browser; the agent submits the registration and pays gas plus any registration fee. **Fund the agent wallet before attaching**, or this step fails with `gas required exceeds allowance`. The CLI verifies the signature came from the on-chain mandate signer — a wrong connected wallet is rejected. After confirmation it polls `getPermissions()` until the permission appears. Per-call model: attach every permission the strategy needs (bounded-approve alongside the protocol permission) in one signing session.
+Only now is the permission live. The owner (mandate signer) signs in the browser; the agent submits the registration and pays gas plus any registration fee. **Fund the agent wallet before attaching**, or this step fails with `gas required exceeds allowance`. The CLI verifies the signature came from the on-chain mandate signer — a wrong connected wallet is rejected. After confirmation it polls `getPermissions()` until the permissions appear.
+
+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>`.
 
 ## Maintenance
 

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

@@ -7,6 +7,13 @@ description: Walks the agent through setting up a new Sailor project or resuming
 
 ## Running the CLI
 
+**Determine the installation mode first** — read `.sail/config.json → installMode` before running any command:
+
+- `"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.
+
 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.
 
 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.
@@ -20,7 +27,7 @@ Stage machine keyed off `.sail/`. Read the state, enter at the right stage, neve
 | `config.json` has `chainId: null` | Stage 0 — chain not chosen; ask which chain, write it to `config.json` |
 | No `account.json` | Stage 1 — SMA not deployed |
 | `account.json` exists, `state/mandates.json` empty or absent | SMA live, no permissions — hand off to **sail-mandates** |
-| `account.json` + tracked mandates | Fully onboarded — hand off to **sail-transactions** / running |
+| `account.json` + tracked mandates | SMA live with permissions — hand off to **sail-transactions** to run. Once the agent is live, the flow is not done: **offer Extend (stage 5 — notifications + a custom dashboard) by default**, unless the operator opts out, then hand off to **sail-extend**. The end state is "stage 5 offered," not "running" |
 
 Supported chains: Ethereum (1), Base (8453), Arbitrum (42161), Unichain (130), Base Sepolia (84532), Eth Sepolia (11155111). `sailor chains --json` lists them with kernel addresses.
 

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

@@ -36,6 +36,22 @@ sailor station stop --json    # SIGTERM, verified against the recorded URL first
 
 Signing-flow commands (`mandate deploy/attach/deploy-clone/revoke`, `onboard`, `account deploy-chain`, `account rotate-signer`, `owner connect`) push requests to a running station daemon if one exists, otherwise they spin up an ephemeral in-process signing server for the duration of the command. Starting a persistent station first means the owner connects their wallet once and approves a whole sequence of requests in the same browser tab — do this before any multi-step signing flow.
 
+## Docker installation
+
+If `.sail/config.json → installMode` is `"docker"`, prefix every command with `docker exec <containerName>` (read `containerName` from the same config):
+
+```bash
+docker exec agent sailor ui start
+docker exec agent sailor ui status
+docker exec agent sailor ui stop
+
+docker exec agent sailor station start --json
+docker exec agent sailor station status --json
+docker exec agent sailor station stop --json
+```
+
+The UI always binds to port **3334** in Docker (the image sets `ENV PORT=3334`). Project files at `/workspace` are your local directory — read and write them directly from local paths; only `sailor` commands need the `docker exec` prefix.
+
 ## Troubleshooting
 
 - Command stuck "waiting"? It is blocked on a browser signature — check `GET /config` `pendingCount`, and tell the user to open the station URL and approve. Signing requests time out after 10 minutes.

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

@@ -51,7 +51,7 @@ These open a signing channel, push a request, and wait (default timeout 10 minut
 | `sailor account deploy-chain --chain <id>` | `create-sma` transaction on the target chain |
 | `sailor account rotate-signer` | Delegate rotation + mandate re-approvals |
 | `sailor mandate deploy` | `deploy-mandate` contract-creation transaction (owner pays gas) |
-| `sailor mandate attach` | `RegisterPermission` EIP-712 (off-chain signature; agent submits and pays gas) |
+| `sailor mandate attach` | `RegisterPermission` EIP-712 — one permission; a comma-separated `--address` list signs `RegisterPermissions` once for all (off-chain signature; agent submits and pays gas) |
 | `sailor mandate deploy-clone` | `RegisterPermission` EIP-712 for the predicted clone address |
 | `sailor mandate revoke` | `RevokePermissions` EIP-712 (agent submits and pays gas) |
 | `sailor owner connect` | Nothing — blocks up to 300s waiting for a wallet to connect |

package/templates/default/AGENTS.md

@@ -24,6 +24,10 @@ Ready? Say **start** and I'll open the setup interface in your browser.
 
 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.
@@ -40,6 +44,18 @@ When the user says start (or any first message), present the welcome above in fu
 
 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.
@@ -61,7 +77,7 @@ Detailed procedures live in skills. If your tooling does not auto-discover skill
 
 | Skill | Load when | Path |
 |---|---|---|
-| sail-onboarding | New project setup, or resuming a partially set-up project | `.agents/skills/sail-onboarding/SKILL.md` |
+| sail-onboarding | New project setup, or resuming a partially set-up project, documentation of sailor commands | `.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` |
@@ -82,3 +98,4 @@ Detailed procedures live in skills. If your tooling does not auto-discover skill
 - 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

package/templates/default/examples/dca/mandate.ts

@@ -9,13 +9,20 @@ import type { Address } from "@sail.money/sailor/sdk";
  * Tokens in the DCA basket.
  * ALLOWED_TOKENS[0] = USDC (input — what the agent spends)
  * ALLOWED_TOKENS[1] = WETH (output — what the agent accumulates)
+ *
+ * PLACEHOLDERS — replace with the operator's tokens for their chain. These are not
+ * "the supported tokens"; any valid ERC-20 on a supported chain works. Resolve and
+ * verify a token's address on-chain (symbol/decimals) before using it — see Gate 1 of
+ * the sail-mandates skill.
  */
 export const ALLOWED_TOKENS: Address[] = [
-  "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base  (6 decimals)
-  "0x4200000000000000000000000000000000000006", // WETH on Base  (18 decimals)
+  "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base  (6 decimals)  — placeholder
+  "0x4200000000000000000000000000000000000006", // WETH on Base  (18 decimals) — placeholder
 ];
 
 // ── Swap parameters ───────────────────────────────────────────────────────────
+// PLACEHOLDER VALUES — these encode this reference strategy, not the operator's.
+// Replace amounts, slippage, and fee tier with the operator's stated bounds.
 
 /** Amount of USDC to spend per swap (in USDC base units, 6 decimals). Default: 5 USDC. */
 export const SWAP_AMOUNT_USDC = 5_000_000n; // 5 USDC