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

package/AGENTS.md

@@ -8,11 +8,10 @@ tooling to create SMAs, register permission contracts, and run strategy agents.
 
 | Package / path | Name | Role |
 |---|---|---|
-| `packages/sdk` | `@sail/sdk` | SailorClient, LocalKeyring, kernel ABIs, EIP-712 builders, deployment registry |
+| `packages/sdk` | `@sail/sdk` | SailorClient, LocalKeyring, kernel ABIs, EIP-712 builders, deployment registry, per-chain address registry |
 | `packages/cli` | `sailor` | CLI: init, keys, account, mandate, onboard, station, ui, run, session, scan, status, owner, doctor, capabilities |
-| `packages/chains` | `@sail/chains` | Per-chain address registry (kernel, mandateFactory, governance) |
 | `packages/ui` | `sailor-ui` | Local dashboard + browser-driven onboarding wizard at localhost:3333 |
-| `templates/dca-rebalancer` | — | Default project scaffold: DCA rebalancer + Foundry workspace |
+| `templates/default` | — | Default agent starter: neutral blank scaffold + Foundry workspace + onboarding guide (AGENTS.md) |
 | `templates/custom-mandate` | — | Solidity reference: IPermission scaffold (not a project template) |
 
 ## Protocol roles
@@ -29,16 +28,15 @@ Use the user-facing terms in all CLI output, prompts, and errors. The code ident
 
 ## Dispatch model
 
-Active kernels vary by chain — verified on-chain via `DISPATCH_TYPEHASH()`:
+All six chains share the same kernel at the same CREATE2 address, verified on-chain via `DISPATCH_TYPEHASH()`:
 
-| Chain | Kernel | Model | DISPATCH_TYPEHASH |
-|---|---|---|---|
-| Base 8453 | `0x6319d3dfDDe3804ba93D65752b00c52bFb05a1ab` | **selective** | `0xbe50c539...` |
-| Base Sepolia 84532 | `0xf1D0F4C9893612627409948BAa9d82a01a373799` | **selective** | `0xbe50c539...` |
-| Arbitrum 42161 | `0x2716B12832DED0EF5688519c5Fe069EFc0374E02` | **selective** | `0xbe50c539...` |
-| Unichain 130 | `0xD985029960a9B7C2E7E38e102C448b8b8539B156` | **selective** | `0xbe50c539...` |
+| Kernel (all 6 chains) | Model | DISPATCH_TYPEHASH |
+|---|---|---|
+| `0x02ABC18B65A328de2e749F56ba79ACF2718a6659` | **selective** | `0xbe50c539...` |
+
+Supported chains: Ethereum (1), Base (8453), Arbitrum (42161), Unichain (130), Base Sepolia (84532), Eth Sepolia (11155111).
 
-All four kernels are live and bootstrapped (genesis allowlist set, `createAccount` verified working, zero fees). Unichain (130) additionally has the full permission-template suite deployed and source-verified (7 shared + 12 standalone) — it is the only chain with templates so far; the other three have core only. `packages/sdk/src/deployments.ts` is the canonical source of truth for kernel addresses, templates, and metadata.
+All six kernels are live and bootstrapped (genesis allowlist set, `createAccount` verified working, zero fees). No templates are deployed against the current kernel on any chain yet — `knownTemplates` and `standaloneTemplates` are empty for all six entries. `packages/sdk/src/deployments.ts` is the canonical source of truth for kernel addresses, templates, and metadata.
 
 **Always use `detectKernelCapabilities` for the real model** — it reads the on-chain typehash and
 overrides the static label in `deployments.ts`. The static label is a fallback for offline use only.
@@ -57,11 +55,11 @@ Pass the detected value — never hardcode the type shape.
 
 ## Active addresses
 
-All four chain records in `packages/sdk/src/deployments.ts` are live — no commented-out or pending
+All six chain records in `packages/sdk/src/deployments.ts` are live — no commented-out or pending
 addresses remain. This file is the source of truth this guide mirrors.
 
 - `packages/sdk/src/deployments.ts` — `SailDeployment` records; canonical source of truth
-- `packages/chains/src/index.ts` — `ChainConfig` per chainId; kept in sync with deployments
+- `packages/sdk/src/chains.ts` — `ChainConfig` per chainId; canonical per-chain registry
 
 ## Key files
 
