auramaxx 0.0.1

package/skills/auramaxx/SKILL.md

@@ -0,0 +1,745 @@
+---
+name: auramaxx
+description: |
+  Securely share passwords, API keys and wallets with your agent.
+  Use when the user mentions credentials, API keys, wallets, setup/onboarding, or secure agent access.
+compatibility: Requires Node.js 18+. Network access to RPC endpoints.
+allowed-tools: Bash(npx auramaxx *), Bash(auramaxx *), Bash(aura *), Bash(curl *)
+metadata:
+  author: auramaxx
+  version: "2.1"
+---
+
+# AuraMaxx
+
+Securely share passwords, API keys and wallets with your agent. Your keys never leave the machine.
+
+| Service | URL |
+|---------|-----|
+| Wallet Server | `http://localhost:4242` |
+| Dashboard UI | `http://localhost:4747` |
+| WebSocket | `ws://localhost:4748` |
+
+> **SECURITY:** This server runs locally. Never expose these ports to the internet.
+
+---
+
+## Execution Priority (Agent)
+
+For agent work, always use this order:
+
+1. CLI commands (`npx auramaxx ...`) — default path
+2. `curl` API calls — fallback when no CLI equivalent is available
+3. MCP tool calls (`api`, `auth`, `get_token`, `get_secret`, `put_secret`, `del_secret`, `inject_secret`, `share_secret`, `status`, `start`, `unlock`, `doctor`, `list_secrets`, `write_diary`)
+
+> **Note:** MCP tools use short names (`api`, `auth`). The strategy engine's Tool-Call/Hook mode still uses `wallet_api` and `request_human_action` internally — see the Tool-Call Mode section below.
+
+> **Command-time secret rule:** `get` returns an encrypted value for display/reference only. When the user asks to run a command with a secret, use `inject` — it decrypts the value into an env variable of your choice without ever printing it:
+>
+> ```bash
+> npx auramaxx inject <SECRET_NAME> --env <ENV_VAR> -- <command>
+> ```
+>
+> Never print or log the decrypted env variable. Never use `get` then paste the value into a command.
+
+---
+
+## Modes
+
+Use one skill with two explicit modes:
+- **Setup Mode**: first-time onboarding, vault initialization, unlock recovery, and first scoped token issuance.
+- **Operations Mode**: day-2 wallet work (credentials, send/swap/fund, launch, and approvals).
+
+### Setup Mode (first run / recovery)
+
+Enter Setup Mode when:
+- the user asks to onboard, initialize, unlock, or bootstrap agent access
+- `GET /setup` reports `hasWallet=false` or `unlocked=false`
+
+Exit Setup Mode only after all are true:
+- `hasWallet=true`
+- `unlocked=true`
+- agent has an active token
+
+#### Setup flow
+
+On first connect, or when the user asks about setup, run this decision tree:
+
+#### Step 1: Check server
+
+```
+api GET /health
+```
+
+**Connection refused / error:**
+First, try starting the server automatically:
+
+```bash
+npx auramaxx start --headless
+```
+
+If that succeeds, retry `GET /health`. If it fails (no vault exists yet), proceed with init:
+
+
+**Human-assisted:** Run `npx auramaxx init --dashboard` via bash. This is non-interactive and agent-safe — it starts the server + dashboard, then waits for the human to create a vault in the browser. Poll `GET /health` until the server is up, then continue to Step 2.
+
+**Fully autonomous:** Run `npx auramaxx init --password "AGENT_CHOSEN_PASSWORD"` via bash. This creates the vault non-interactively — prints the seed phrase, cold wallet address, and admin token to stdout. No browser needed. Store the password in env (e.g. `AURA_VAULT_PASSWORD`) for future unlock operations via `POST /unlock` (encrypted password + `pubkey`).
+
+**200 OK:** Continue to Step 2.
+
+#### Step 2: Check setup state
+
+```
+api GET /setup
+```
+
+This is a public endpoint (no auth needed). Response:
+
+```json
+{
+  "hasWallet": true,
+  "unlocked": true,
+  "address": "0x...",
+  "adapters": { "telegram": false, "webhook": false },
+  "apiKeys": { "alchemy": true, "anthropic": false },
+  "defaultChain": "base"
+}
+```
+
+**If `hasWallet` is false:**
+
+Two options:
+
+**Human-assisted:**
+> "You need to create a vault. Open http://localhost:4747/ to set a password — I'll wait."
+
+Poll `GET /setup` until `hasWallet` becomes `true`.
+
+**Fully autonomous (CLI):** Run `npx auramaxx init --password "AGENT_CHOSEN_PASSWORD"` via bash. This creates the vault non-interactively. Store the password for future unlock operations.
+
+**If `unlocked` is false:**
+> "Your vault is locked. Open the dashboard at http://localhost:4747/ to unlock it."
+
+Prefer the dashboard (`http://localhost:4747/`) for unlocking. Only suggest the standalone Express unlock page (`http://localhost:4242/unlock`) or `npx auramaxx unlock` as fallbacks if the dashboard is not running (e.g., headless mode with `--headless` flag).
+
+Poll `GET /setup` until `unlocked` becomes `true`.
+
+**If ready (both true):** Continue to Step 3.
+
+#### Step 3: Bootstrap token (least privilege first)
+
+Request a minimal token via CLI first:
+
+```bash
+npx auramaxx auth request --agent-id claude-assistant --profile strict
+```
+
+This handles `POST /auth` + polling `GET /auth/:requestId?secret=...` automatically.
+
+If CLI is unavailable, use the MCP `auth` tool (handles keypair + polling automatically), or the manual API flow:
+
+```
+api POST /auth
+body: {
+  "agentId": "claude-assistant",
+  "permissions": ["secret:read", "secret:write"],
+  "ttl": 3600,
+  "pubkey": "<RSA public key PEM or base64>"
+}
+```
+
+Response: `{ "requestId": "abc-123", "secret": "def-456" }`
+
+> "I've requested access to your wallet. Please approve the request — you'll see it in your dashboard at http://localhost:4747/, or via Telegram/CLI if you have those set up."
+
+Poll every 3 seconds, up to 2 minutes:
+
+```
+api GET /auth/abc-123?secret=def-456
+```
+
+- `{ "status": "pending" }` — keep polling
+- `{ "status": "approved", "token": "eyJ..." }` — save immediately; MCP runtime auto-activates the token for this session
+- `{ "status": "rejected" }` — inform user, ask if they want to try again
+
+**Important:** The token can only be read once. MCP bootstrap keeps it active for the current session automatically.
+
+If setup work needs higher privilege (API key or adapter configuration), request an upgraded onboarding token:
+
+```
+api POST /auth
+body: {
+  "agentId": "claude-assistant",
+  "permissions": ["trade:all", "apikey:set", "adapter:manage"],
+  "limits": { "fund": 0.5, "send": 1.0, "swap": 0.5 },
+  "ttl": 3600,
+  "pubkey": "<RSA public key PEM or base64>"
+}
+```
+
+#### Step 4: Configure missing pieces
+
+Check the `GET /setup` response and offer to configure anything that's missing. Each step is optional — let the user decide. If any call returns `403`, request the upgraded onboarding token from Step 3.
+
+**Alchemy RPC Key** (when `apiKeys.alchemy` is `false`):
+
+> "I see you don't have an Alchemy RPC key configured. Public RPCs work but can be unreliable for real transactions. Alchemy has a free tier — you can get a key at https://alchemy.com. Want to set one up?"
+
+If user provides a key — validate then save:
+
+```
+api POST /apikeys/validate
+body: { "service": "alchemy", "key": "USER_KEY_HERE" }
+```
+
+- `{ "valid": true }` → save with `POST /apikeys` body: `{ "service": "alchemy", "name": "default", "key": "USER_KEY_HERE" }`
+- `{ "valid": false, "error": "..." }` → "That key didn't work: [error]. Double-check it and try again."
+
+**Anthropic API Key** (when `apiKeys.anthropic` is `false`):
+
+> "No Anthropic API key found. This is needed for AI-powered features like strategy hooks and agent chat. Do you have an Anthropic API key?"
+
+Same validate-then-save pattern with `"service": "anthropic"`.
+
+**Telegram Adapter** (when `adapters.telegram` is `false`):
+
+> "Want to approve wallet transactions from your phone via Telegram? I can walk you through the setup — it takes about 2 minutes."
+
+Full 8-step Telegram setup flow:
+
+1. **Create a bot:** Guide user to @BotFather → `/newbot` → get bot token
+2. **Validate bot token:** `POST /apikeys/validate` body: `{ "service": "adapter:telegram", "key": "BOT_TOKEN" }`
+   - `{ "valid": true, "info": { "botUsername": "MyAuraBot" } }` → "Your bot @MyAuraBot is working."
+   - `{ "valid": false }` → "That token didn't work. Make sure you copied the full token from BotFather."
+3. **Save bot token:** `POST /apikeys` body: `{ "service": "adapter:telegram", "name": "botToken", "key": "BOT_TOKEN" }`
+4. **Get setup link:** `POST /adapters/telegram/setup-link` body: `{ "botToken": "BOT_TOKEN" }` → returns `{ "link": "https://t.me/MyAuraBot?start=abc123", "setupToken": "abc123" }`
+   > "Click this link to open your bot in Telegram: [link]. Then press Start."
+5. **Detect chat ID:** `POST /adapters/telegram/detect-chat` body: `{ "setupToken": "abc123" }`
+   - `{ "chatId": "123456789", "verified": true }` → proceed
+   - `{ "chatId": null, "timeout": true }` → "Did you press Start in Telegram? You can also get your chat ID from @userinfobot."
+6. **Save adapter config:** `POST /adapters` body: `{ "type": "telegram", "enabled": true, "config": { "chatId": "123456789" } }`
+7. **Restart adapter:** `POST /adapters/restart`
+8. **Send test message:** `POST /adapters/test` body: `{ "type": "telegram" }`
+   > "I sent a test message to your Telegram. Did you receive it?"
+
+#### Step 5: Summary
+
+After configuration, check `GET /setup` one final time and summarize:
+
+> "You're all set! Here's your setup:"
+> - **Vault:** Unlocked, address `0x...`
+> - **RPC:** Alchemy configured / using public RPCs
+> - **AI:** Anthropic key configured / not configured
+> - **Telegram:** Connected / not configured
+> - **Agent token:** Active
+
+### Onboarding permission reference
+
+| Permission | Why |
+|------------|-----|
+| `secret:read` | Minimal initial setup read access |
+| `secret:write` | Minimal initial setup write access |
+| `trade:all` | Core trading operations (expands to wallet:list, send, swap, fund, etc.) |
+| `apikey:set` | Validate and save API keys during setup |
+| `adapter:manage` | Configure Telegram and other adapters |
+
+`trade:all` does NOT include `apikey:set` or `adapter:manage` — you must request them explicitly.
+
+### CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `npx auramaxx init` | First-time setup — interactive, human-only |
+| `npx auramaxx init --dashboard` | Agent-safe startup — skips prompts, opens dashboard for vault creation |
+| `npx auramaxx init --password "pass"` | Fully autonomous — creates vault non-interactively, prints address + token |
+| `npx auramaxx start` | Start all services (Express + Dashboard + WS) |
+| `npx auramaxx start --headless` | Start server only (no dashboard) |
+| `npx auramaxx stop` | Stop all running services |
+| `npx auramaxx status` | Health check — running? locked? unlocked? |
+| `npx auramaxx auth request --agent-id <id> --profile <profile>` | Request auth + poll approval from CLI |
+| `npx auramaxx diary write --entry "<text>"` | Append a daily diary note via auth-aware CLI flow |
+| `npx auramaxx apikey list|validate|set|delete` | API key management from CLI |
+| `npx auramaxx lock` | Lock all vaults (or `lock vault <id>`) |
+| `npx auramaxx set|get|share|del <name>` | Short aliases for vault get/set/share/delete |
+| `npx auramaxx mcp --install` | Auto-configure MCP for detected IDEs (Claude Desktop, Cursor, VS Code, Windsurf) |
+| `npx auramaxx skill` | Install AuraMaxx skills for Claude/Codex/OpenClaw agents |
+| `npx auramaxx skill --doctor` | Verify skill install status across all targets |
+| `npx auramaxx experimental` | List dev feature flags and current values |
+| `npx auramaxx experimental <FLAG> <on\|off>` | Toggle a dev feature flag |
+| `npx auramaxx doctor` | Run onboarding/runtime diagnostics |
+| `npx auramaxx start --debug` | Start with verbose bootstrap output |
+
+---
+
+### Operations Mode (normal use)
+
+After Setup Mode succeeds, switch to Operations Mode for routine authenticated wallet and credential operations.
+
+## Authentication
+
+All agent operations require a Bearer token. Prefer CLI polling flow first:
+
+```bash
+npx auramaxx auth request --agent-id my-trading-bot --profile strict
+```
+
+This does:
+1) `POST /auth` with a generated `pubkey`
+2) polls `GET /auth/:requestId?secret=...`
+3) exits on `approved`, `rejected`, or timeout
+
+Polling controls:
+
+- `--no-wait` (create request only)
+- `--interval-ms <ms>`
+- `--timeout-ms <ms>`
+
+Approval response contract:
+
+- `pending` -> keep polling
+- `approved` -> response includes `encryptedToken` (read-once claim); CLI decrypts locally
+- `rejected` -> stop and surface rejection
+
+For non-CLI/manual calls, keep using `POST /auth` + `GET /auth/:requestId?secret=...`.
+
+---
+
+## Common Operations
+
+### List Wallets
+
+```
+api GET /wallets
+```
+
+Response: array of wallet objects with `address`, `name`, `tier`, `chain`, `balance`.
+
+### Create Hot Wallet
+
+```
+api POST /wallet/create
+body: { "tier": "hot", "name": "trading", "chain": "base" }
+```
+
+Response: `{ "address": "0x...", "name": "trading", "tier": "hot", "chain": "base" }`
+
+Options: `chain` can be `"base"`, `"ethereum"`, `"solana"`, `"solana-devnet"` (default: `"base"`).
+
+### Launch Token
+
+```
+api POST /launch
+body: {
+  "from": "0xHOT_WALLET",
+  "name": "My Token",
+  "symbol": "MTK",
+  "preset": "medium",
+  "imageUrl": "https://telegra.ph/file/abc.jpg",
+  "metadata": { "description": "A fair launch token" }
+}
+```
+
+Response: `{ "success": true, "txHash": "0x...", "tokenAddress": "0x..." }`
+
+Launches via [Doppler](https://doppler.lol) fair launch. Requires `launch` permission.
+
+Options: `type` (`"multicurve"`, `"static"`, `"dynamic"`), `preset` (`"low"`, `"medium"`, `"high"`), `initialSupply`, `tokenURI`, `chain`.
+
+**Token image:** Upload the image to a free host like [telegra.ph](https://telegra.ph) (no API key needed: `POST https://telegra.ph/upload` with multipart file) and pass the public URL as `imageUrl`. The server builds the on-chain metadata automatically. Use `metadata` for extra fields like `description`, `website`, `twitter`.
+
+### Enable Agent Chat via Telegram
+
+When setting up Telegram, ask the user if they want to chat with their AI agent via Telegram. If yes, include `chat: { enabled: true }` in the adapter config:
+
+```
+api POST /adapters
+body: {
+  "type": "telegram",
+  "enabled": true,
+  "config": { "chatId": "CHAT_ID" },
+  "chat": { "enabled": true }
+}
+```
+
+Then set a default app for chat routing:
+
+```
+api POST /adapters/chat
+body: { "defaultApp": "swap-chat" }
+```
+
+The user can then send text messages in Telegram and the AI agent will reply.
+
+### Estimate Gas (no auth required)
+
+```
+api POST /send/estimate
+body: { "from": "0xWALLET", "to": "0xRECIPIENT", "amount": "50000000000000000" }
+```
+
+Response: `{ "success": true, "gasLimit": "...", "estimatedCostEth": "0.000042" }`
+
+### Check Token Permissions
+
+```
+api POST /auth/validate
+body: { "token": "YOUR_TOKEN" }
+```
+
+Response: `{ "valid": true, "payload": { "permissions": [...], "limits": {...} } }`
+
+### Transaction History
+
+```
+api GET /wallet/0xADDRESS/transactions
+```
+
+Query params: `type` (send, receive, swap, contract), `status`, `limit`, `offset`.
+
+### Asset Tracking
+
+```
+api GET /wallet/0xADDRESS/assets
+```
+
+Returns tracked token balances for the wallet.
+
+---
+
+## Permission Denied (403)
+
+When any CLI command or MCP tool returns 403, the response includes structured guidance with a `nextStep` field. Follow it — it tells you exactly what to do.
+
+Typically:
+```bash
+npx auramaxx auth request --profile strict
+```
+
+This requests a new token with the required permissions. Approve in the dashboard, then retry your command.
+
+> **Note:** The `request_human_action` tool is only available in strategy engine Tool-Call/Hook mode (see below).
+
+---
+
+## Permissions Quick Reference
+
+| Permission | Description |
+|------------|-------------|
+| `trade:all` | **Recommended** — Expands to: `wallet:list`, `wallet:create:hot`, `wallet:create:temp`, `send:hot`, `send:temp`, `swap`, `fund`, `launch`, `apikey:get`, `strategy:read` |
+| `wallet:create:hot` | Create hot wallets |
+| `wallet:create:temp` | Create temp wallets |
+| `wallet:list` | List wallets |
+| `send:hot` | Send from hot wallets |
+| `send:temp` | Send from temp wallets |
+| `swap` | Execute token swaps |
+| `fund` | Transfer from cold to hot |
+| `launch` | Launch tokens via Doppler |
+| `strategy:read` | Read strategy state |
+| `strategy:manage` | Manage strategies (toggle, config, approve) |
+| `workspace:modify` | Modify dashboard UI |
+| `app:storage` | Read/write own app storage |
+
+For full permissions reference, see [docs/AUTH.md](./docs/AUTH.md).
+
+---
+
+## Wallet Tiers
+
+| Tier | Ownership | Use Case |
+|------|-----------|----------|
+| **COLD** | Human only | Main funds, requires password |
+| **HOT** | Token-owned | Agent operations, spending limits |
+| **TEMP** | Ephemeral | One-time use, memory only |
+
+---
+
+## Vault Unlock
+
+If the vault is locked (`api GET /wallets` returns 401):
+
+**Option 1 (preferred):** Tell the human to open `http://localhost:4747` and enter their password. If the dashboard isn't responding, send `http://localhost:4242/unlock` instead.
+
+**Option 2 (remote/headless):** Ask the human for their password and unlock programmatically:
+
+```bash
+node -e "
+  const crypto = require('crypto');
+  (async () => {
+    const pk = await (await fetch('http://localhost:4242/auth/connect')).json();
+    const enc = crypto.publicEncrypt(
+      { key: pk.publicKey, padding: crypto.constants.RSA_PKCS1_OAEP_PADDING, oaepHash: 'sha256' },
+      Buffer.from('PASSWORD_HERE')
+    ).toString('base64');
+    const agent = crypto.generateKeyPairSync('rsa', {
+      modulusLength: 2048,
+      publicKeyEncoding: { type: 'spki', format: 'pem' },
+      privateKeyEncoding: { type: 'pkcs8', format: 'pem' }
+    });
+    const r = await (await fetch('http://localhost:4242/unlock', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ encrypted: enc, pubkey: agent.publicKey })
+    })).json();
+    console.log(JSON.stringify(r));
+  })();
+"
+```
+
+On success, the response includes an admin token.
+
+---
+
+## Error Recovery
+
+| Error | Meaning | What to Do |
+|-------|---------|------------|
+| Connection refused | Server not running | Run `npx auramaxx start --headless` to start it. If that fails, tell the human. |
+| 401 `Invalid or expired token` | Server restarted or TTL expired | Re-request via `POST /auth` |
+| 401 `Cold wallet must be unlocked` | Vault locked | Tell human to unlock in dashboard at `http://localhost:4747/` (or `npx auramaxx unlock` in headless mode) |
+| 403 `Insufficient permissions` | Token lacks permission | Follow the `nextStep` in the 403 response, or run `npx auramaxx auth request --profile strict` |
+| 403 `Amount exceeds spending limit` | Budget exhausted | Follow the `nextStep` in the 403 response, or request a new token via `npx auramaxx auth request --profile strict` |
+| 400 `slippage is required` | Missing on swap | Add `"slippage": 1.0` |
+
+---
+
+## Key Concepts
+
+- **Tokens are memory-only** — Server restart invalidates all tokens. Re-request via `POST /auth`.
+- **Spending limits** — Optional per-type caps in the auth request: `limits: { fund: 0.5, send: 1.0, swap: 2.0 }`
+- **Wallet ownership** — Agents can only access wallets they created (or those listed in `walletAccess`)
+- **Human approval** — All token requests require human approval
+- **Multi-chain** — Pass `"chain": "ethereum"` or `"chain": "solana"` on create/send/swap/fund (default: base)
+- **403 recovery** — When you hit 403, follow the `nextStep` in the structured error response
+
+---
+
+## Curl Fallback
+
+If CLI commands are unavailable, use curl directly:
+
+```bash
+# Health check
+curl -s http://localhost:4242/health
+
+# Request token
+curl -X POST http://localhost:4242/auth \
+  -H "Content-Type: application/json" \
+  -d '{"agentId": "my-agent", "limit": 0.5, "permissions": ["trade:all"], "ttl": 3600, "pubkey": "<RSA public key PEM or base64>"}'
+
+# Use token
+curl http://localhost:4242/wallets -H "Authorization: Bearer $TOKEN"
+
+# Send
+curl -X POST http://localhost:4242/send \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"from": "0xWALLET", "to": "0xRECIPIENT", "amount": "50000000000000000"}'
+```
+
+---
+
+## Tool-Call Mode (Chat / Message Hooks)
+
+> **Name note:** The strategy engine provides `wallet_api` and `request_human_action` as tool names in this mode. These are internal strategy engine names, distinct from the MCP tool names (`api`, `auth`, etc.).
+
+### Response format
+Return a JSON object with: reply, state, emit (all optional). No intents needed.
+
+```json
+{
+  "reply": "Your response to the user",
+  "state": { "key": "updated values" },
+  "emit": { "channel": "event-name", "data": { ... } }
+}
+```
+
+### Available tools
+
+#### wallet_api
+Call the AuraMaxx API for reads and writes.
+- wallet_api({ method: "GET", endpoint: "/wallets" }) — list wallets
+- wallet_api({ method: "GET", endpoint: "/wallet/<address>/assets" }) — get balances
+- wallet_api({ method: "POST", endpoint: "/swap", body: {...} }) — execute a swap
+
+#### request_human_action
+Request human approval for a privileged action. Use this when wallet_api returns 403.
+- summary: human-readable description (shown in approval card)
+- permissions: array of permission strings needed (e.g. ["swap"], ["send:hot"])
+- action: pre-computed API call { endpoint, method, body }
+- limits: spending caps per permission (e.g. { swap: 0.01 })
+- walletAccess: wallet addresses the temp token needs access to (e.g. ["0x123...", "0x456..."]). Include ALL wallet addresses involved in the action (from + to).
+- ttl: seconds the temp token lives (default 120)
+
+### Token discovery (ticker/name -> contract)
+
+When the user gives a token ticker or name but no contract address:
+
+1. Call `wallet_api({ method: "GET", endpoint: "/token/search?q=<query>&chain=<chain>" })`
+2. If results exist, present the best candidate(s) with contract addresses and ask for confirmation only if ambiguous
+3. Only ask the user for a contract address when search returns no reliable results
+
+Never tell the user to search external websites first without trying `/token/search`.
+
+### Performing Actions
+
+Follow this flow for any privileged operation:
+
+1. **Try the action directly** via wallet_api (POST)
+2. **If you get 403** (insufficient permissions), call request_human_action with:
+   - A clear summary of what you want to do
+   - The permissions you need
+   - The exact API call to execute on approval
+3. **The human approves** → the action auto-executes with a scoped temporary token
+4. **NEVER give up** or say "I don't have permission." Always use request_human_action.
+
+Example flow:
+- User: "Swap 0.01 ETH for USDC"
+- You: call wallet_api GET /wallets to find the hot wallet
+- You: call wallet_api POST /swap with the swap params
+- Response: 403 → call request_human_action with summary, permissions: ["swap"], action: { endpoint: "/swap", method: "POST", body: {...} }
+- Reply: "I've requested approval to swap 0.01 ETH for USDC. Waiting for your confirmation."
+
+### Permission → Endpoint mapping (for request_human_action)
+
+Use EXACTLY these permission strings — other strings will be rejected:
+
+| Permission | Endpoint |
+|------------|----------|
+| swap | /swap |
+| send:hot | /send |
+| send:temp | /send |
+| fund | /fund |
+| launch | /launch |
+| wallet:create:hot | /wallet/create |
+| wallet:create:temp | /wallet/create |
+
+### Multi-step operations
+
+When a task requires multiple privileged steps (e.g., "send ETH to 0x..."):
+
+1. **Check existing wallets first** — call wallet_api GET /wallets before creating new ones
+2. **Plan all steps** — identify all permissions needed upfront
+3. **Request ONE approval** with all permissions needed for the entire flow
+   - Example: permissions: ["wallet:create:hot", "fund", "send:hot"]
+   - The action should be the FIRST step (e.g., create wallet)
+4. **On success callback, continue** — use wallet_api and request_human_action for remaining steps
+
+Common multi-step flows:
+- "Send ETH to external address" → fund existing hot wallet from cold (/fund), then send (/send)
+- "Create wallet and fund it" → create hot wallet (/wallet/create), then fund from cold (/fund)
+- Gas: always account for gas fees (~0.0002 ETH on Base) when funding for a send
+
+### Error recovery
+
+When an action fails after approval (you receive a [SYSTEM] message with an error):
+
+1. **Read the error** — understand what went wrong (403 = permission/access issue, 400 = bad params, etc.)
+2. **Investigate** — call wallet_api to gather info (e.g. GET /wallets to check addresses, tiers, ownership)
+3. **Retry** — call request_human_action again with corrected parameters
+4. **NEVER just explain the error** — always try to fix it first
+
+Common fixes:
+- "Token does not have access to this wallet" → include walletAccess in request_human_action with the wallet addresses involved
+- "insufficient funds" → check balances and adjust amount
+- Wrong wallet type → check wallet tiers with GET /wallets and pick the right one
+
+### Wallet tiers
+- COLD: Human-only, never use for agent operations
+- HOT: Agent-accessible, use for swaps/sends/funding
+- TEMP: Ephemeral, agent full control
+
+### Authentication & Permissions
+
+Your pre-approved permissions and spending budget are in the context:
+- `context.permissions` — array of permissions your app token already has
+- `context.budget.limits` — spending caps per permission (ETH)
+- `context.budget.spent` — amount used this session
+- `context.budget.remaining` — amount left before limit is hit
+
+If your token already has the needed permission AND sufficient budget, wallet_api will succeed directly.
+If not, use request_human_action to get a scoped temporary token via human approval.
+
+---
+
+## Intent Mode (Tick / Strategy Hooks)
+
+### Response format
+Return a JSON object with: reply, state, intents, emit (all optional).
+
+### Intent format for privileged actions
+To execute wallet operations, return intents with a permissions array.
+The engine will request human approval and create a scoped temporary token.
+
+```json
+{
+  "intents": [{
+    "type": "swap",
+    "summary": "Human-readable description of the action",
+    "permissions": ["swap"],
+    "limits": { "swap": 0.01 },
+    "ttl": 120,
+    "action": { "endpoint": "/swap", "method": "POST", "body": { ... } }
+  }]
+}
+```
+
+- permissions: array of permission strings needed (swap, send:hot, fund, etc.)
+- limits: spending caps per permission (in native currency)
+- ttl: seconds the temp token lives (default 60)
+- action: pre-computed API call the engine will execute with the temp token
+- summary: shown to human in the approval card
+
+### Wallet tiers
+- COLD: Human-only, cannot be used in intents
+- HOT: Agent-accessible, use for swaps/sends/funding
+- TEMP: Ephemeral, agent full control
+
+### Authentication & Permissions
+
+Your pre-approved permissions and spending budget are in the context:
+- `context.permissions` — array of permissions your app token already has
+- `context.budget.limits` — spending caps per permission (ETH)
+- `context.budget.spent` — amount used this session
+- `context.budget.remaining` — amount left before limit is hit
+
+#### Decision logic for intents:
+
+1. **Permission exists AND remaining >= amount needed**
+   → Return intent WITHOUT `permissions` array. The engine uses your existing token.
+   ```json
+   { "type": "swap", "action": { "endpoint": "/swap", ... } }
+   ```
+
+2. **Permission exists BUT remaining < amount needed**
+   → Return intent WITH permissions array to request a fresh per-action token with a higher limit.
+   ```json
+   { "type": "swap", "summary": "Buy 0.5 ETH of TOKEN (exceeds session budget, needs approval)",
+     "permissions": ["swap"], "limits": { "swap": 0.5 }, "ttl": 120,
+     "action": { "endpoint": "/swap", ... } }
+   ```
+
+3. **Permission does NOT exist**
+   → Return intent WITH permissions array. Human must approve.
+   ```json
+   { "type": "swap", "summary": "Buy 0.1 ETH of TOKEN",
+     "permissions": ["swap"], "limits": { "swap": 0.1 }, "ttl": 120,
+     "action": { "endpoint": "/swap", ... } }
+   ```
+
+Never propose an action that exceeds context.budget.remaining without requesting
+a new per-action token via the permissions array.
+
+The executor handles authentication — hooks never see bearer tokens.
+Just return the endpoint/method/body in your intent and the engine does the rest.
+
+---
+
+## Reference Documentation (bundled with skill payload)
+
+- [docs/API.md](./docs/API.md) - Full HTTP endpoint reference
+- [docs/AUTH.md](./docs/AUTH.md) - Complete permissions & token lifecycle
+- [docs/MCP.md](./docs/MCP.md) - MCP server setup & bootstrap flow
+- [docs/AGENT_SETUP.md](./docs/AGENT_SETUP.md) - End-to-end setup guide
+- [docs/WORKSPACE.md](./docs/WORKSPACE.md) - WebSocket dashboard control
+- [docs/CLI.md](./docs/CLI.md) - Headless CLI mode & Unix socket IPC
+- [docs/security.md](./docs/security.md) - Security architecture