shll-skills 1.3.0 → 2.0.0

package/README.md

@@ -13,13 +13,17 @@ npm install -g shll-skills
 ## Quick Start
 
 ```bash
-export RUNNER_PRIVATE_KEY="0x..."
+# 1. Generate an operator wallet (hot wallet for AI)
+shll-run generate-wallet
+# -> Outputs address + private key
 
-# 1. One-click onboarding: rent agent + authorize + fund vault
-shll-run init --listing-id 0xABC...DEF --days 30 --fund 0.5
-# -> Agent #5 is ready!
+export RUNNER_PRIVATE_KEY="0x...(operator key)..."
 
-# 2. Trade
+# 2. Get setup instructions (user completes on shll.run with their OWN wallet)
+shll-run setup-guide --listing-id 0xABC...DEF --days 30
+# -> Outputs shll.run link for rent + authorize + fund
+
+# 3. After setup, trade with your token-id
 shll-run swap --from BNB --to USDC --amount 0.1 --token-id 5
 ```
 
@@ -77,18 +81,29 @@ AI Agent -> CLI command -> PolicyClient.validate() -> PolicyGuard (on-chain) ->
 3. If approved, `AgentNFA.execute()` routes through PolicyGuard -> vault
 4. PolicyGuard enforces: spending limits, cooldowns, DEX whitelist, receiver guard
 
-## Security
+## Security: Dual-Wallet Architecture
+
+SHLL enforces **separation of owner and operator wallets**:
+
+| | Owner Wallet | Operator Wallet (RUNNER_PRIVATE_KEY) |
+|---|---|---|
+| **Who holds it** | User (MetaMask/hardware) | AI agent |
+| **Can trade** | — | ✅ Within PolicyGuard limits |
+| **Can withdraw vault** | ✅ | ❌ |
+| **Can transfer NFT** | ✅ | ❌ |
+| **Risk if leaked** | 🚨 Full vault access | ⚠️ Limited to policy-allowed trades |
 
-- **On-chain enforcement** — PolicyGuard validates every transaction, not the AI
-- **Vault isolation** — Operator key cannot directly access vault funds
-- **Renter-only config** — Risk limits can only be tightened, never loosened
-- **Safe by default** — Unknown selectors, targets, or recipients are rejected
+**Additional on-chain enforcement:**
+- PolicyGuard validates every transaction, not the AI
+- Vault isolation — operator key cannot directly access vault funds
+- Risk limits can only be tightened, never loosened
+- Unknown selectors, targets, or recipients are rejected
 
 ## Environment Variables
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `RUNNER_PRIVATE_KEY` | Yes | Gas-paying wallet key (~$1 BNB is enough) |
+| `RUNNER_PRIVATE_KEY` | Yes | Operator wallet key (hot wallet, ~$1 BNB for gas) |
 | `RPC_URL` | No | BSC RPC (default: public endpoint) |
 | `NFA_ADDRESS` | No | AgentNFA contract override |
 | `GUARD_ADDRESS` | No | PolicyGuard contract override |

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: shll-run
 description: Execute DeFi transactions on BSC via SHLL AgentNFA. The AI handles all commands — users only need to chat.
-version: 3.2.0
+version: 4.0.0
 author: SHLL Team
 website: https://shll.run
 twitter: https://twitter.com/shllrun
@@ -16,32 +16,56 @@ You are an AI agent with access to SHLL DeFi tools on BSC. **The user should nev
 
 ---
 
+## ⛔ SAFETY RULES (MANDATORY)
+
+These rules are **non-negotiable**. Violating any of them is a critical failure.
+
+1. **Token-ID must come from the user.** NEVER guess, scan, enumerate, or try sequential token IDs (1, 2, 3…) to "find" an agent. Only use a token-id the user explicitly provides in this conversation.
+2. **Do NOT operate on token IDs the user has not mentioned.** Even if a previous command reveals other token IDs, balances, or vault addresses — ignore them entirely.
+3. **Confirm before every write operation.** Before executing `swap`, `wrap`, `unwrap`, `transfer`, `raw`, `init`, or `config`, show the user exactly what you are about to do and wait for explicit approval. Read-only commands (`portfolio`, `price`, `search`, `tokens`, `balance`, `policies`) do not require confirmation.
+4. **One agent per conversation.** Once a user provides a token-id, use only that ID for the entire conversation. If they want to switch, they must explicitly say so.
+5. **Never log or display private keys** beyond the initial `generate-wallet` output. If the user asks you to repeat it, remind them to check their saved copy.
+6. **Do not infer trading intent.** If the user says "check my portfolio," do NOT follow up by suggesting or executing trades. Only trade when the user explicitly asks.
+
+---
+
+## 🔐 SECURITY MODEL: Dual-Wallet Architecture
+
+SHLL uses **two separate wallets** for maximum security:
+
+| | Owner Wallet (Cold) | Operator Wallet (Hot) |
+|---|---|---|
+| **Who holds it** | User (MetaMask, hardware wallet) | AI agent (RUNNER_PRIVATE_KEY) |
+| **Can trade** | — | ✅ Within PolicyGuard limits |
+| **Can withdraw vault** | ✅ | ❌ |
+| **Can transfer NFT** | ✅ | ❌ |
+| **Can change operator** | ✅ | ❌ |
+| **Risk if leaked** | 🚨 Full vault access | ⚠️ Limited to policy-allowed trades |
+
+**Critical rule: You (the AI) ONLY have access to the operator wallet. You must NEVER ask for, store, or handle the user's owner wallet key. All owner-level operations (rent, fund, withdraw) are done by the user on https://shll.run.**
+
+---
+
 ## CONVERSATION FLOW: New User Onboarding
 
 When a user wants to use SHLL for the first time, follow this decision tree:
 