@@ -79,10 +77,10 @@ addresses remain. This file is the source of truth this guide mirrors.
 
 ```bash
 pnpm install
-pnpm build        # builds all packages; dependency order: sdk → chains → cli → ui
+pnpm build        # builds all packages; dependency order: sdk → cli → ui
 ```
 
-Build order matters — `cli` imports from `sdk` and `chains`.
+Build order matters — `cli` imports from `sdk`.
 
 ## Test
 
@@ -94,6 +92,36 @@ pnpm test:ui      # playwright — requires pnpm build first
 Test fixtures live in `packages/ui/test/fixtures/` — isolated directories with pre-canned `.sail/`
 state; no real RPC needed.
 
+## RPC configuration
+
+RPC URLs are resolved by `packages/cli/src/lib/chain.ts` `getRpcUrl(chainId)` in this order (first match wins):
+
+1. `.sail/.env.local` — chain-specific var (e.g. `BASE_RPC_URL`, `ARBITRUM_RPC_URL`)
+2. `.sail/.env.local` — generic `RPC_URL`
+3. Shell environment — chain-specific var
+4. Shell environment — generic `RPC_URL`
+
+Two valid patterns for `.sail/.env.local`:
+
+```
+# Option A — single active chain
+RPC_URL=https://your-base-endpoint
+CHAIN_ID=8453
+```
+
+```
+# Option B — per-chain (multi-chain projects; omit RPC_URL if all chains have a specific var)
+CHAIN_ID=8453
+BASE_RPC_URL=https://your-base-endpoint
+ARBITRUM_RPC_URL=https://your-arbitrum-endpoint
+UNICHAIN_RPC_URL=https://your-unichain-endpoint
+ETH_MAINNET_RPC_URL=https://your-mainnet-endpoint
+BASE_SEPOLIA_RPC_URL=https://your-base-sepolia-endpoint
+SEPOLIA_RPC_URL=https://your-sepolia-endpoint
+```
+
+Per-chain vars always take precedence for their specific chain, so multi-chain projects resolve each endpoint correctly. `sailor chains --verify` uses this to check every chain that has a configured RPC.
+
 ## Conventions
 
 - `SAIL_DIR` — env var pointing to the project's `.sail/` directory (used by the UI server)

package/README.md

@@ -1,8 +1,8 @@
 # Sailor
 
-> A toolkit for building and operating Sail Protocol SMAs with AI agents.
+> The operator toolkit for Sail Protocol — SDK, CLI, and local dashboard for building and running mandated agents.
 
