Improvements (#14)

* improve pred flows

* improve skills

* minor improvements

* update to latest main

* improve description

* address review comments

* add safety check

* update predict funding

Author: AyushBherwani1998

skills/metamask-agent-wallet/SKILL.md

@@ -42,6 +42,8 @@ Match the user's intent to a command and reference file, then read the reference
 | Show active wallet details | `mm wallet show` | [wallet.md](references/wallet.md) |
 | Show active wallet address | `mm wallet address` | [wallet.md](references/wallet.md) |
 | Check the active wallet balance | `mm wallet balance` | [wallet.md](references/wallet.md) |
+| Show current trading mode and policies | `mm wallet trading-mode get` | [wallet.md](references/wallet.md) |
+| Set trading mode (guard or beast) | `mm wallet trading-mode set` | [wallet.md](references/wallet.md) |
 | Sign a plaintext message | `mm wallet sign-message` | [signing.md](references/signing.md) |
 | Sign EIP-712 typed data | `mm wallet sign-typed-data` | [signing.md](references/signing.md) |
 | Send a raw EVM transaction | `mm wallet send-transaction` | [transaction.md](references/transaction.md) |
@@ -69,7 +71,7 @@ Match the user's intent to a command and reference file, then read the reference
 | One-time Predict setup | `mm predict setup` | [predict.md](references/predict.md) |
 | Create or refresh Predict credentials | `mm predict auth` | [predict.md](references/predict.md) |
 | Repair Predict approvals | `mm predict approve` | [predict.md](references/predict.md) |
-| Check Predict back-end status | `mm predict status` | [predict.md](references/predict.md) |
+| Check Predict back-end status and account setup | `mm predict status` | [predict.md](references/predict.md) |
 | Check if Polymarket is geoblocked for your IP | `mm predict geoblock` | [predict.md](references/predict.md) |
 | List prediction markets | `mm predict markets list` | [predict.md](references/predict.md) |
 | Search prediction markets | `mm predict markets search` | [predict.md](references/predict.md) |
@@ -112,7 +114,12 @@ CLI behavior lives in `references/`. Repeatable patterns live in `workflows/`. L
 | Open a perpetual position flow | [perps-open-position.md](workflows/perps-open-position.md) |
 | Close a perpetual position flow | [perps-close-position.md](workflows/perps-close-position.md) |
 | Modify a perpetual position flow | [perps-modify-position.md](workflows/perps-modify-position.md) |
-| Predict setup-fund-quote-place flow | [predict-trading.md](workflows/predict-trading.md) |
+| Predict first-time setup and credentials | [predict-setup.md](workflows/predict-setup.md) |
+| Deposit or withdraw pUSD from Predict wallet | [predict-funding.md](workflows/predict-funding.md) |
+| Search and browse prediction markets | [predict-markets.md](workflows/predict-markets.md) |
+| Quote and place a prediction order | [predict-place-order.md](workflows/predict-place-order.md) |
+| View or cancel Predict orders and positions | [predict-manage-orders.md](workflows/predict-manage-orders.md) |
+| View Predict portfolio and redeem winnings | [predict-portfolio.md](workflows/predict-portfolio.md) |
 | Token discovery, prices, and market data | [market-data.md](workflows/market-data.md) |
 
 ## Global Flags
@@ -187,6 +194,7 @@ Before constructing any command, validate all user-provided values:
 | `--side` (predict) | Must be `buy` or `sell` |
 | `--slippage` | Must be a number between 0 and 100 |
 | `--from-chain`, `--to-chain` | Must be a positive integer EVM chain ID |
+| `--to-address` | Must match `^0x[0-9a-fA-F]{40}$`. Only valid for cross-chain swaps (`--to-chain` differs from `--from-chain`); rejected for same-chain swaps |
 | `--password` | Must be a non-empty string. Never log, display, or store the value. |
 
 Do not pass unvalidated user input into any command.
@@ -199,7 +207,7 @@ Do not pass unvalidated user input into any command.
 | Raw transactions | Always confirm transaction payload, chain, recipient, value, and calldata summary before executing |
 | Message signing | Always show exact message and chain before signing |
 | Typed-data signing | Always show domain, primary type, chain, verifying contract, and message summary before signing |
-| Swaps / bridges | Always confirm from/to tokens, amount, source/destination chain, slippage, and quoted output before executing |
+| Swaps / bridges | Always confirm from/to tokens, amount, source/destination chain, slippage, quoted output, and recipient address (if `--to-address` is set) before executing |
 | Perps trading | Always confirm symbol, side, size, leverage, venue, order type, and limit price if present before executing |
 | Perps deposit/withdraw | Always confirm amount, asset, venue, network, and destination where applicable before executing |
 | Predict trading | Always confirm token ID, side, size, price, order type, market, and outcome before executing |

skills/metamask-agent-wallet/references/decode.md

@@ -12,13 +12,11 @@ Decode hex-encoded EVM calldata into its function name, parameters, and a plain-
 mm decode --payload <0x-calldata> [--toon]
 ```
 
-The payload can also be passed positionally: `mm decode <0x-calldata>`.
-
 ### Supported Flags
 
 | Name | Required | Description |
 | --- | --- | --- |
-| `--payload` | Yes | Hex-encoded EVM calldata to decode (e.g. `0x095ea7b3...`). Positional index 0 |
+| `--payload` | Yes | Hex-encoded EVM calldata to decode (e.g. `0x095ea7b3...`). |
 
 ### Output
 
@@ -31,8 +29,7 @@ The payload can also be passed positionally: `mm decode <0x-calldata>`.
 ### Example
 
 ```bash
-mm decode --payload 0x095ea7b3000000000000000000000000...
-mm decode 0x095ea7b3000000000000000000000000... --toon
+mm decode --payload 0x095ea7b3000000000000000000000000... --toon
 ```
 
 ## Notes

skills/metamask-agent-wallet/references/errors.md

@@ -66,6 +66,8 @@ This reference lists error codes the CLI actually emits. SDK-only or remapped co
 | `NO_AUTH_TOKEN` | Missing authentication token for wallet operations |
 | `NO_PROJECT_ID` | Project ID not configured for wallet |
 | `MISSING_PROJECT_ID` | Project ID is not configured |
+| `INVALID_TRADING_MODE` | Invalid trading mode; use `guard` or `beast` |
+| `ALREADY_SET_TRADING_MODE` | Trading mode is already set to the requested value |
 
 ## Command Errors
 

skills/metamask-agent-wallet/references/predict.md

@@ -92,7 +92,7 @@ mm predict approve --wait
 
 ## `predict status` Command
 
-Probe Predict back-end reachability (Gamma + CLOB).
+Probe Predict back-end reachability (Gamma + CLOB) and report account setup status: deposit wallet address, on-chain deployment, stored CLOB credentials, and a `setupComplete` flag. 
 
 ### Syntax
 

skills/metamask-agent-wallet/references/swap.md

@@ -9,7 +9,7 @@ Get a swap or bridge quote showing expected output, fees, and route.
 ### Syntax
 
 ```bash
-mm swap quote --from <token> --to <token> --amount <amount> --from-chain <chain-id> [--to-chain <chain-id>] [--slippage <percent>]
+mm swap quote --from <token> --to <token> --amount <amount> --from-chain <chain-id> [--to-chain <chain-id>] [--to-address <address>] [--slippage <percent>]
 ```
 
 ### Supported Flags
@@ -20,7 +20,8 @@ mm swap quote --from <token> --to <token> --amount <amount> --from-chain <chain-
 | `--to` | Yes | Destination token symbol (e.g. USDC, USDT) |
 | `--amount` | Yes | Human-readable amount to swap (e.g. 0.5, 100) |
 | `--from-chain` | Yes | Source EVM chain ID (e.g. 1 for Ethereum, 137 for Polygon) |
-| `--to-chain` | No | Destination EVM chain ID; defaults to `--from-chain` for same-chain swaps |
+| `--to-chain` | No | Destination EVM chain ID. Defaults to `--from-chain` for same-chain swaps |
+| `--to-address` | No | Recipient address for bridged output tokens. Only valid for cross-chain swaps. Defaults to the signer's wallet |
 | `--slippage` | No | Maximum slippage as a percentage, 0-100 (defaults to 0.5) |
 
 ### Example
@@ -30,6 +31,7 @@ mm swap quote --from ETH --to USDC --amount 0.5 --from-chain 1
 mm swap quote --from USDC --to USDT --amount 100 --from-chain 137
 mm swap quote --from ETH --to USDC --amount 1 --from-chain 1 --to-chain 137
 mm swap quote --from ETH --to USDC --amount 0.5 --from-chain 1 --slippage 1
+mm swap quote --from ETH --to pUSD --amount 0.5 --from-chain 1 --to-chain 137 --to-address 0x742d...f2bD18
 ```
 
 ## `swap execute` Command
@@ -40,7 +42,7 @@ Execute a swap or bridge, either by referencing a previous quote ID or by provid
 
 ```bash
 mm swap execute --quote-id <id> [--password <password>]
-mm swap execute --from <token> --to <token> --amount <amount> --from-chain <chain-id> [--to-chain <chain-id>] [--slippage <percent>] [--password <password>]
+mm swap execute --from <token> --to <token> --amount <amount> --from-chain <chain-id> [--to-chain <chain-id>] [--to-address <address>] [--slippage <percent>] [--password <password>]
 ```
 
 ### Supported Flags
@@ -52,7 +54,8 @@ mm swap execute --from <token> --to <token> --amount <amount> --from-chain <chai
 | `--to` | Yes (unless `--quote-id`) | Destination token symbol |
 | `--amount` | Yes (unless `--quote-id`) | Amount to swap |
 | `--from-chain` | Yes (unless `--quote-id`) | Source EVM chain ID |
-| `--to-chain` | No | Destination EVM chain ID; defaults to `--from-chain` for same-chain swaps |
+| `--to-chain` | No | Destination EVM chain ID. Defaults to `--from-chain` for same-chain swaps |
+| `--to-address` | No | Recipient address for bridged output tokens. Only valid for cross-chain swaps. Defaults to the signer's wallet. Persisted quotes retain the recipient for `--quote-id` execution |
 | `--slippage` | No | Maximum slippage as a percentage, 0-100 (defaults to 0.5) |
 | `--password` | No | Password to unlock the BYOK mnemonic (BYOK mode only) [env: `MM_PASSWORD`] |
 
@@ -84,7 +87,7 @@ mm swap status --quote-id <id> [--tx-hash <hash>]
 | Name | Required | Description |
 | --- | --- | --- |
 | `--quote-id` | Yes | Quote ID returned by `mm swap quote` |
-| `--tx-hash` | No | Source transaction hash; overrides the stored hash from execute |
+| `--tx-hash` | No | Source transaction hash. Overrides the stored hash from execute |
 
 ### Example
 

skills/metamask-agent-wallet/references/wallet.md

@@ -18,7 +18,7 @@ mm wallet create [--chain-namespace <namespace>] [--name <name>] [--trading-mode
 | --- | --- | --- |
 | `--chain-namespace` | No | Wallet chain namespace: `evm` (EIP-155) (allowed: `evm`) |
 | `--name` | No | Display name for the wallet |
-| `--trading-mode` | No | Trading mode for server wallets: `guard` (enforces outflow/whitelist policies) or `beast` (skips policy checks). Only applies to server-wallet mode (allowed: `guard`, `beast`) |
+| `--trading-mode` | No | `guard` enforces outflow/whitelist policies and blocks malicious transactions. `beast` skips policy checks but still blocks malicious transactions. Only applies to server-wallet mode (allowed: `guard`, `beast`) |
 | `--password` | No | Password to unlock the BYOK mnemonic (BYOK mode only) [env: `MM_PASSWORD`] |
 
 ### Example
@@ -127,6 +127,45 @@ mm wallet address
 mm wallet address --chain-namespace evm
 ```
 
+## `wallet trading-mode get` Command
+
+Show the current trading mode, active server-wallet address, and policies for the selected wallet. Server-wallet mode only.
+
+### Syntax
+
+```bash
+mm wallet trading-mode get
+```
+
+### Example
+
+```bash
+mm wallet trading-mode get
+```
+
+## `wallet trading-mode set` Command
+
+Set the trading mode for the active server wallet. Prompts for confirmation when switching to Beast mode. Rejects if the mode is already set or the session isn't in server-wallet mode.
+
+### Syntax
+
+```bash
+mm wallet trading-mode set <guard|beast>
+```
+
+### Supported Flags
+
+| Name | Required | Description |
+| --- | --- | --- |
+| `<mode>` | Yes | `guard` enforces outflow/whitelist policies and blocks malicious transactions. `beast` skips policy checks but still blocks malicious transactions |
+
+### Example
+
+```bash
+mm wallet trading-mode set guard
+mm wallet trading-mode set beast
+```
+
 ## `wallet balance` Command
 
 Show native and token balances for the active wallet.

skills/metamask-agent-wallet/workflows/bridge.md

@@ -1,4 +1,4 @@
-# Bridge Workflow
+# Bridge workflow
 
 Use this workflow when the user wants to bridge tokens across chains.
 
@@ -10,7 +10,7 @@ Reference command syntax in `references/swap.md`. The CLI uses the same `swap` c
 2. Confirm with the user.
 3. Execute and track status.
 
-Do not skip the quote review step. It is where the user sees output amount, fees, route, and slippage.
+Don't skip the quote review step. The user needs to see output amount, fees, route, and slippage before executing.
 
 ## Quote
 
@@ -20,8 +20,14 @@ mm swap quote --from ETH --to USDC --amount 1 --from-chain 1 --to-chain 137 --sl
 
 Required flags: `--from`, `--to`, `--amount`, `--from-chain`, and `--to-chain`.
 
+If the user wants the bridged tokens sent to a different wallet on the destination chain, add `--to-address`:
+
+```bash
+mm swap quote --from ETH --to USDC --amount 1 --from-chain 1 --to-chain 137 --to-address 0x742d...f2bD18
+```
+
 Persist the quote id for execution. Show the quote to the user before execution.
-Confirm source token, destination token, amount, source chain, destination chain, slippage, expected output, fees, and route.
+Confirm source token, destination token, amount, source chain, destination chain, slippage, expected output, fees, route, and recipient address (if `--to-address` was set).
 
 ## Execute
 
@@ -40,7 +46,7 @@ mm swap status --quote-id "QUOTE_ID" --tx-hash 0xabc123
 
 Use status polling for bridges where the destination side can lag behind the source transaction.
 
-## Edge Cases
+## Edge cases
 
 - Quote expired: re-quote and ask the user to review the new quote.
 - Insufficient balance: surface the error verbatim.

skills/metamask-agent-wallet/workflows/login.md

@@ -6,10 +6,9 @@ Reference command syntax in `references/auth.md`.
 
 ## Flow
 
-1. Confirm the target environment with `mm config get env` (set with `mm config set env` before login if not `prod`).
-2. Ask the user which login method they want: MetaMask Mobile QR, Google, or Email.
-3. Execute login.
-4. Verify with token.
+1. Ask the user which login method they want: MetaMask Mobile QR, Google, or Email.
+2. Execute login.
+3. Verify with token.
 
 ## Login
 

skills/metamask-agent-wallet/workflows/onboarding.md

@@ -7,11 +7,10 @@ Reference command syntax in `references/auth.md` and `references/wallet.md`.
 ## Flow
 
 1. Check CLI installation.
-2. Configure environment (if not using production).
-3. Login.
-4. Initialize wallet mode.
-5. Verify auth status.
-6. Show wallet address.
+2. Login.
+3. Initialize wallet mode.
+4. Verify auth status.
+5. Show wallet address.
 
 ## Check CLI Installation
 
@@ -23,19 +22,6 @@ If this fails, the CLI is not installed. Guide the user to install it with `npm
 
 Then run the version compatibility check from the skill `Preflight` section: compare the installed `major.minor` against the pinned `cliVersion` and the latest published release, and warn the user if they are out of sync.
 
-## Configure Environment
-
-Production (`prod`) is the default. Set the target environment **before** login if the user needs dev or uat:
-
-```bash
-mm config get env
-mm config set env dev
-```
-
-For a one-off override without persisting, use `MM_ENV=dev mm login` (or `uat`).
-
-To switch environments, run `mm config set env <prod|dev|uat>`.
-
 ## Login Flow
 
 Ask the user which login method they want to use: MetaMask Mobile QR, Google, or Email. QR (`mm login qr`) is available on non-production builds (dev/uat); on production it returns `COMING_SOON`, so fall back to Google or email there.

skills/metamask-agent-wallet/workflows/perps-open-position.md

@@ -1,4 +1,4 @@
-# Perps Open Position Workflow
+# Perps open position workflow
 
 Use this workflow when the user wants to open a new perpetual position.
 
@@ -11,29 +11,63 @@ Reference command syntax in `references/perps.md`.
 3. Dry run.
 4. Confirm with the user and open.
 
-## Confirm Symbol
+## Confirm symbol
 
-If the user does not mention a token symbol, list available markets and confirm with the user:
+If the user doesn't mention a token symbol, list available markets and confirm with the user:
 
 ```bash
 mm perps markets
 ```
 
-## Check Balance
+## Check balance
 
-`--venue` defaults to `hyperliquid`. It can be omitted.
+`--venue` defaults to `hyperliquid`. You can omit it.
 
 ```bash
 mm perps balance
 ```
 
 If available margin is zero or insufficient, deposit USDC before proceeding. Hyperliquid only supports deposits from Arbitrum mainnet (`eip155:42161`).
 
+Check the user's Arbitrum balance for USDC and ETH (for gas).
+
+```bash
+mm wallet balance --chain 42161
+```
+
+### No ETH and no USDC on Arbitrum
+
+Inform the user that ETH on Arbitrum is required for gas. Without ETH, no on-chain transaction is possible. Bridge from another chain.
+
+```bash
+mm swap quote --from <TOKEN> --to ETH --amount 0.001 --from-chain <SOURCE_CHAIN_ID> --to-chain 42161
+mm swap execute --quote-id "$QUOTE_ID" # quote ID from the swap quote command
+```
+
+Once the user has ETH for gas, swap or bridge to get USDC on Arbitrum.
+
+```bash
+mm swap quote --from <TOKEN> --to USDC --amount <AMOUNT> --from-chain <SOURCE_CHAIN_ID> --to-chain 42161
+mm swap execute --quote-id "$QUOTE_ID" # quote ID from the swap quote command
+```
+
+### Has ETH or another token on Arbitrum (but no USDC)
+
+Swap to USDC on Arbitrum.
+
+```bash
+mm swap quote --from <TOKEN> --to USDC --amount <AMOUNT> --from-chain 42161
+mm swap execute --quote-id "$QUOTE_ID" # quote ID from the swap quote command
+```
+
+### Has ETH and USDC on Arbitrum
+
+Deposit USDC directly into Hyperliquid.
+
 ```bash
-mm perps deposit --amount <amount> --asset USDC
+mm perps deposit --amount <AMOUNT> --asset USDC
 ```
 
-To confirm a deposit, wait briefly and poll `mm perps balance`.
 
 ## Quote
 
@@ -45,7 +79,7 @@ mm perps quote --symbol BTC --side long --size 0.01 --leverage 5
 
 Show the user estimated entry, notional, fees, liquidation price, side, size, leverage, and venue before proceeding.
 
-## Dry Run
+## Dry run
 
 Preview the order before signing:
 
@@ -65,4 +99,4 @@ Remove `--dry-run` only after explicit user confirmation:
 mm perps open --symbol BTC --side long --size 0.01 --leverage 5
 ```
 
-Do not add `--yes` unless the user explicitly asked for unattended execution.
+Don't add `--yes` unless the user explicitly asked for unattended execution.