auramaxx 0.0.12 → 0.0.13

package/skills/auramaxx/SKILL.md

@@ -1,745 +1,125 @@
 ---
 name: auramaxx
 description: |
-  Securely store, retrieve, and share sensitive data with your human.
-  Use when the user asks for credentials, API keys, credit cards, passwords, or any kind of secret that should not be exposed.
-compatibility: Requires Node.js 18+. Network access to RPC endpoints.
+  Minimal AuraMaxx skill: trigger on secret/login intents, then use concrete CLI examples (list -> get/set/inject).
+compatibility: Requires Node.js 18+ with local AuraMaxx runtime.
 allowed-tools: Bash(npx auramaxx *), Bash(auramaxx *), Bash(aura *), Bash(curl *)
 metadata:
   author: auramaxx
-  version: "2.1"
+  version: "3.0"
 ---
 
-# AuraMaxx
+# AuraMaxx (Minimal)
 
-Securely store, retrieve, and share sensitive data with your human. Secrets never leave the machine.
+Use this skill for credential and secret workflows.
 
-| Service | URL |
-|---------|-----|
-| Wallet Server | `http://localhost:4242` |
-| Dashboard UI | `http://localhost:4747` |
-| WebSocket | `ws://localhost:4748` |
+## When To Use
 
-> **SECURITY:** This server runs locally. Never expose these ports to the internet.
+Always use this skill when user intent matches any of these:
 
----
-
-## 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.
+- "log into my <site/service>" (example: "log into my facebook")
+- "what is my <site/service> password"
+- "find my <service> api key/token"
+- "give me my credit card details"
+- "run this command with my <secret>"
 
----
-
-## Modes
-
-Use one skill with two explicit modes:
-- **Setup Mode**: first-time onboarding, agent initialization, unlock recovery, and first scoped token issuance.
-- **Operations Mode**: day-2 wallet work (credentials, send/swap/fund, launch, and approvals).
+## Auth Precedence
 
-### Setup Mode (first run / recovery)
+CLI auth order:
 
-Enter Setup Mode when:
-- the user asks to onboard, initialize, unlock, or bootstrap agent access
-- `GET /setup` reports `hasWallet=false` or `unlocked=false`
+1. `AURA_TOKEN` env
+2. socket bootstrap
+3. `/auth` fallback
 
-Exit Setup Mode only after all are true:
-- `hasWallet=true`
-- `unlocked=true`
-- agent has an active token
+Notes:
 
-#### Setup flow
+- No stored-session fallback in this chain.
+- If `--profile` / `--profile-version` are omitted, CLI resolves from `trust.localProfile` / `trust.localProfileVersion`, then seed defaults (`admin`, `v1`).
+- `AURA_AUTH_PROFILE` / `AURA_AGENT_PROFILE` are not used for CLI fallback profile selection.
 
-On first connect, or when the user asks about setup, run this decision tree:
+## Retrieval Flow (Do This First)
 
-#### Step 1: Check server
+For login/API key/card/password requests:
 
-```
-api GET /health
-```
+1. List first with a scoped query.
+2. Select the matching credential.
+3. Then run `get` (for read) or `inject` (for command execution).
 
-**Connection refused / error:**
-First, try starting the server automatically:
+Examples:
 
 ```bash
-npx auramaxx start --headless
+aura list --name facebook --json
+aura list --name stripe --json
+aura list --name visa --json
 ```
 
-If that succeeds, retry `GET /health`. If it fails (no agent 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 agent 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 agent 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_AGENT_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 agent. 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 agent non-interactively. Store the password for future unlock operations.
-
-**If `unlocked` is false:**
-> "Your agent 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:
+If ambiguous, narrow by field:
 
 ```bash
-npx auramaxx auth request --agent-id claude-assistant --profile strict
+aura list --name facebook --field username --json
 ```
 
-This handles `POST /auth` + polling `GET /auth/:requestId?secret=...` automatically.
+API equivalent:
 
-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>"
-}
+```text
+GET /credentials?q=facebook
 ```
 
-#### 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:"
-> - **Agent:** 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 agent creation |
-| `npx auramaxx init --password "pass"` | Fully autonomous — creates agent 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 agents (or `lock agent <id>`) |
-| `npx auramaxx set|get|share|del <name>` | Short aliases for agent 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:
+## Concrete CLI Examples
 
 ```bash
-npx auramaxx auth request --agent-id my-trading-bot --profile strict
-```
+# Health
 
-This does:
-1) `POST /auth` with a generated `pubkey`
-2) polls `GET /auth/:requestId?secret=...`
-3) exits on `approved`, `rejected`, or timeout
+aura status
 
-Polling controls:
+# List
 
-- `--no-wait` (create request only)
-- `--interval-ms <ms>`
-- `--timeout-ms <ms>`
+aura list
+aura list --name facebook --json
 
-Approval response contract:
+# Read
 
-- `pending` -> keep polling
-- `approved` -> response includes `encryptedToken` (read-once claim); CLI decrypts locally
-- `rejected` -> stop and surface rejection
+aura get FACEBOOK_LOGIN
+aura get FACEBOOK_LOGIN --field password --first
 
-For non-CLI/manual calls, keep using `POST /auth` + `GET /auth/:requestId?secret=...`.
+# Create/update
 
----
+aura set FACEBOOK_LOGIN hunter2 --type login --field password --username alice
+aura set STRIPE_KEY sk_live_123 --type apikey --tags prod,api
 
-## Common Operations
+# Use secret in a command (preferred vs printing)
+aura inject OPENAI_API_KEY --env OPENAI_API_KEY -- node app.js
 
-### List Wallets
+# Share / delete
+aura share FACEBOOK_LOGIN --expires-after 24h
+aura del FACEBOOK_LOGIN
 
-```
-api GET /wallets
+# Approval flow
+aura auth request --agent-id codex --profile dev
+aura auth claim <reqId> --json
+aura get FACEBOOK_LOGIN --reqId <reqId>
 ```
 
-Response: array of wallet objects with `address`, `name`, `tier`, `chain`, `balance`.
+## 403 Handling
 
-### Create Hot Wallet
+If response includes `reqId`:
 
-```
-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"`).
+1. Ask human to approve.
+2. Claim token (`aura auth claim <reqId> --json`).
+3. Retry original command with same `reqId` when required.
 
-### Launch Token
+If 403 has no `reqId`:
 
-```
-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" }
-}
-```
+- Request a new token with least privilege first (`--profile dev`).
+- Use `--profile admin` only when route explicitly requires admin.
 
-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" }
-```
+## Guardrails
 
-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 |
-
----
-
-## Agent Unlock
-
-If the agent 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` | Agent 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.
-
----
+- For commands, use `inject`, not plaintext copy/paste.
+- Do not print secrets unless user explicitly asks for plaintext output.
+- Prefer `aura` alias (`npx auramaxx` equivalent).
 
-## Reference Documentation (bundled with skill payload)
+## Full Reference
 
-- [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
+- CLI examples and command reference: `docs/CLI.md`
+- Auth flow details: `docs/AUTH.md`