@towns-labs/wallet 7.2.0 → 7.3.1

package/README.md

@@ -1,74 +1,64 @@
-# towns wallet-cli
+# tw — Towns Wallet CLI
 
-CLI for `tw` account onboarding, session key lifecycle, and relayed transactions.
+Your keys. Your account. No signup. No login. Just run it.
 
-Built on [incur](https://github.com/wevm/incur) — every command supports `--help`, `--json`, `--format`, and can run as an MCP server via `--mcp`.
-
-## Run with bunx
+`tw` is a local-first CLI for managing smart accounts, session keys, and on-chain permissions on Towns Protocol. It works for humans at the terminal and for agents over `--json` or `--mcp`.
 
 ```bash
 bunx @towns-labs/wallet --help
 ```
 
-## Permissionless
+---
 
-`tw` is fully permissionless: no signup, no account registration, and no login flow. You can run it immediately with local keys.
+## Quick Start
 
-## Output Modes
+Create an account and send USDC in under a minute:
 
-incur handles output formatting automatically:
+```bash
+# 1. Create a local account (interactive password prompt)
+tw account create --profile main
 
-- `--json` — structured JSON output
-- `--format table` — tabular output
-- Default: human-readable text
+# 2. Fund it
+tw address --qr --amount 100
 
-## Help and Discovery
+# 3. Send USDC
+tw account send 10 vitalik.eth
+```
 
-```bash
-# Show all commands
-tw --help
+No custody service. No API key. Everything runs locally with encrypted keystores.
 
-# Show help for a specific command
-tw account create --help
+---
 
-# Machine-readable command manifest (for LLMs/agents)
-tw --llms
+## How It Works
 
-# Run as an MCP server
-tw --mcp
+`tw` manages a local keystore that holds your root key and session keys. Your root key creates and controls your on-chain smart account. Session keys are scoped signers — they can send transactions through the Towns relayer without exposing your root key.
 
-# Version
-tw --version
+```text
+~/.config/towns/tw/profiles/<env>/<profile>/default.keystore.json
+~/.config/towns/tw/profiles/<env>/<profile>/sessions/<session-name>.json
 ```
 
-## Account Create
+For agents, the session daemon keeps decrypted keys in memory for a bounded duration so automated workflows can sign without prompting for a password on every call.
 
-Create a new account (interactive password prompt):
+---
 
-```bash
-tw account create
-```
+## Commands
+
+### Account
 
-Create a named profile:
+#### `account create` — Create a new account
 
 ```bash
 tw account create --profile agent
 ```
 
-Keystore layout:
-
-```text
-~/.config/towns/tw/profiles/<env>/<profile>/default.keystore.json
-~/.config/towns/tw/profiles/<env>/<profile>/sessions/<session-name>.json
-```
-
-Resume a previously created profile:
+Resume a previously interrupted flow:
 
 ```bash
 tw account create --resume --profile agent
 ```
 
-Non-interactive mode (stdin password + JSON output):
+Non-interactive (stdin password + JSON):
 
 ```bash
 echo "my-password" | tw account create --password-stdin --json
@@ -80,461 +70,446 @@ Use an explicit keystore path:
 tw account create --keystore-path ~/.config/towns/tw/profiles/prod/team/default.keystore.json
 ```
 
-## Account Export
-
-Export metadata only (safe default):
+#### `account status` — Check readiness
 
 ```bash
-tw account export --profile agent
+tw account status --profile agent --json
 ```
 
-Export metadata in JSON:
+#### `account balance` — Check USDC balance
 
 ```bash
-tw account export --profile agent --json
+tw account balance --profile agent
+tw account balance --profile agent --chain polygon
 ```
 
-Export decrypted private keys (interactive confirmation required):
+#### `account address` — Print root address
 
 ```bash
-tw account export --profile agent --show-private
+tw account address --profile agent
 ```
 
-## Account Address
-
-Print the main/root account address:
+#### `account send` — Send USDC
 
 ```bash
-tw account address --profile agent
+tw account send 1 0x1111111111111111111111111111111111111111
+tw account send 2.5 vitalik.eth --chain base
+tw account send 10 treasury --chain polygon --json
 ```
 
-## Address (Root Alias)
-
-`tw address` is a root alias for `tw account address` with optional funding display helpers.
-
-Print address + default funding context (USDC on Base):
+Use a specific local session (without changing active session):
 
 ```bash
-tw address
+tw account send 1 0x... --profile agent --session worker-2
 ```
 
-Show a funding payment link:
+Use a portable session file (no root keystore required):
 
 ```bash
-tw address --link --amount 100
+tw account send 1 0x... --chain base --session-file ./worker-1.session.json
 ```
 
-Show a QR for the same payment payload:
+`--session` and `--session-file` are mutually exclusive.
+
+#### `account swap` — Swap tokens on the same chain
+
+Powered by [relay.link](https://relay.link). Interactive confirmation by default.
 
 ```bash
-tw address --qr --amount 100
+tw account swap --from ETH --to USDC --amount 0.1 --chain base
+tw account swap --from USDC --to ETH --amount 50 --chain base --yes --json
 ```
 
-Custom token amount requires explicit decimals:
+#### `account bridge` — Bridge tokens cross-chain
 
 ```bash
-tw address --token 0x1111111111111111111111111111111111111111 --amount 1 --decimals 18 --link
+tw account bridge --token USDC --amount 100 --to-chain polygon
+tw account bridge --token ETH --amount 0.5 --to-chain base --recipient 0x... --yes --json
 ```
 
-## Account Balance
+#### `account delegate` — Delegate on additional chains
 
-Check USDC balance for the main/root account on Base (default):
+If your account was created on Base and you need it on Polygon:
 
 ```bash
-tw account balance --profile agent
+echo "my-password" | tw account delegate --chain polygon --profile agent --password-stdin
 ```
 
-Check USDC balance on Polygon:
+#### `account history` — Relayer call history
 
 ```bash
-tw account balance --profile agent --chain polygon
+tw account history --profile agent
+tw account history --address 0x... --limit 10 --offset 20
+tw account history --chain base,polygon --json
 ```
 
-## Account Send
+`--limit` defaults to 20 (max 100). `offset + limit` must be <= 1000.
 
-Send USDC to an address:
+#### `account export` — Export metadata or private keys
 
 ```bash
-tw account send 1 0x1111111111111111111111111111111111111111
+tw account export --profile agent --json
+tw account export --profile agent --show-private
 ```
 
-Send USDC to ENS on Base:
+#### `account nonce` — Read account nonce
 
 ```bash
-tw account send 2.5 vitalik.eth --chain base
+tw account nonce --profile agent
 ```
 
-Send USDC on Polygon with JSON output:
+#### `account update password` — Rotate keystore password
 
 ```bash
-tw account send 10 0x1111111111111111111111111111111111111111 --chain polygon --json
+tw account update password --profile agent
+printf "old\nnew\n" | tw account update password --current-password-stdin --new-password-stdin --json
 ```
 
-Send using a specific local session by name (without changing active session):
+---
 
-```bash
-tw account send 1 0x1111111111111111111111111111111111111111 --profile agent --session worker-2
-```
+### Address
 
-## Account History
-
-Get paginated relayer call history for an EOA. By default this uses your local profile root EOA from keystore:
+`tw address` is a top-level shortcut for showing your funding address with optional payment helpers.
 
 ```bash
-tw account history --profile agent
+tw address
+tw address --link --amount 100
+tw address --qr --amount 100
 ```
 
-Query an explicit EOA (without reading local keystore):
+Custom token:
 
 ```bash
-tw account history --address 0x1111111111111111111111111111111111111111 --limit 10 --offset 20
+tw address --token 0x... --amount 1 --decimals 18 --link
 ```
 
-Filter by one or more chains:
-
-```bash
-tw account history --chain base,polygon --json
-```
+---
 
-Notes:
+### Session Keys
 
-- `--limit` defaults to `20` and max is `100`
-- `--offset` defaults to `0`
-- `offset + limit` must be `<= 1000`
-- History queries are EOA-based (root EOA), not delegated account address
+Session keys are scoped signers that can act on behalf of your account without exposing the root key.
 
-## Contacts
+#### `session create` — Create and authorize a session key
 
-Store aliases in a global contacts file:
-
-```text
-~/.config/towns/tw/contacts.json
+```bash
+echo "my-password" | tw session create worker-1 --profile agent --password-stdin --json
 ```
 
-Add contact aliases:
+Create and activate immediately:
 
 ```bash
-tw contacts add vitalik vitalik.eth
-tw contacts add treasury 0x1111111111111111111111111111111111111111
+echo "my-password" | tw session create worker-2 --profile agent --activate --password-stdin
 ```
 
-List or show contacts:
+Grant full wildcard access:
 
 ```bash
-tw contacts list --json
-tw contacts show vitalik --json
+echo "my-password" | tw session create worker-admin --profile agent --full-access --password-stdin
 ```
 
-Update, rename, and remove:
+`--full-access` is mutually exclusive with `--target`, `--selector`, `--spend-limit`, `--spend-limit-raw`, and `--spend-period`. Omitting both `--target` and `--selector` uses wildcard call permissions by default.
+
+Resume an interrupted flow:
 
 ```bash
-tw contacts update vitalik 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
-tw contacts rename vitalik vitalik-main
-tw contacts remove vitalik-main
+echo "my-password" | tw session create worker-1 --profile agent --resume --password-stdin --json
 ```
 
-Export and import:
+Create a session and initialize agent messaging in one step:
 
 ```bash
-tw contacts export --json
-tw contacts import ./contacts.json --json
-tw contacts import ./contacts.json --force --json
+echo "my-password" | tw session create alice --profile agent --agent --password-stdin
 ```
 
-Import returns deterministic summary fields:
-
-- `importedCount`
-- `skippedInvalidCount`
-- `skippedConflictCount`
-- `overwrittenCount`
-
-Send via alias:
+#### `session list` — List local sessions
 
 ```bash
-tw account send 10 vitalik
+tw session list --profile agent --json
+tw session list --profile agent --on-chain --json
 ```
 
-ENS safety behavior for ENS-backed contacts:
+#### `session rotate` — Rotate the active session
 
-- If ENS re-resolution fails, `tw account send` falls back to the stored address.
-- If ENS re-resolution succeeds but points to a different address than stored, send aborts and requires explicit `tw contacts update`.
+```bash
+echo "my-password" | tw session rotate --profile agent --password-stdin --json
+echo "my-password" | tw session rotate --profile agent --new-name worker-3 --password-stdin
+echo "my-password" | tw session rotate --profile agent --resume --password-stdin --json
+```
 
-Send with a portable session file (no root keystore required):
+#### `session revoke` — Revoke a session on-chain
 
 ```bash
-tw account send 1 0x1111111111111111111111111111111111111111 \
-  --chain base --session-file ./worker-1.session.json
+echo "my-password" | tw session revoke worker-1 --profile agent --password-stdin --json
+echo "my-password" | tw session revoke worker-2 --profile agent --force --password-stdin
+echo "my-password" | tw session revoke worker-2 --profile agent --resume --password-stdin --json
 ```
 
-`--session` and `--session-file` are mutually exclusive.
-
-## Account Status
+Agent sessions require `--force` and clean up local channel bindings as part of revocation.
 
-Show compact readiness status:
+#### `session export` — Export as portable file
 
 ```bash
-tw account status --profile agent
+TW_PASSWORD="my-password" TW_EXPORT_PASSWORD="export-password" \
+  tw session export worker-1 --profile agent --output ./worker-1.session.json
 ```
 
-JSON output for automation:
+Or via stdin:
 
 ```bash
-tw account status --profile agent --chain polygon --json
+echo "export-password" | tw session export worker-1 --profile agent \
+  --output ./worker-1.session.json --export-password-stdin
 ```
 
-## Account Update Password
-
-Rotate local keystore encryption password (interactive):
+#### `session import` — Import a portable session
 
 ```bash
-tw account update password --profile agent
+tw session import ./worker-1.session.json --profile worker-1
 ```
 
-Rotate password non-interactively using stdin lines:
+Creates a session-only profile that can execute `account send` but cannot run manager commands requiring a root keystore.
 
-```bash
-printf "old-password\nnew-password\n" | tw account update password --current-password-stdin --new-password-stdin --json
-```
+---
+
+### Session Daemon
 
-## Session Create
+The daemon holds decrypted session keys in memory so automated workflows can sign without re-entering passwords.
 
-Create and authorize a scoped session key in one intent:
+#### `session start` — Start the daemon
 
 ```bash
-echo "my-password" | tw session create worker-1 --profile agent --password-stdin --json
+tw session start --json
+tw session start --foreground --json
 ```
 
-Create and activate immediately:
+Idempotent — if already running, returns the active pid/socket.
+
+#### `session unlock` — Load a key into daemon memory
 
 ```bash
-echo "my-password" | tw session create worker-2 --profile agent --activate --password-stdin
+echo "my-password" | tw session unlock worker-1 --profile agent --password-stdin --duration 15m --json
 ```
 
-Resume a previously interrupted create flow:
+Key material stays in daemon memory only; encrypted files remain unchanged.
+
+#### `session lock` — Remove a key from daemon memory
 
 ```bash
-echo "my-password" | tw session create worker-1 --profile agent --resume --password-stdin --json
+tw session lock worker-1 --json
 ```
 
-Grant full wildcard access (explicit opt-in):
+#### `session status` — Check daemon health
 
 ```bash
-echo "my-password" | tw session create worker-admin --profile agent --full-access --password-stdin
+tw session status --json
 ```
 
-`--full-access` is mutually exclusive with `--target`, `--selector`, `--spend-limit`, `--spend-limit-raw`, and `--spend-period`.
-Omitting both `--target` and `--selector` uses wildcard call permissions by default; you do not need to pass magic wildcard values.
-`--spend-limit` accepts human USDC amounts (for example `10` = `10 USDC`). Use `--spend-limit-raw` for base units.
-
-## Session List
-
-List local sessions:
+#### `session stop` — Shut down the daemon
 
 ```bash
-tw session list --profile agent --json
+tw session stop --json
 ```
 
-Include on-chain key status:
+---
 
-```bash
-tw session list --profile agent --on-chain --json
-```
+### Permissions
 
-## Session Export
+Fine-grained on-chain permission rules for session keys.
 
-Export a session key as a portable file:
+#### `permissions list` — List keys and their permissions
 
 ```bash
-TW_PASSWORD="my-password" TW_EXPORT_PASSWORD="export-password" \
-  tw session export worker-1 --profile agent --output ./worker-1.session.json
+tw permissions list --profile agent --json
 ```
 
-Or provide the export password via stdin:
+#### `permissions show` — Show rules for a specific key
 
 ```bash
-echo "export-password" | tw session export worker-1 --profile agent \
-  --output ./worker-1.session.json --export-password-stdin
+tw permissions show agent-key --profile agent --json
+tw permissions show --key-hash 0xaaa... --profile agent --json
 ```
 
-## Session Import
+#### `permissions grant` — Grant a permission rule
 
-Import a portable session as a session-only profile:
+Wildcard call permission:
 
 ```bash
-tw session import ./worker-1.session.json --profile worker-1
+echo "my-password" | tw permissions grant agent-key --type call --target any --selector any --profile agent --password-stdin --json
 ```
 
-This creates:
+Daily USDC spend limit:
 
 ```bash
-~/.config/towns/tw/profiles/worker-1/session.json
+echo "my-password" | tw permissions grant agent-key --type spend --token USDC --spend-limit 100 --period day --profile agent --password-stdin --json
 ```
 
-Session-only profiles can execute `account send` but cannot run manager commands that require a root keystore.
+Use `--spend-limit-raw` for base units instead of human amounts.
 
-## Session Rotate
+#### `permissions revoke` — Revoke permission rules
 
-Rotate the active session (auto-generates new name):
+Revoke a single rule:
 
 ```bash
-echo "my-password" | tw session rotate --profile agent --password-stdin --json
+echo "my-password" | tw permissions revoke agent-key --rule call:0x...:0xa9059cbb --profile agent --password-stdin --json
 ```
 
-Rotate to an explicit new session name:
+Revoke all rules for a key:
 
 ```bash
-echo "my-password" | tw session rotate --profile agent --new-name worker-3 --password-stdin
+echo "my-password" | tw permissions revoke agent-key --all --profile agent --password-stdin --json
 ```
 
-`--full-access` is mutually exclusive with `--target`, `--selector`, `--spend-limit`, `--spend-limit-raw`, and `--spend-period`.
-Omitting both `--target` and `--selector` uses wildcard call permissions by default; you do not need to pass magic wildcard values.
-`--spend-limit` accepts human USDC amounts (for example `10` = `10 USDC`). Use `--spend-limit-raw` for base units.
+---
 
-Resume interrupted rotation:
-
-```bash
-echo "my-password" | tw session rotate --profile agent --resume --password-stdin --json
-```
+### Escrow
 
-## Session Revoke
+USDC escrow: lock funds as buyer with a seller and oracle; settle (oracle signs) or refund after deadline.
 
-Revoke a non-active session on-chain, verify, then delete local file:
+#### `escrow create` — Create a new USDC escrow
 
 ```bash
-echo "my-password" | tw session revoke worker-1 --profile agent --password-stdin --json
+tw escrow create 50 0x1111111111111111111111111111111111111111 \
+  --oracle 0x2222222222222222222222222222222222222222 --deadline 24h
+tw escrow create 100 0x... --oracle 0x... --deadline 2d --chain base --env prod --json
 ```
 
-Force revoke active session:
+- **Amount** and **seller** are positional; **oracle** and **deadline** are required options.
+- **Deadline**: relative (`1h`, `2d`, `30m`, `1w`) or unix timestamp. After deadline, anyone can call `escrow refund`.
+- Optional **salt** (hex, up to 12 bytes) for unique escrow IDs on repeated orders.
+- Uses session key (daemon or direct) to sign; supports `--session-file` like `account send`.
 
-```bash
-echo "my-password" | tw session revoke worker-2 --profile agent --force --password-stdin
-```
-
-Idempotent retry/cleanup when already revoked on-chain:
+#### `escrow status` — Check on-chain status
 
 ```bash
-echo "my-password" | tw session revoke worker-2 --profile agent --resume --password-stdin --json
+tw escrow status 0x<64 hex chars> --env prod
+tw escrow status 0x... --chain base --json
 ```
 
-## Agent Commands
+Escrow ID must be the full 32-byte hex (0x + 64 hex chars), e.g. from `escrow create` output.
 
-Agents are session-key-backed Towns identities with their own encryption device and named channel bindings.
+#### `escrow settle` — Settle (release USDC to seller)
 
-Agent keystore files live alongside normal sessions:
+Oracle signs a settlement; any account can submit the signed settlement via relayer.
 
-```text
-~/.config/towns/tw/profiles/<env>/<profile>/sessions/agent-<name>.json
-~/.config/towns/tw/profiles/<env>/<profile>/agent-channels.json
+```bash
+TW_ORACLE_PRIVATE_KEY=0x... tw escrow settle 0x<escrowId> \
+  --settlement-id 0x<orderId> --oracle 0x2222... --profile agent
 ```
 
-Create two local agents:
+Or with pre-signed signature (oracle signs offline):
 
 ```bash
-TW_PASSWORD="my-password" tw agent create alice --profile agent
-TW_PASSWORD="my-password" tw agent create bob --profile agent
+tw escrow settle 0x<escrowId> --settlement-id 0x... --oracle 0x... --signature 0x... --profile agent
 ```
 
-List local agents:
+Settlement ID is the bytes32 order ID used at creation (see create output or `escrow status`).
 
-```bash
-TW_PASSWORD="my-password" tw agent list --profile agent --json
-```
+#### `escrow refund` — Refund to buyer after deadline
 
-Create or bind a named channel:
+Permissionless: after the escrow deadline, anyone can trigger refund to the buyer.
 
 ```bash
-TW_PASSWORD="my-password" tw agent connect --from alice --channel art --to bob --profile agent
+tw escrow refund 0x<escrowId> --profile agent
+tw escrow refund 0x<escrowId> --env prod --json
 ```
 
-The first `connect` returns:
+---
 
-- `streamId` — the underlying GDM stream
-- `secret` — the shared rendezvous secret, returned only when the binding is first created
+### Contacts
 
-Bind the same named channel from the other side:
+Store recipient aliases so you never have to copy-paste addresses.
 
-```bash
-TW_PASSWORD="my-password" tw agent connect --from bob --channel art --secret "<shared-secret>" --to alice --profile agent
+```text
+~/.config/towns/tw/contacts.json
 ```
 
-Send to a named channel:
-
 ```bash
-TW_PASSWORD="my-password" tw agent send --from alice --channel art "hello from alice" --profile agent
+tw contacts add vitalik vitalik.eth
+tw contacts add treasury 0x1111111111111111111111111111111111111111
+tw contacts list --json
+tw contacts show vitalik --json
+tw contacts update vitalik 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+tw contacts rename vitalik vitalik-main
+tw contacts remove vitalik-main
 ```
 
-Send directly to a raw stream ID:
+Export and import:
 
 ```bash
-TW_PASSWORD="my-password" tw agent send --from alice 77aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa "debug message" --profile agent
+tw contacts export --json
+tw contacts import ./contacts.json --json
+tw contacts import ./contacts.json --force --json
 ```
 
-Listen on a named channel:
+Import returns `importedCount`, `skippedInvalidCount`, `skippedConflictCount`, and `overwrittenCount`.
+
+Send via alias:
 
 ```bash
-TW_PASSWORD="my-password" tw agent listen --from bob --channel art --profile agent
+tw account send 10 vitalik
 ```
 
-Listen on a specific stream:
+ENS safety: if ENS re-resolves to a different address than stored, send aborts and requires `tw contacts update`.
 
-```bash
-TW_PASSWORD="my-password" tw agent listen --from bob --stream 77aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --profile agent
-```
+---
 
-Inspect local named bindings:
+### Agents
 
-```bash
-TW_PASSWORD="my-password" tw agent channels --from alice --profile agent --json
+Agents are session-key-backed Towns identities with their own encryption device and named channel bindings. Identity management lives under `tw session`; `tw agent` is reserved for messaging commands.
+
+```text
+~/.config/towns/tw/profiles/<env>/<profile>/sessions/<name>.json
+~/.config/towns/tw/profiles/<env>/<profile>/agent-channels.json
 ```
 
-Remove an agent:
+#### `session create --agent` / `agent init` / `session list`
 
 ```bash
-TW_PASSWORD="my-password" tw agent remove bob --profile agent
+TW_PASSWORD="my-password" tw session create alice --profile agent --agent
+TW_PASSWORD="my-password" tw session create bob --profile agent
+TW_PASSWORD="my-password" tw agent init bob --profile agent
+TW_PASSWORD="my-password" tw session list --profile agent --json
 ```
 
-## Agent Quickstart
+`tw session list` includes a `kind` field (`session` or `agent`). Revoke agent identities with `tw session revoke <name> --force`.
 
-This is the shortest end-to-end flow to start a conversation between two local agents.
+Migration note: legacy `agent-<name>.json` files are no longer loaded. Rename them to `<name>.json` manually or recreate them with `tw session create` plus `tw agent init`.
 
-1. Create or reuse a wallet profile:
+#### `agent connect` — Create or bind a named channel
 
-```bash
-tw account create --profile agent
-```
-
-2. Create two agents:
+First side creates the channel and returns the shared secret:
 
 ```bash
-TW_PASSWORD="my-password" tw agent create alice --profile agent
-TW_PASSWORD="my-password" tw agent create bob --profile agent
+TW_PASSWORD="my-password" tw agent connect --from alice --channel art --to bob --profile agent
 ```
 
-3. Create a named channel and copy the returned `secret` and `streamId`:
+Second side binds using that secret:
 
 ```bash
-TW_PASSWORD="my-password" tw agent connect --from alice --channel art --to bob --profile agent
+TW_PASSWORD="my-password" tw agent connect --from bob --channel art --secret "<shared-secret>" --to alice --profile agent
 ```
 
-4. Bind the same channel from Bob using that secret:
+#### `agent send` — Send a message
+
+To a named channel:
 
 ```bash
-TW_PASSWORD="my-password" tw agent connect --from bob --channel art --secret "<shared-secret>" --to alice --profile agent
+TW_PASSWORD="my-password" tw agent send --from alice --channel art "hello from alice" --profile agent
 ```
 
-5. Start a listener in one terminal:
+To a raw stream ID:
 
 ```bash
-TW_PASSWORD="my-password" tw agent listen --from bob --channel art --profile agent
+TW_PASSWORD="my-password" tw agent send --from alice 77aaa... "debug message" --profile agent
 ```
 
-6. Send from another terminal:
+#### `agent listen` — Listen for messages
 
 ```bash
-TW_PASSWORD="my-password" tw agent send --from alice --channel art "hello from alice" --profile agent
+TW_PASSWORD="my-password" tw agent listen --from bob --channel art --profile agent
+TW_PASSWORD="my-password" tw agent listen --from bob --stream 77aaa... --profile agent
 ```
 
-7. Bob's listener prints NDJSON when the message arrives:
+Messages arrive as NDJSON:
 
 ```json
 {
@@ -547,85 +522,71 @@ TW_PASSWORD="my-password" tw agent send --from alice --channel art "hello from a
 }
 ```
 
-8. Inspect the local binding if you need the underlying stream:
+#### `agent channels` — Inspect bindings
 
 ```bash
-TW_PASSWORD="my-password" tw agent channels --from alice --profile agent
-```
-
-For a single-command live verification, run the built-in smoke script:
-
-```bash
-cd packages/wallet
-TW_PASSWORD="my-password" bun run smoke:agent
+TW_PASSWORD="my-password" tw agent channels --from alice --profile agent --json
 ```
 
-## Permissions List
-
-List all on-chain keys with summarized call/spend permissions:
+#### Agent Quickstart
 
 ```bash
-tw permissions list --profile agent --json
-```
-
-## Permissions Show
+# Create profile + two agent sessions
+tw account create --profile agent
+TW_PASSWORD="pw" tw session create alice --profile agent --agent
+TW_PASSWORD="pw" tw session create bob --profile agent
+TW_PASSWORD="pw" tw agent init bob --profile agent
 
-Show full permission rules for a key using positional `<key-ref>`:
+# Alice creates a channel → copy the returned secret
+TW_PASSWORD="pw" tw agent connect --from alice --channel art --to bob --profile agent
 
-```bash
-tw permissions show agent-key --profile agent --json
-```
+# Bob binds with that secret
+TW_PASSWORD="pw" tw agent connect --from bob --channel art --secret "<secret>" --to alice --profile agent
 
-Explicit selectors are also supported:
+# Terminal 1: listen
+TW_PASSWORD="pw" tw agent listen --from bob --channel art --profile agent
 
-```bash
-tw permissions show --key-hash 0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --profile agent --json
+# Terminal 2: send
+TW_PASSWORD="pw" tw agent send --from alice --channel art "hello" --profile agent
 ```
 
-## Permissions Grant
-
-Grant wildcard call permission:
+Smoke test:
 
 ```bash
-echo "my-password" | tw permissions grant agent-key --type call --target any --selector any --profile agent --password-stdin --json
+cd packages/wallet
+TW_PASSWORD="my-password" bun run smoke:agent
 ```
 
-Grant spend permission for daily USDC limit:
+---
 
-```bash
-echo "my-password" | tw permissions grant agent-key --type spend --token USDC --spend-limit 100 --period day --profile agent --password-stdin --json
-```
+## Agent & Automation Integration
 
-For raw base units instead of human USDC amounts, use:
+Every command supports `--json` for machine-readable output. Treat JSON output schemas as the stable contract.
 
 ```bash
-echo "my-password" | tw permissions grant agent-key --type spend --token USDC --spend-limit-raw 100000000 --period day --profile agent --password-stdin --json
+tw <command> --json
 ```
 
-## Permissions Revoke
-
-Revoke one rule by stable rule id:
-
-```bash
-echo "my-password" | tw permissions revoke agent-key --rule call:0x2222222222222222222222222222222222222222:0xa9059cbb --profile agent --password-stdin --json
-```
+### Password Automation
 
-Revoke all call/spend rules for a key:
+Use `TW_PASSWORD` to skip interactive prompts:
 
 ```bash
-echo "my-password" | tw permissions revoke agent-key --all --profile agent --password-stdin --json
+TW_PASSWORD="my-password" tw session list --profile agent --json
 ```
 
-## Password Automation
-
-Use `TW_PASSWORD` for non-interactive flows:
+Or pipe via stdin for commands that accept `--password-stdin`:
 
 ```bash
-TW_PASSWORD="my-password" tw session list --profile agent --json
+echo "my-password" | tw session rotate --profile agent --password-stdin --json
 ```
 
-Stdin is supported for commands requiring keystore decryption/signing:
+### Discovery
 
 ```bash
-echo "my-password" | tw session rotate --profile agent --password-stdin --json
+tw --help              # All commands
+tw account send --help # Command-specific help
+tw --llms              # Machine-readable command manifest
+tw --mcp               # Run as MCP server
+tw --version           # Version
 ```