-Sailor is the operator layer for [Sail Protocol](../SailProtocol): the tooling an agent builder uses to create a Separately Managed Account, bound it with permissions, and run a strategy against it. It wraps the on-chain primitives — SailKernel dispatch, MandateFactory registration, EIP-712 mandate signing — behind a TypeScript SDK, a CLI, and a local dashboard. An agent is an async function that receives context and returns intended transactions; Sailor previews each through the kernel, executes the approved ones, and records what happened. It does not deploy the protocol or author new permission templates — that lives in Sail Protocol. It sits one level up: turning a deployed SailKernel into something an operator can actually drive.
+Sailor is the off-chain operator layer for [Sail Protocol](https://github.com/sail-money/SailProtocol): the tooling an operator uses to create a Separately Managed Account, register a mandate, and run a strategy agent against it. It wraps SailKernel dispatch, MandateFactory registration, and EIP-712 mandate signing behind a TypeScript SDK, a CLI, and a local dashboard. It does not deploy the protocol or author permission templates — those live in Sail Protocol. It targets already-deployed SailKernel instances and gives operators the tooling to drive them.
 
 ---
 
@@ -10,39 +10,60 @@ Sailor is the operator layer for [Sail Protocol](../SailProtocol): the tooling a
 
 | Package | Name | Role |
 |---|---|---|
-| `packages/sdk` | `@sail/sdk` | TypeScript library wrapping SailKernel and MandateFactory |
-| `packages/cli` | `sailor` | CLI for account setup, mandate signing, and agent execution |
-| `packages/chains` | `@sail/chains` | Per-chain address registry (EVM-compatible) |
-| `packages/ui` | `sailor-ui` | Local dashboard running on localhost:3333 |
-| `templates/dca-rebalancer` | — | Starter template: DCA portfolio rebalancer (default for `sailor init`) |
-| `templates/custom-mandate` | — | Solidity reference: allowlist mandate contracts (not a project template) |
+| `packages/sdk` | `@sail.money/sdk` / `@sail.money/sailor/sdk` | TypeScript library: SailorClient, EIP-712 helpers, ABIs, deployment registry, chain registry |
+| `packages/cli` | `@sail.money/sailor` | CLI for account setup, mandate signing, and agent execution |
+| `packages/ui` | `sailor-ui` | Local dashboard running at localhost:3333 |
+| `templates/default` | — | Default agent starter (neutral; what `sailor init` scaffolds) |
+| `templates/custom-mandate` | — | Solidity reference: IPermission scaffold (not a project template) |
 | `templates/lifi-permissions` | — | Solidity reference: LiFi clone permission contracts (not a project template) |
 
 ---
 
-## How it works
-
-The path from nothing to a running agent is seven steps:
+## Protocol model
+
+```mermaid
+flowchart TD
+    Owner["**Owner**<br/>holds the Safe · signs the mandate"]
+    Manager["**Manager**<br/>agent · signs dispatches"]
+    SMA["**SMA**<br/>Safe · holds assets · executes"]
+    Mandate["**Mandate**<br/>set of permission contracts"]
+    Kernel["**Sail Kernel**<br/>evaluates permission · trusted core<br/>dispatches to Safe on success"]
+
+    Owner -- "01 deploys & owns" --> SMA
+    Owner -- "02 signs mandate (EIP-712)" --> Mandate
+    Owner -- "03 appoints · instant revocation" --> Manager
+    Manager -- "04 signs dispatch (EIP-712)" --> Kernel
+    Mandate -- "05 defines bounds" --> Kernel
+    Kernel -- "06 ✓ executes · ✗ outside mandate: reverts" --> SMA
+```
 
-1. **Generate keys** — a manager key (the agent's dispatch signer) and a permissionSigner key, both generated and encrypted on disk.
-2. **Deploy SMA** — a Safe registered with SailKernel, with the manager and permissionSigner addresses set at registration.
-3. **Write a strategy** — an async `tick` function that receives a context and returns a list of intended dispatches.
-4. **Sign a mandate** — a set of registered permissions that bound what the agent can do, authorized via EIP-712 by the permission signer through MetaMask or a local key.
-5. **Dry-run** — the kernel's `previewBatch` confirms the named permission passes before anything executes on-chain.
-6. **Run the agent** — locally on a cron schedule, or via GitHub Actions on a timer.
-7. **Monitor** — the local dashboard on localhost:3333 reflects live mandate state, agent status, and activity.
+Sailor is the operator tooling that drives the Manager/dispatch and mandate-registration flows (steps 02–05).
 
 ---
 
 ## Roles
 
-Sailor operates the three roles Sail Protocol separates:
+Sail Protocol separates three authority roles. Sailor operates all of them:
 
 | Role | Authority | Held by |
 |---|---|---|
-| **Owner** | Holds the Safe. Custody anchor. | The LP (Safe owner) — same wallet as MetaMask |
-| **Permission Signer** | Signs mandate registration and revocation via EIP-712. | Same as Owner, or a separate key |
-| **Manager** | Executes dispatches within permitted bounds. Signs each dispatch. | The agent key — encrypted in `.sail/keys/manager.json` |
+| **Owner** | Holds the Safe. Custody anchor. Always self-custodial. | The LP (Safe owner) |
+| **Permission Signer** | Authorizes the mandate. Signs registration and revocation via EIP-712. | Same as Owner, or a separate signing key |
+| **Manager** | Executes dispatches within mandate bounds. Signs each dispatch. | The agent wallet — encrypted in `.sail/keys/manager.json` |
+
+---
+
+## How it works
+
+The path from nothing to a running agent follows the protocol lifecycle:
+
+1. **Deploy your SMA** — `sailor onboard --new-sma` creates the SMA on-chain. `sailor account predict` computes the deterministic address in advance. The same owner, permission signer, manager, and salt produce the same SMA address on every supported chain.
+2. **Author your permissions** — describe what the agent may do. Permission contracts encode the bounds: tokens, amounts, venues, call targets. Author them in the scaffolded Foundry workspace.
+3. **Simulate, deploy, and sign your mandate** — `sailor mandate simulate` probes a permission off-chain before authorizing it. `sailor mandate deploy --attach` deploys and registers it on-chain. `sailor mandate sign` builds and signs the registration payload against live on-chain state.
+4. **Run** — `sailor run` executes the agent locally on a schedule, or via the GitHub Actions workflow the scaffold provides.
+5. **Operate** — `sailor doctor` checks kernel health and gas balances; `sailor chains` lists supported chains and deployment addresses; `sailor session pause` instantly revokes dispatch rights without touching Safe custody.
+
+Run `npx sailor init my-agent`, open the scaffolded folder in Claude Code, Cursor, or any AI coding assistant, and say **"start"**. The `AGENTS.md` in the project guides the assistant through all five stages.
 
 ---
 
@@ -50,13 +71,24 @@ Sailor operates the three roles Sail Protocol separates:
 
 ### Start a new agent project (recommended)
 
-Open your AI coding assistant and run in its terminal:
+Create a folder, step into it, then install and init:
 
-```sh
-npx sailor init my-agent
+```bash
+# bash / zsh / macOS
+mkdir my-agent && cd my-agent && npm i @sail.money/sailor && npx sailor init
+```
+
+```powershell
+# PowerShell (Windows)
+mkdir my-agent ; cd my-agent ; npm i @sail.money/sailor ; npx sailor init
 ```
 
-Then say **"start"** — your assistant takes it from there.
+Then open the folder in your AI coding assistant and say **"start"**.
+
+> **npx shortcut** — skips the explicit install; npm downloads sailor on the fly:
+> ```sh
+> mkdir my-agent && cd my-agent && npx sailor init
+> ```
 
 ### Global CLI (for direct sailor commands)
 
@@ -71,30 +103,53 @@ sailor init my-agent
 
 Prerequisites:
 
-- Node.js 18+ (the CLI runs on 18; `pnpm install` needs Node 22+)
-- A wallet (MetaMask or Rabby)
+- Node.js 18+
+- A wallet (MetaMask, Rabby, Phantom, and more)
 - An RPC URL (e.g. Alchemy free tier)
-- A supported chain: **Base, Base Sepolia, Arbitrum, or Unichain** — these use the verified deployments bundled in `@sail/sdk`, so no `@sail/chains` entry is needed. Other chains require kernel + mandateFactory addresses in `@sail/chains` (see [State of the project](#state-of-the-project)).
+- A supported chain: **Ethereum, Base, Arbitrum, Unichain, Base Sepolia, or Eth Sepolia** — verified deployments are bundled in `@sail.money/sailor`.
+
+### Recommended — assistant-driven
 
 ```bash
-npx sailor init my-agent && cd my-agent
-npm install                    # or `pnpm install` (needs Node 22+)
+# bash / zsh / macOS
+mkdir my-agent && cd my-agent && npm i @sail.money/sailor && npx sailor init && npm install
+```
 
-# 1. Ground yourself — read-only, no gas, no wallet:
-sailor capabilities            # what you can build on this chain
-sailor doctor                  # kernel model + RPC reachability + gas balances
+```powershell
+# PowerShell (Windows)
+mkdir my-agent ; cd my-agent ; npm i @sail.money/sailor ; npx sailor init ; npm install
+```
+
+Open this folder in Claude Code, Cursor, Codex, or any AI coding assistant and say **"start"**. The scaffolded `AGENTS.md` guides the assistant through all five stages — SMA deployment, strategy definition, mandate authoring, running, and automation. No manual steps required.
 
-# 2. Set up the account in the browser wizard (choose chain, connect wallet,
-#    generate the agent key, deploy your SMA):
-sailor ui start                # open http://localhost:3333 and follow steps 1–4
+### Direct CLI reference
 
-# 3. Back in the terminal: configure .sail/.env.local, fund the agent key for gas,
-sailor mandate prepare         # draft permissions → approve in the browser
-sailor run                     # start the agent (use --once for a single tick)
+```bash
+# Discovery
+sailor chains              # list supported chains and kernel addresses
+sailor capabilities        # what you can build on this chain — read-only, no gas
+sailor doctor              # kernel model + RPC reachability + gas balances
+
+# SMA setup
+sailor account predict     # compute deterministic SMA address before deploying
+sailor onboard --new-sma   # deploy SMA and optionally attach a mandate
+
+# Mandate lifecycle
+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
+
+# Agent operation
+sailor run --once          # single tick — confirm it works before automating
+sailor run                 # start the agent (continuous)
+sailor keys export-ci      # copy encrypted agent wallet to ci-keystore.json for CI
+
+# Dashboard
+sailor ui start            # open http://localhost:3333
 ```
 
-The SMA is deployed through the browser wizard (it submits from your wallet), not a
-terminal command — see the scaffolded project's `AGENTS.md` for the full 8-step flow.
+`sailor run` writes reverted transactions to stderr as `reverted: <txHash> (gas used: N)`; successful dispatches are appended to `.sail/activity.jsonl`.
 
 ---
 
@@ -106,7 +161,7 @@ writes into the **current directory**; pass a name to create a subdirectory.
 ```bash
 sailor init                              # scaffold into cwd
 sailor init my-agent                     # create ./my-agent/ and scaffold there
-sailor init --template dca-rebalancer    # explicit (same as default)
+sailor init --template default           # explicit (same as default)
 sailor init my-agent --template <name>   # named subdirectory + specific template
 ```
 
@@ -114,7 +169,7 @@ sailor init my-agent --template <name>   # named subdirectory + specific templat
 
 | Template | Description |
 |---|---|
-| `dca-rebalancer` | Dollar-cost-averaging portfolio rebalancer. Includes a full agent loop, Foundry workspace for permission contracts, GitHub Actions cron job, and the operator guide (`AGENTS.md`). **Default.** |
+| `default` | Neutral agent starter. Includes a blank agent loop, Foundry workspace for permission contracts, GitHub Actions cron job, and the operator guide (`AGENTS.md`). For a complete worked example see `examples/dca/`. **Default.** |
 
 ### What makes a valid template
 
@@ -182,20 +237,19 @@ sailor ui stop
 
 ## Agent-driven onboarding & custom mandates
 
-For chains with a bundled Sail deployment (Base, Base Sepolia, Arbitrum, Unichain — shipped
-in `@sail/sdk`, no `@sail/chains` entry required), an agent can drive the whole
-setup through a browser **signing station**. The station is a local HTTP +
-WebSocket daemon that bridges the CLI and the owner's wallet: the agent never
-holds the owner key — it pushes signing requests, the owner approves them in the
-browser, and the agent submits the transactions it's allowed to.
+On any of the six supported chains, an agent can drive the whole setup through
+a browser **signing station**. The station is a local HTTP + WebSocket daemon
+that bridges the CLI and the owner's wallet: the agent never holds the owner
+key — it pushes signing requests, the owner approves them in the browser, and
+the agent submits the transactions it's allowed to.
 
 ```bash
-sailor keys generate                       # manager (agent) key
-sailor station start &                      # signing daemon (serves the UI)
+sailor keys generate                       # create the manager (agent) key
+sailor station start &                     # signing daemon (serves the UI)
 # owner opens the printed URL once and connects their wallet
-sailor owner connect                        # detect & persist the owner
-sailor scan                                 # discover the owner's Safes + state
-sailor onboard --new-sma                    # create an SMA + (optionally) attach a mandate
+sailor owner connect                       # detect & persist the owner
+sailor scan                                # discover the owner's Safes + state
+sailor onboard --new-sma                   # create an SMA + (optionally) attach a mandate
 ```
 
 Agents author their own permission contracts and deploy them from the scaffolded
@@ -217,35 +271,98 @@ a `RegisterPermission` EIP-712 message, then the agent submits
 `--json` for headless agent use; set `SAIL_PASSPHRASE` to unlock the manager key
 non-interactively.
 
+`sailor mandate sign` reconciles against the live on-chain `getPermissions()` call
+before building the mandate payload — permissions revoked on-chain are excluded even
+if they remain in the local `.sail/state/mandates.json` (which is an append-only
+historical record and is never modified by the reconciliation).
+
+### GitHub Actions CI
+
+The scaffolded `.github/workflows/agent-tick.yml` runs `sailor run --once` on a
+cron schedule using `npm ci` (no pnpm required). Setup:
+
+1. `sailor keys export-ci` — copies the encrypted agent wallet to `ci-keystore.json`
+   in the project root and allowlists it in `.gitignore`. The geth v3 keystore is
+   safe to commit; the raw private key is never exposed.
+2. Commit `ci-keystore.json`, `.sail/account.json`, and `.sail/mandate.json`.
+3. Add two repository secrets (Settings → Secrets → Actions):
+   - `SAIL_PASSPHRASE` — the passphrase that encrypts the agent wallet
+   - `RPC_URL` — your RPC endpoint
+
+The workflow copies `ci-keystore.json` to `.sail/keys/manager.json`, then calls
+`npx sailor run --once` with `SAIL_PASSPHRASE` set so the key is unlocked
+non-interactively. No private key ever appears in the workflow file or in secrets.
+
 ---
 
-## Architecture
+## Packages
+
+Sailor ships as a **single npm package** — the SDK is bundled inside it and exposed via a subpath export:
+
+| Package | Contents |
+|---|---|
+| `@sail.money/sailor` | CLI binary, UI server, templates, examples, and SDK |
+
+The SDK is available as a subpath export for use in agent code:
+
+```ts
+import type { Agent, AgentContext, Dispatch } from '@sail.money/sailor/sdk'
+```
+
+The SDK is also published separately as `@sail.money/sdk` for projects that consume it independently of the CLI.
+
+### npm (`publish-npm.yml`)
+
+Published to the public npm registry under the `@sail.money` scope.
 
+| Trigger | Package | Version | dist-tag |
+|---|---|---|---|
+| Tag push (`v*`) | `@sail.money/sailor` | `0.1.0` | `latest` |
+| Manual dispatch | `@dev.sail.money/sailor` | `0.1.0-42` | `dev` |
+
+```bash
+npm install @sail.money/sailor                # latest stable (tag push)
+```
+
+For dev builds, the package name changes scope to `@dev.sail.money`. Use an alias so your import paths stay the same:
+
+```bash
+npm install "@sail.money/sailor@npm:@dev.sail.money/sailor@dev"
+```
+
+This installs the latest dev build and makes it available as `@sail.money/sailor` locally — `@sail.money/sailor/sdk` imports continue to work unchanged.
+
+### GitHub Packages (`publish.yml`)
+
+Published to GitHub Packages under the `@sail-money` scope for internal testing — no public npm registry required.
+
+| Trigger | Package | dist-tag |
+|---|---|---|
+| Merge to `main` | `@sail-money/sailor` | `latest` |
+| Manual dispatch | `@sail-money/sailor-dev` | `dev` |
+
+Both builds require an alias since the package scope differs from `@sail.money`:
+
+```bash
+npm install "@sail.money/sailor@npm:@sail-money/sailor@latest" --registry https://npm.pkg.github.com
+npm install "@sail.money/sailor@npm:@sail-money/sailor-dev@dev" --registry https://npm.pkg.github.com
+```
+
+Or pin in `package.json`:
+
+```json
+"dependencies": {
+  "@sail.money/sailor": "npm:@sail-money/sailor@latest"
+}
 ```
-   ┌────────────────────┐                          ┌────────────────────┐
-   │  Permission Signer │                          │    Manager/Agent   │
-   │  MetaMask / local  │                          │ .sail/keys/manager │
-   └─────────┬──────────┘                          └─────────┬──────────┘
-             │                                               │
-             │ EIP-712 mandate                               │ dispatch
-             ▼                                               ▼
-   ┌─────────────────────────────────────────────────────────────────────┐
-   │                            SailKernel                               │
-   │                          (Sail Protocol)                            │
-   └─────────┬───────────────────────┬───────────────────────┬───────────┘
-             │                       │                       │
-             │ registration          │ execution             │ evaluation
-             ▼                       ▼                       ▼
-   ┌────────────────────┐  ┌────────────────────┐  ┌────────────────────┐
-   │   MandateFactory   │  │         Safe       │  │     Permissions    │
-   │  (register perms)  │  │      (custody)     │  │  (named, per-call) │
-   └────────────────────┘  └────────────────────┘  └────────────────────┘
-
-          sailor CLI / @sail/sdk drive both signing paths above.
-          .sail/ (account · mandate · activity) ──→ sailor-ui (localhost:3333)
+
+```json
+"dependencies": {
+  "@sail.money/sailor": "npm:@sail-money/sailor-dev@dev"
+}
 ```
 
-The CLI and SDK sit between the operator and SailKernel: they build the EIP-712 payloads, submit dispatches, and read kernel state via viem. The permission signer authorizes the mandate — registration runs through MandateFactory — while the manager key signs each dispatch the kernel evaluates against a named permission before executing it through the Safe. All local state — the deployed account, the signed mandate, and the agent's activity log — lives under `.sail/` on disk, which the dashboard reads through a small local server. Sailor never holds the Owner key and runs no hosted backend; the wallet talks to the chain directly.
+Either way, `@sail.money/sailor/sdk` imports work unchanged.
 
 ---
 
@@ -255,74 +372,48 @@ The CLI and SDK sit between the operator and SailKernel: they build the EIP-712
 - The Owner key controls the Safe and is never read by Sailor. Mandate signing requires a deliberate action by the permission signer.
 - The manager key is encrypted on disk using geth keystore v3 (scrypt + aes-128-ctr) and is never transmitted.
 - The session can be paused instantly via `sailor session pause` or the dashboard stop button; this does not affect Safe custody.
+- All addresses passed to the CLI are normalized with `getAddress()` (EIP-55 checksum). Mixed-case or lowercase inputs are accepted and canonicalized before any on-chain call or state write.
 
 ---
 
 ## State of the project
 
-Sailor is functional and published as [`@sail.money/sailor`](https://www.npmjs.com/package/@sail.money/sailor) on npm (v0.0.1). The SDK, CLI, keystore, mandate flows, agent runner, and dashboard are implemented and have been exercised end to end against Base Sepolia.
+Sailor is functional and published as [`@sail.money/sailor`](https://www.npmjs.com/package/@sail.money/sailor) on npm (v0.1.0). The SDK, CLI, keystore, mandate flows, agent runner, and dashboard are implemented and have been exercised end to end.
+
+The Sail Protocol trusted core is deployed on six chains — Ethereum, Base, Arbitrum, Unichain, Base Sepolia, and Eth Sepolia — via CREATE2, with every core contract at the same address on every chain. All six run the selective dispatch model with zero fees and are bootstrapped with a genesis allowlist so `createAccount` is usable immediately. These deployments are under an ongoing external audit by [Octane Security](https://octane.security) and are not final — do not use them with funds you are not prepared to lose.
 
-The Sail Protocol trusted core is deployed on Base, Base Sepolia, Arbitrum, and Unichain as staging deployments for testing ahead of a formal launch. All four run the selective dispatch model, with verified deployments bundled in `@sail/sdk`. These deployments are under an ongoing external audit by [Octane Security](https://octane.security) and are not final — do not use them with funds you are not prepared to lose. Permission templates are not yet deployed against the Base, Arbitrum, and Base Sepolia kernels; **Unichain** ships the full template suite (7 shared + 12 standalone, source-verified) and its template registries in `@sail/sdk` are populated. `@sail/chains` and the remaining template registries will be filled in as templates are deployed on the other chains and at mainnet launch.
+Permission templates have not yet been deployed against the current kernel on any chain; `knownTemplates` and `standaloneTemplates` are empty for all six chains in `packages/sdk/src/deployments.ts` and will be populated as templates are deployed and verified against the new kernel.
 
 ---
 
 ## Deployments
 
-The Sail Protocol trusted core is live on the following chains as **staging deployments** ahead of a formal launch, bundled in `@sail/sdk`. All run the selective dispatch model with zero fees. Permission templates are not yet deployed against the Base, Arbitrum, and Base Sepolia kernels; **Unichain** ships the full template suite (7 shared + 12 standalone, source-verified on uniscan.xyz) and has its onboarding allowlists seeded at genesis.
+All core contracts are deployed at the same address on every supported chain via CREATE2 (commit `1199b33`, 2026-06-09). An SMA created with the same owner, permission signer, manager, fee policy, and salt has the same address on every supported chain.
 
-### Base (8453)
+### Core addresses (identical on all 6 chains)
 
 | Contract | Address |
 |---|---|
-| SailKernel | `0x6319d3dfDDe3804ba93D65752b00c52bFb05a1ab` |
-| SailGovernance | `0x7E897D919872b1587577617ffFC42113679d0C50` |
-| Timelock | `0x8eC3Ca951E193C6E3713A70022454d7A1f083281` |
-| PermissionFactory | `0x7724EACd97C8601d5AC244Aadbf76ad87353Ff31` |
-| StandardFeePolicy | `0x65850a8D5050aeAade68289ff96c4F119a24B82e` |
-| SafeModuleEnabler | `0xC84EdE78f93291A1fab19F51c4c7e938AB302Edf` |
+| SailKernel | `0x02ABC18B65A328de2e749F56ba79ACF2718a6659` |
+| SailGovernance | `0x7A478118715791728BDE3bc7A4D7ECfdEB89C6EC` |
+| TimelockController | `0xE48Ba8DB6d748adafD13155c3590f62e58a77f56` |
+| MandateFactory | `0x14EDd6c2a56EfC0d71E215ab13094B9AF90543d2` |
+| StandardFeePolicy | `0xe7B5901b839cFFDEd9D4108A22712C8BfdA1D80D` |
+| SafeModuleEnabler | `0x7897Cb53a4be4a2eaAf46D60573C4Fd83b33fE1F` |
 | Treasury | `0xB01dCE443d052e44b7D13726c0EC9fFB7f5815B6` |
 
-### Arbitrum (42161)
+These addresses are bundled in `@sail.money/sailor` and exposed via `getSailDeployment(chainId)` in the SDK. The Protocol repository is the canonical source of truth for deployment details — see [deployments/addresses.md](https://github.com/sail-money/Protocol/blob/main/deployments/addresses.md).
 
-| Contract | Address |
-|---|---|
-| SailKernel | `0x2716B12832DED0EF5688519c5Fe069EFc0374E02` |
-| SailGovernance | `0xd6AbB7A1036ADc7958Abffec9Da03450c5a2Ec8e` |
-| Timelock | `0x114CB7110C780f7E3a6093AfE0B52463a569857C` |
-| PermissionFactory | `0x23681A8A4C9819D8EaB37E46B858da6F3c85E683` |
-| StandardFeePolicy | `0xAdfB986D48480bC67a7cF3751d30599161632e0D` |
-| SafeModuleEnabler | `0xabe2a6D03F592BC602cA1dBDCD885ba2493274f9` |
-| Treasury | `0xB01dCE443d052e44b7D13726c0EC9fFB7f5815B6` |
-
-### Base Sepolia (84532)
+### Supported chains
 
-| Contract | Address |
+| Chain | Chain ID |
 |---|---|
-| SailKernel | `0xf1D0F4C9893612627409948BAa9d82a01a373799` |
-| SailGovernance | `0xEaD44bC6999E7b00b9b2E11c1660248DC2a30993` |
-| Timelock | `0x97B863e392C9859336788D5Ec454527d33C95B74` |
-| PermissionFactory | `0xdfF6a2272F667cDf78Af4681b9c88A219998db95` |
-| StandardFeePolicy | `0x05570F7973b46Eb9Ed4518422891EFC26BD58b97` |
-| SafeModuleEnabler | `0xB2C2B52d94412e3472C9fb2B52186eA12a935869` |
-| Treasury | `0xB01dCE443d052e44b7D13726c0EC9fFB7f5815B6` |
-
-### Unichain (130)
-
-First chain to ship the full permission-template suite (7 shared + 12 standalone, source-verified on [uniscan.xyz](https://uniscan.xyz)). Genesis allowlist bootstrap — onboarding usable without the 48h timelock.
-
-| Contract | Address |
-|---|---|
-| SailKernel | `0xD985029960a9B7C2E7E38e102C448b8b8539B156` |
-| SailGovernance | `0xAb5C90ECfF2763f6f20f8E553E3b8778dD9C349A` |
-| Timelock | `0xd44FbBB37f01e235E0EE5386948F216d36D0CEf2` |
-| PermissionFactory | `0x8edDb62Aa49CeB837abf2653be2d93Ad9Fe6777D` |
-| StandardFeePolicy | `0x7bBA8BE3c01c972757aA4a230A00D58aB600A1F1` |
-| SafeModuleEnabler | `0xFE9227A9F2baf704060c604466df354a5A137b9B` |
-| Treasury | `0xB01dCE443d052e44b7D13726c0EC9fFB7f5815B6` |
-
-The 19 template addresses are in `@sail/sdk` (`knownTemplates` + `standaloneTemplates` for chain 130).
-
-Addresses are sourced from `@sail/sdk` (`packages/sdk/src/deployments.ts`), the canonical registry.
+| Ethereum | 1 |
+| Base | 8453 |
+| Arbitrum | 42161 |
+| Unichain | 130 |
+| Base Sepolia | 84532 |
+| Eth Sepolia | 11155111 |
 
 ---