-### Step 1: Check if they have a gas wallet
+### Step 1: Generate operator wallet
 
-Ask: *"Do you already have a wallet set up for SHLL? (a RUNNER_PRIVATE_KEY)"*
+Ask: *"Do you already have an operator wallet set up for SHLL? (a RUNNER_PRIVATE_KEY)"*
 
-**If NO** -> Generate one for them:
+**If NO** → Generate one:
 ```bash
 shll-run generate-wallet
 ```
-This outputs:
-```json
-{"status":"success","address":"0xABC...","privateKey":"0x123...","note":"..."}
-```
 
 Tell the user:
-- *"I've generated a new wallet for you."*
+- *"I've generated an operator wallet for you."*
 - *"Address: `0xABC...` — send about $1 of BNB here for gas fees."*
-- *"Private key: `0x123...` — save this somewhere safe, you'll need it."*
-- *"This wallet ONLY pays gas fees (~$0.01 per transaction). Your trading funds are stored in a separate secure vault on-chain that this key cannot access directly."*
-
-Then wait for them to fund it.
+- *"Private key: `0x123...` — save this securely, then set it as RUNNER_PRIVATE_KEY."*
+- *"This is an OPERATOR wallet — it can only trade within safety limits. It CANNOT withdraw your vault funds or touch your agent ownership."*
 
-**If YES** -> Ask them to provide it, then set it:
+**If YES** → Set it:
 ```bash
 export RUNNER_PRIVATE_KEY="0x..."
 ```
@@ -53,26 +77,28 @@ shll-run balance
 ```
 
 If `sufficient: false`, tell the user:
-*"Your gas wallet needs more BNB. Please send at least $1 of BNB to `<address>`. You can buy BNB on Binance, OKX, or any exchange and withdraw to this address on BSC (BEP-20)."*
+*"Your operator wallet needs more BNB for gas fees. Send at least $1 of BNB to `<address>`. You can buy BNB on Binance, OKX, or any exchange and withdraw to BSC (BEP-20)."*
 
-Wait until balance is sufficient before proceeding.
+Wait until balance is sufficient.
 
-### Step 3: Check if they have a token-id (Agent)
+### Step 3: Set up agent (user does this themselves)
 
 Ask: *"Do you already have a SHLL Agent? (a token-id number)"*
 
-**If NO** -> Create one:
+**If NO** → Guide them to set up via shll.run:
 ```bash
-shll-run init --listing-id <LISTING_ID> --days 30 --fund 0.1
+shll-run setup-guide --listing-id <LISTING_ID> --days 30
 ```
 
-**About `listing-id`:** This is the SHLL Agent template ID from the marketplace. If the user doesn't know it, tell them:
-*"You can find available Agent templates at https://shll.run. Each template has a listing-id. Tell me the listing-id and I'll set up your Agent."*
+This outputs a link to https://shll.run/setup with pre-filled parameters. Tell the user:
+1. *"Open the setup link in your browser."*
+2. *"Connect YOUR personal wallet (MetaMask, WalletConnect) — this becomes the owner wallet."*
+3. *"Follow the steps to: rent an agent → authorize the operator wallet → fund the vault."*
+4. *"When done, tell me your token-id number."*
 
-After init succeeds, tell the user:
-*"Your Agent #<tokenId> is ready! Your trading vault is at `<vault>`. I've funded it with 0.1 BNB. You can start trading now."*
+**⚠️ NEVER use `init` for new users.** The `init` command is deprecated because it uses the same key for owner and operator, which is a security risk.
 
-**If YES** -> Verify it works:
+**If YES** → Verify:
 ```bash
 shll-run portfolio -k <ID>
 ```
@@ -89,16 +115,13 @@ The user is now set up. They can ask you things like:
 
 ## COMMAND REFERENCE
 
-### Wallet Setup (no private key needed)
+### Wallet & Setup
 | Command | What it does |
 |---------|-------------|
-| `shll-run generate-wallet` | Create a new gas wallet (address + private key) |
-| `shll-run balance` | Check gas wallet BNB balance |
-
-### Setup (one-time)
-| Command | What it does |
-|---------|-------------|
-| `shll-run init --listing-id <ID> --days <N> [--fund <BNB>]` | Rent agent + authorize + fund vault |
+| `shll-run generate-wallet` | Create a new operator wallet (address + private key) |
+| `shll-run balance` | Check operator wallet BNB balance |
+| `shll-run setup-guide -l <LISTING> -d <DAYS>` | Output setup instructions + shll.run link for secure onboarding |
+| ~~`shll-run init`~~ | **DEPRECATED** — insecure single-wallet mode |
 
 ### Trading
 | Command | What it does |
@@ -130,10 +153,13 @@ The user is now set up. They can ask you things like:
 ## HOW TO EXPLAIN THINGS TO USERS
 
 ### "What is RUNNER_PRIVATE_KEY?"
-*"It's a gas-paying wallet. Think of it like a prepaid card that only pays small transaction fees (~$0.01 each). It does NOT hold your trading money. Your trading funds are in a secure on-chain vault that this key can't directly access. You only need about $1 of BNB in it."*
+*"It's your operator wallet — a hot wallet that the AI uses to execute trades within safety limits. Think of it like a company credit card with a spending cap. It can NOT withdraw funds from your vault or transfer your agent ownership. You only need ~$1 of BNB in it for gas fees."*
+
+### "Why do I need two wallets?"
+*"Security. Your personal wallet (owner) controls high-risk operations like withdrawing vault funds. The operator wallet can only trade within PolicyGuard limits. Even if the operator key is compromised, an attacker can NOT drain your vault — they can only make trades within the safety rules you've set. Your owner wallet stays offline and safe."*
 
 ### "Is my money safe?"
-*"Yes. All trading funds are in an on-chain vault protected by PolicyGuard, a smart contract that enforces spending limits, cooldowns, and whitelisted DEXs. Even if the AI makes a mistake, the smart contract will reject unsafe transactions. The gas wallet key cannot withdraw from the vault."*
+*"Yes, on multiple levels. First, the operator wallet (which the AI uses) cannot withdraw vault funds — only your owner wallet can. Second, all trades go through PolicyGuard, which enforces spending limits, cooldowns, and DEX whitelists. Even if someone got the operator key, your money is protected by on-chain smart contract rules."*
 
 ### "What are policies?"
 *"Policies are on-chain safety rules: how much you can spend per transaction, how often you can trade, which DEXs are allowed, etc. You can tighten these rules but never loosen them beyond the template ceiling."*

package/dist/index.js

@@ -858,9 +858,16 @@ tokensCmd.action(() => {
   }));
   output({ status: "success", tokens });
 });
-var initCmd = new import_commander.Command("init").description("One-click setup: rent an Agent, authorize self as operator, and fund the vault").requiredOption("-l, --listing-id <bytes32>", "Template listing ID (bytes32 hex)").requiredOption("-d, --days <number>", "Number of days to rent").option("-f, --fund <bnb>", "BNB to deposit into vault (human-readable, e.g. 0.1)", "0").option("-r, --rpc <url>", "BSC RPC URL", DEFAULT_RPC).option("--listing-manager <address>", "ListingManagerV2 address", DEFAULT_LISTING_MANAGER).option("--nfa-address <address>", "AgentNFA contract address", DEFAULT_NFA);
+var initCmd = new import_commander.Command("init").description("[DEPRECATED] One-click setup \u2014 uses same key as owner AND operator. Use setup-guide instead.").requiredOption("-l, --listing-id <bytes32>", "Template listing ID (bytes32 hex)").requiredOption("-d, --days <number>", "Number of days to rent").option("-f, --fund <bnb>", "BNB to deposit into vault (human-readable, e.g. 0.1)", "0").option("--i-understand-the-risk", "Acknowledge the security risk of using same key for owner and operator").option("-r, --rpc <url>", "BSC RPC URL", DEFAULT_RPC).option("--listing-manager <address>", "ListingManagerV2 address", DEFAULT_LISTING_MANAGER).option("--nfa-address <address>", "AgentNFA contract address", DEFAULT_NFA);
 initCmd.action(async (opts) => {
   try {
+    if (!opts.iUnderstandTheRisk) {
+      output({
+        status: "error",
+        message: "\u26A0\uFE0F  DEPRECATED: 'init' uses the same private key as both owner AND operator. If this key is leaked (e.g. via AI prompt injection), an attacker can withdraw ALL vault funds. Use 'setup-guide' instead for a secure dual-wallet setup. If you understand the risk and still want to proceed, add --i-understand-the-risk."
+      });
+      process.exit(1);
+    }
     if (!process.env.RUNNER_PRIVATE_KEY) {
       output({ status: "error", message: "RUNNER_PRIVATE_KEY environment variable is missing" });
       process.exit(1);
@@ -1459,14 +1466,125 @@ configCmd.action(async (opts) => {
     process.exit(1);
   }
 });
-var genWalletCmd = new import_commander.Command("generate-wallet").description("Generate a new BSC wallet (address + private key)").action(() => {
+var setupGuideCmd = new import_commander.Command("setup-guide").description("Output step-by-step instructions for secure dual-wallet agent setup").requiredOption("-l, --listing-id <bytes32>", "Template listing ID (bytes32 hex)").requiredOption("-d, --days <number>", "Number of days to rent").option("-r, --rpc <url>", "BSC RPC URL", DEFAULT_RPC).option("--listing-manager <address>", "ListingManagerV2 address", DEFAULT_LISTING_MANAGER).option("--nfa-address <address>", "AgentNFA contract address", DEFAULT_NFA);
+setupGuideCmd.action(async (opts) => {
+  try {
+    const pk = process.env.RUNNER_PRIVATE_KEY;
+    let operatorAddress;
+    if (pk) {
+      const account = (0, import_accounts2.privateKeyToAccount)(toHex(pk));
+      operatorAddress = account.address;
+    } else {
+      output({
+        status: "error",
+        message: "RUNNER_PRIVATE_KEY not set. Run 'generate-wallet' first to create an operator wallet, then set RUNNER_PRIVATE_KEY."
+      });
+      process.exit(1);
+      return;
+    }
+    const rpcUrl = opts.rpc || DEFAULT_RPC;
+    const listingManagerAddr = toHex(opts.listingManager || DEFAULT_LISTING_MANAGER);
+    const nfaAddr = toHex(opts.nfaAddress || DEFAULT_NFA);
+    const listingId = opts.listingId;
+    const daysToRent = Number(opts.days);
+    const publicClient = (0, import_viem2.createPublicClient)({ chain: import_chains2.bsc, transport: (0, import_viem2.http)(rpcUrl) });
+    let rentCost = "unknown";
+    let priceInfo = "";
+    try {
+      const listing = await publicClient.readContract({
+        address: listingManagerAddr,
+        abi: LISTING_MANAGER_ABI,
+        functionName: "listings",
+        args: [listingId]
+      });
+      const [, , , pricePerDay, minDays, active] = listing;
+      if (!active) {
+        output({ status: "error", message: "Listing is not active" });
+        process.exit(1);
+      }
+      if (daysToRent < minDays) {
+        output({ status: "error", message: `Minimum rental is ${minDays} days, you requested ${daysToRent}` });
+        process.exit(1);
+      }
+      const totalRent = BigInt(pricePerDay) * BigInt(daysToRent);
+      rentCost = `${(Number(totalRent) / 1e18).toFixed(6)} BNB`;
+      priceInfo = ` (${totalRent.toString()} wei)`;
+    } catch {
+      rentCost = "unable to query \u2014 check listing-id";
+    }
+    const expiryTimestamp = Math.floor(Date.now() / 1e3) + daysToRent * 86400;
+    const setupUrl = `https://shll.run/setup?operator=${operatorAddress}&listing=${encodeURIComponent(listingId)}&days=${daysToRent}`;
+    output({
+      status: "guide",
+      securityModel: "DUAL-WALLET: Your wallet (owner) stays offline. AI only uses the operator wallet, which CANNOT withdraw vault funds.",
+      operatorAddress,
+      setupUrl,
+      rentCost: `${rentCost}${priceInfo}`,
+      steps: [
+        {
+          step: 1,
+          title: "Open SHLL Setup Page",
+          action: `Open ${setupUrl} in your browser`,
+          note: "Connect YOUR wallet (MetaMask/WalletConnect). This is your owner wallet \u2014 keep it safe and offline after setup."
+        },
+        {
+          step: 2,
+          title: "Rent Agent",
+          action: "Click 'Rent Agent' and confirm the transaction",
+          fallback: {
+            method: "BscScan (manual)",
+            contract: listingManagerAddr,
+            function: "rentToMintWithParams(bytes32,uint32,uint32,uint16,bytes)",
+            args: [listingId, daysToRent, 1, 1, "0x01"],
+            value: rentCost
+          }
+        },
+        {
+          step: 3,
+          title: "Authorize Operator",
+          action: "Click 'Authorize Operator' \u2014 this gives the AI wallet permission to trade within PolicyGuard safety limits",
+          note: `Operator address: ${operatorAddress}`,
+          fallback: {
+            method: "BscScan (manual)",
+            contract: nfaAddr,
+            function: "setOperator(uint256,address,uint64)",
+            args: ["<tokenId from step 2>", operatorAddress, expiryTimestamp]
+          }
+        },
+        {
+          step: 4,
+          title: "Fund Vault (optional)",
+          action: "Deposit BNB into the vault for trading",
+          fallback: {
+            method: "BscScan (manual)",
+            contract: nfaAddr,
+            function: "fundAgent(uint256)",
+            args: ["<tokenId>"],
+            value: "amount of BNB to deposit"
+          }
+        },
+        {
+          step: 5,
+          title: "Tell AI your token-id",
+          action: "Come back and tell the AI your token-id number. The AI will verify your portfolio and you're ready to trade."
+        }
+      ]
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    output({ status: "error", message });
+    process.exit(1);
+  }
+});
+var genWalletCmd = new import_commander.Command("generate-wallet").description("Generate a new operator wallet (address + private key) for AI to use").action(() => {
   const pk = (0, import_accounts2.generatePrivateKey)();
   const account = (0, import_accounts2.privateKeyToAccount)(pk);
   output({
     status: "success",
     address: account.address,
     privateKey: pk,
-    note: "SAVE THIS PRIVATE KEY SECURELY. This wallet is for paying gas fees (~$0.01/tx). Send ~$1 of BNB to the address above, then set RUNNER_PRIVATE_KEY to the privateKey value."
+    note: "SAVE THIS PRIVATE KEY SECURELY. This is the OPERATOR wallet \u2014 it can only trade within PolicyGuard limits. It CANNOT withdraw vault funds or transfer your Agent NFT. Send ~$1 of BNB here for gas fees, then set RUNNER_PRIVATE_KEY to this privateKey value.",
+    securityReminder: "Use a SEPARATE wallet (MetaMask, hardware wallet) as the owner to rent the agent and fund the vault. Run 'setup-guide' for step-by-step instructions."
   });
 });
 var balanceCmd = new import_commander.Command("balance").description("Check BNB balance of the gas-paying wallet (RUNNER_PRIVATE_KEY)").option("-r, --rpc <url>", "BSC RPC URL", DEFAULT_RPC).action(async (opts) => {
@@ -1507,6 +1625,7 @@ program.addCommand(unwrapCmd);
 program.addCommand(transferCmd);
 program.addCommand(policiesCmd);
 program.addCommand(configCmd);
+program.addCommand(setupGuideCmd);
 program.addCommand(genWalletCmd);
 program.addCommand(balanceCmd);
 program.parse(process.argv);

package/dist/index.mjs

@@ -868,9 +868,16 @@ tokensCmd.action(() => {
   }));
   output({ status: "success", tokens });
 });
-var initCmd = new Command("init").description("One-click setup: rent an Agent, authorize self as operator, and fund the vault").requiredOption("-l, --listing-id <bytes32>", "Template listing ID (bytes32 hex)").requiredOption("-d, --days <number>", "Number of days to rent").option("-f, --fund <bnb>", "BNB to deposit into vault (human-readable, e.g. 0.1)", "0").option("-r, --rpc <url>", "BSC RPC URL", DEFAULT_RPC).option("--listing-manager <address>", "ListingManagerV2 address", DEFAULT_LISTING_MANAGER).option("--nfa-address <address>", "AgentNFA contract address", DEFAULT_NFA);
+var initCmd = new Command("init").description("[DEPRECATED] One-click setup \u2014 uses same key as owner AND operator. Use setup-guide instead.").requiredOption("-l, --listing-id <bytes32>", "Template listing ID (bytes32 hex)").requiredOption("-d, --days <number>", "Number of days to rent").option("-f, --fund <bnb>", "BNB to deposit into vault (human-readable, e.g. 0.1)", "0").option("--i-understand-the-risk", "Acknowledge the security risk of using same key for owner and operator").option("-r, --rpc <url>", "BSC RPC URL", DEFAULT_RPC).option("--listing-manager <address>", "ListingManagerV2 address", DEFAULT_LISTING_MANAGER).option("--nfa-address <address>", "AgentNFA contract address", DEFAULT_NFA);
 initCmd.action(async (opts) => {
   try {
+    if (!opts.iUnderstandTheRisk) {
+      output({
+        status: "error",
+        message: "\u26A0\uFE0F  DEPRECATED: 'init' uses the same private key as both owner AND operator. If this key is leaked (e.g. via AI prompt injection), an attacker can withdraw ALL vault funds. Use 'setup-guide' instead for a secure dual-wallet setup. If you understand the risk and still want to proceed, add --i-understand-the-risk."
+      });
+      process.exit(1);
+    }
     if (!process.env.RUNNER_PRIVATE_KEY) {
       output({ status: "error", message: "RUNNER_PRIVATE_KEY environment variable is missing" });
       process.exit(1);
@@ -1469,14 +1476,125 @@ configCmd.action(async (opts) => {
     process.exit(1);
   }
 });
-var genWalletCmd = new Command("generate-wallet").description("Generate a new BSC wallet (address + private key)").action(() => {
+var setupGuideCmd = new Command("setup-guide").description("Output step-by-step instructions for secure dual-wallet agent setup").requiredOption("-l, --listing-id <bytes32>", "Template listing ID (bytes32 hex)").requiredOption("-d, --days <number>", "Number of days to rent").option("-r, --rpc <url>", "BSC RPC URL", DEFAULT_RPC).option("--listing-manager <address>", "ListingManagerV2 address", DEFAULT_LISTING_MANAGER).option("--nfa-address <address>", "AgentNFA contract address", DEFAULT_NFA);
+setupGuideCmd.action(async (opts) => {
+  try {
+    const pk = process.env.RUNNER_PRIVATE_KEY;
+    let operatorAddress;
+    if (pk) {
+      const account = privateKeyToAccount2(toHex(pk));
+      operatorAddress = account.address;
+    } else {
+      output({
+        status: "error",
+        message: "RUNNER_PRIVATE_KEY not set. Run 'generate-wallet' first to create an operator wallet, then set RUNNER_PRIVATE_KEY."
+      });
+      process.exit(1);
+      return;
+    }
+    const rpcUrl = opts.rpc || DEFAULT_RPC;
+    const listingManagerAddr = toHex(opts.listingManager || DEFAULT_LISTING_MANAGER);
+    const nfaAddr = toHex(opts.nfaAddress || DEFAULT_NFA);
+    const listingId = opts.listingId;
+    const daysToRent = Number(opts.days);
+    const publicClient = createPublicClient2({ chain: bsc2, transport: http2(rpcUrl) });
+    let rentCost = "unknown";
+    let priceInfo = "";
+    try {
+      const listing = await publicClient.readContract({
+        address: listingManagerAddr,
+        abi: LISTING_MANAGER_ABI,
+        functionName: "listings",
+        args: [listingId]
+      });
+      const [, , , pricePerDay, minDays, active] = listing;
+      if (!active) {
+        output({ status: "error", message: "Listing is not active" });
+        process.exit(1);
+      }
+      if (daysToRent < minDays) {
+        output({ status: "error", message: `Minimum rental is ${minDays} days, you requested ${daysToRent}` });
+        process.exit(1);
+      }
+      const totalRent = BigInt(pricePerDay) * BigInt(daysToRent);
+      rentCost = `${(Number(totalRent) / 1e18).toFixed(6)} BNB`;
+      priceInfo = ` (${totalRent.toString()} wei)`;
+    } catch {
+      rentCost = "unable to query \u2014 check listing-id";
+    }
+    const expiryTimestamp = Math.floor(Date.now() / 1e3) + daysToRent * 86400;
+    const setupUrl = `https://shll.run/setup?operator=${operatorAddress}&listing=${encodeURIComponent(listingId)}&days=${daysToRent}`;
+    output({
+      status: "guide",
+      securityModel: "DUAL-WALLET: Your wallet (owner) stays offline. AI only uses the operator wallet, which CANNOT withdraw vault funds.",
+      operatorAddress,
+      setupUrl,
+      rentCost: `${rentCost}${priceInfo}`,
+      steps: [
+        {
+          step: 1,
+          title: "Open SHLL Setup Page",
+          action: `Open ${setupUrl} in your browser`,
+          note: "Connect YOUR wallet (MetaMask/WalletConnect). This is your owner wallet \u2014 keep it safe and offline after setup."
+        },
+        {
+          step: 2,
+          title: "Rent Agent",
+          action: "Click 'Rent Agent' and confirm the transaction",
+          fallback: {
+            method: "BscScan (manual)",
+            contract: listingManagerAddr,
+            function: "rentToMintWithParams(bytes32,uint32,uint32,uint16,bytes)",
+            args: [listingId, daysToRent, 1, 1, "0x01"],
+            value: rentCost
+          }
+        },
+        {
+          step: 3,
+          title: "Authorize Operator",
+          action: "Click 'Authorize Operator' \u2014 this gives the AI wallet permission to trade within PolicyGuard safety limits",
+          note: `Operator address: ${operatorAddress}`,
+          fallback: {
+            method: "BscScan (manual)",
+            contract: nfaAddr,
+            function: "setOperator(uint256,address,uint64)",
+            args: ["<tokenId from step 2>", operatorAddress, expiryTimestamp]
+          }
+        },
+        {
+          step: 4,
+          title: "Fund Vault (optional)",
+          action: "Deposit BNB into the vault for trading",
+          fallback: {
+            method: "BscScan (manual)",
+            contract: nfaAddr,
+            function: "fundAgent(uint256)",
+            args: ["<tokenId>"],
+            value: "amount of BNB to deposit"
+          }
+        },
+        {
+          step: 5,
+          title: "Tell AI your token-id",
+          action: "Come back and tell the AI your token-id number. The AI will verify your portfolio and you're ready to trade."
+        }
+      ]
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    output({ status: "error", message });
+    process.exit(1);
+  }
+});
+var genWalletCmd = new Command("generate-wallet").description("Generate a new operator wallet (address + private key) for AI to use").action(() => {
   const pk = generatePrivateKey();
   const account = privateKeyToAccount2(pk);
   output({
     status: "success",
     address: account.address,
     privateKey: pk,
-    note: "SAVE THIS PRIVATE KEY SECURELY. This wallet is for paying gas fees (~$0.01/tx). Send ~$1 of BNB to the address above, then set RUNNER_PRIVATE_KEY to the privateKey value."
+    note: "SAVE THIS PRIVATE KEY SECURELY. This is the OPERATOR wallet \u2014 it can only trade within PolicyGuard limits. It CANNOT withdraw vault funds or transfer your Agent NFT. Send ~$1 of BNB here for gas fees, then set RUNNER_PRIVATE_KEY to this privateKey value.",
+    securityReminder: "Use a SEPARATE wallet (MetaMask, hardware wallet) as the owner to rent the agent and fund the vault. Run 'setup-guide' for step-by-step instructions."
   });
 });
 var balanceCmd = new Command("balance").description("Check BNB balance of the gas-paying wallet (RUNNER_PRIVATE_KEY)").option("-r, --rpc <url>", "BSC RPC URL", DEFAULT_RPC).action(async (opts) => {
@@ -1517,6 +1635,7 @@ program.addCommand(unwrapCmd);
 program.addCommand(transferCmd);
 program.addCommand(policiesCmd);
 program.addCommand(configCmd);
+program.addCommand(setupGuideCmd);
 program.addCommand(genWalletCmd);
 program.addCommand(balanceCmd);
 program.parse(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "shll-skills",
-    "version": "1.3.0",
+    "version": "2.0.0",
     "description": "SHLL Agent Runtime Skill for OpenClaw",
     "main": "dist/index.js",
     "bin": {
@@ -21,4 +21,4 @@
         "typescript": "^5.4.5",
         "@types/node": "^20.12.7"
     }
-}
+}

package/src/index.ts

@@ -438,18 +438,31 @@ tokensCmd.action(() => {
     output({ status: "success", tokens });
 });
 
-// ── Subcommand: init (one-click onboarding) ─────────────
+// ── Subcommand: init (DEPRECATED — uses same key for owner+operator) ──
 const initCmd = new Command("init")
-    .description("One-click setup: rent an Agent, authorize self as operator, and fund the vault")
+    .description("[DEPRECATED] One-click setup — uses same key as owner AND operator. Use setup-guide instead.")
     .requiredOption("-l, --listing-id <bytes32>", "Template listing ID (bytes32 hex)")
     .requiredOption("-d, --days <number>", "Number of days to rent")
     .option("-f, --fund <bnb>", "BNB to deposit into vault (human-readable, e.g. 0.1)", "0")
+    .option("--i-understand-the-risk", "Acknowledge the security risk of using same key for owner and operator")
     .option("-r, --rpc <url>", "BSC RPC URL", DEFAULT_RPC)
     .option("--listing-manager <address>", "ListingManagerV2 address", DEFAULT_LISTING_MANAGER)
     .option("--nfa-address <address>", "AgentNFA contract address", DEFAULT_NFA);
 
 initCmd.action(async (opts) => {
     try {
+        // Deprecation guard
+        if (!opts.iUnderstandTheRisk) {
+            output({
+                status: "error",
+                message: "⚠️  DEPRECATED: 'init' uses the same private key as both owner AND operator. " +
+                    "If this key is leaked (e.g. via AI prompt injection), an attacker can withdraw ALL vault funds. " +
+                    "Use 'setup-guide' instead for a secure dual-wallet setup. " +
+                    "If you understand the risk and still want to proceed, add --i-understand-the-risk.",
+            });
+            process.exit(1);
+        }
+
         // Validate private key
         if (!process.env.RUNNER_PRIVATE_KEY) {
             output({ status: "error", message: "RUNNER_PRIVATE_KEY environment variable is missing" });
@@ -1227,9 +1240,138 @@ configCmd.action(async (opts) => {
     }
 });
 
+// -- Subcommand: setup-guide (secure dual-wallet onboarding) ------
+const setupGuideCmd = new Command("setup-guide")
+    .description("Output step-by-step instructions for secure dual-wallet agent setup")
+    .requiredOption("-l, --listing-id <bytes32>", "Template listing ID (bytes32 hex)")
+    .requiredOption("-d, --days <number>", "Number of days to rent")
+    .option("-r, --rpc <url>", "BSC RPC URL", DEFAULT_RPC)
+    .option("--listing-manager <address>", "ListingManagerV2 address", DEFAULT_LISTING_MANAGER)
+    .option("--nfa-address <address>", "AgentNFA contract address", DEFAULT_NFA);
+
+setupGuideCmd.action(async (opts) => {
+    try {
+        // Get operator address from RUNNER_PRIVATE_KEY
+        const pk = process.env.RUNNER_PRIVATE_KEY;
+        let operatorAddress: string;
+        if (pk) {
+            const account = privateKeyToAccount(toHex(pk) as Hex);
+            operatorAddress = account.address;
+        } else {
+            output({
+                status: "error",
+                message: "RUNNER_PRIVATE_KEY not set. Run 'generate-wallet' first to create an operator wallet, then set RUNNER_PRIVATE_KEY.",
+            });
+            process.exit(1);
+            return;
+        }
+
+        const rpcUrl = opts.rpc || DEFAULT_RPC;
+        const listingManagerAddr = toHex(opts.listingManager || DEFAULT_LISTING_MANAGER) as Address;
+        const nfaAddr = toHex(opts.nfaAddress || DEFAULT_NFA) as Address;
+        const listingId = opts.listingId as string;
+        const daysToRent = Number(opts.days);
+
+        // Query listing to calculate rent cost
+        const publicClient = createPublicClient({ chain: bsc, transport: http(rpcUrl) });
+        let rentCost = "unknown";
+        let priceInfo = "";
+        try {
+            const listing = await publicClient.readContract({
+                address: listingManagerAddr,
+                abi: LISTING_MANAGER_ABI,
+                functionName: "listings",
+                args: [listingId as Hex],
+            });
+            const [, , , pricePerDay, minDays, active] = listing;
+            if (!active) {
+                output({ status: "error", message: "Listing is not active" });
+                process.exit(1);
+            }
+            if (daysToRent < minDays) {
+                output({ status: "error", message: `Minimum rental is ${minDays} days, you requested ${daysToRent}` });
+                process.exit(1);
+            }
+            const totalRent = BigInt(pricePerDay) * BigInt(daysToRent);
+            rentCost = `${(Number(totalRent) / 1e18).toFixed(6)} BNB`;
+            priceInfo = ` (${totalRent.toString()} wei)`;
+        } catch {
+            rentCost = "unable to query — check listing-id";
+        }
+
+        // Calculate operator expiry timestamp
+        const expiryTimestamp = Math.floor(Date.now() / 1000) + daysToRent * 86400;
+
+        // Build shll.run setup URL
+        const setupUrl = `https://shll.run/setup?operator=${operatorAddress}&listing=${encodeURIComponent(listingId)}&days=${daysToRent}`;
+
+        output({
+            status: "guide",
+            securityModel: "DUAL-WALLET: Your wallet (owner) stays offline. AI only uses the operator wallet, which CANNOT withdraw vault funds.",
+            operatorAddress,
+            setupUrl,
+            rentCost: `${rentCost}${priceInfo}`,
+            steps: [
+                {
+                    step: 1,
+                    title: "Open SHLL Setup Page",
+                    action: `Open ${setupUrl} in your browser`,
+                    note: "Connect YOUR wallet (MetaMask/WalletConnect). This is your owner wallet — keep it safe and offline after setup.",
+                },
+                {
+                    step: 2,
+                    title: "Rent Agent",
+                    action: "Click 'Rent Agent' and confirm the transaction",
+                    fallback: {
+                        method: "BscScan (manual)",
+                        contract: listingManagerAddr,
+                        function: "rentToMintWithParams(bytes32,uint32,uint32,uint16,bytes)",
+                        args: [listingId, daysToRent, 1, 1, "0x01"],
+                        value: rentCost,
+                    },
+                },
+                {
+                    step: 3,
+                    title: "Authorize Operator",
+                    action: "Click 'Authorize Operator' — this gives the AI wallet permission to trade within PolicyGuard safety limits",
+                    note: `Operator address: ${operatorAddress}`,
+                    fallback: {
+                        method: "BscScan (manual)",
+                        contract: nfaAddr,
+                        function: "setOperator(uint256,address,uint64)",
+                        args: ["<tokenId from step 2>", operatorAddress, expiryTimestamp],
+                    },
+                },
+                {
+                    step: 4,
+                    title: "Fund Vault (optional)",
+                    action: "Deposit BNB into the vault for trading",
+                    fallback: {
+                        method: "BscScan (manual)",
+                        contract: nfaAddr,
+                        function: "fundAgent(uint256)",
+                        args: ["<tokenId>"],
+                        value: "amount of BNB to deposit",
+                    },
+                },
+                {
+                    step: 5,
+                    title: "Tell AI your token-id",
+                    action: "Come back and tell the AI your token-id number. The AI will verify your portfolio and you're ready to trade.",
+                },
+            ],
+        });
+
+    } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        output({ status: "error", message });
+        process.exit(1);
+    }
+});
+
 // -- Subcommand: generate-wallet ---------------------------------
 const genWalletCmd = new Command("generate-wallet")
-    .description("Generate a new BSC wallet (address + private key)")
+    .description("Generate a new operator wallet (address + private key) for AI to use")
     .action(() => {
         const pk = generatePrivateKey();
         const account = privateKeyToAccount(pk);
@@ -1237,7 +1379,11 @@ const genWalletCmd = new Command("generate-wallet")
             status: "success",
             address: account.address,
             privateKey: pk,
-            note: "SAVE THIS PRIVATE KEY SECURELY. This wallet is for paying gas fees (~$0.01/tx). Send ~$1 of BNB to the address above, then set RUNNER_PRIVATE_KEY to the privateKey value.",
+            note: "SAVE THIS PRIVATE KEY SECURELY. This is the OPERATOR wallet — it can only trade within PolicyGuard limits. " +
+                "It CANNOT withdraw vault funds or transfer your Agent NFT. " +
+                "Send ~$1 of BNB here for gas fees, then set RUNNER_PRIVATE_KEY to this privateKey value.",
+            securityReminder: "Use a SEPARATE wallet (MetaMask, hardware wallet) as the owner to rent the agent and fund the vault. " +
+                "Run 'setup-guide' for step-by-step instructions.",
         });
     });
 
@@ -1286,6 +1432,7 @@ program.addCommand(unwrapCmd);
 program.addCommand(transferCmd);
 program.addCommand(policiesCmd);
 program.addCommand(configCmd);
+program.addCommand(setupGuideCmd);
 program.addCommand(genWalletCmd);
 program.addCommand(balanceCmd);
 program.parse(process.argv);