feat(kit): repivot public surface to establishWallet + earn primitive

README.md

@@ -14,35 +14,39 @@ Best-execution routing across Jupiter Perps, Pacifica, Drift, and Flash Trade.
 
 Your agent decides. Toreva executes. Every action receipted.
 
-## Agentic perps setup
+## Establish your wallet
 
-Use `toreva_establish` before perps execution when an agent needs delegated
-authority for a human wallet. The standard perps pattern is:
+Use `toreva_establish` to attach a policy-controlled delegated authority to
+your Solana wallet. Your wallet stays the root owner — Toreva creates a bounded
+session key that enforces spend caps, allowed-token constraints, and revocation
+policy. Non-custodial: Toreva never holds private key material. Every
+establishment is receipted.
 
-```text
-human wallet
-  -> Toreva/Swig master authority
-  -> venue-specific child capability
-  -> Pacifica API agent wallet when Pacifica is selected
+```bash
+# Minimum — attach delegated authority to your wallet
+toreva_establish({ walletAddress: "your-wallet-address" })
 ```
 
-The human wallet remains the root owner. The Swig authority is the policy and
-capital-management control layer. Pacifica uses a separate API agent wallet
-because Pacifica REST orders require an on-curve Ed25519 signer. Toreva can
-create, bind, fund, route, monitor, and revoke that child capability through
-Toreva surfaces; the user does not need to open Pacifica.
+Once established, your agent can execute across all supported primitives —
+earn, perps, and more — without re-authenticating for each operation.
 
-For best execution, omit `venue` on `toreva_perps_long` or
-`toreva_perps_short`. Toreva will compare enabled venues and route by estimated
-all-in cost. Set `venue` only when you intentionally want a specific venue.
-Perps tools use the Gateway MCP field contract: `walletAddress`, `token`,
-`sizeUsd`, `leverage`, `collateralToken`, and `collateralAmount`.
+## Earn
 
-The public integration packet lives in this repo:
+Deploy idle USDC to yield across supported venues with `toreva_earn`. Scan,
+compare, and execute from a single tool.
 
-- [Agentic perps integration patterns](./docs/agentic-perps-integration-patterns.md)
-- [OpenAPI-style relay examples](./docs/toreva-perps.openapi.json)
-- [Claude Code agent prompt](./docs/claude-code-agent-prompt.md)
+```bash
+npx toreva earn-compare --asset USDC --venue kamino
+npx toreva earn-compare --asset USDC --venue marginfi
+```
+
+| Venue | Asset |
+| --- | --- |
+| Kamino Finance | USDC |
+| Marginfi | USDC |
+
+Every earn execution returns a read-evidence receipt, a venue-intelligence
+receipt, and a sentinel review receipt.
 
 ## Install
 
@@ -114,6 +118,18 @@ truth for agent, SDK, CLI, Skills, and MCP integration details.
 
 ## Perps tools
 
+Run `toreva_establish` first to attach a delegated authority before execution.
+For best fill, omit `venue` — Toreva compares enabled venues and routes by
+estimated all-in cost. Set `venue` only when you intentionally want a specific
+venue. Perps tools use fields: `walletAddress`, `token`, `sizeUsd`, `leverage`,
+`collateralToken`, and `collateralAmount`.
+
+The public integration packet lives in this repo:
+
+- [Agentic perps integration patterns](./docs/agentic-perps-integration-patterns.md)
+- [OpenAPI-style relay examples](./docs/toreva-perps.openapi.json)
+- [Claude Code agent prompt](./docs/claude-code-agent-prompt.md)
+
 | Tool | Fee | What it does |
 | --- | --- | --- |
 | `toreva_perps_long` | 1 bps | Open long — routes to better fill |

skills/toreva-earn.md

@@ -2,4 +2,25 @@
 
 Non-custodial execution primitives for Solana. Best-execution routing across Jupiter Perps, Pacifica, Drift, and Flash Trade. 1 bps to open. Everything else is free.
 
+Use this skill to scan, compare, and deploy idle USDC into yield positions across supported venues.
+
+**Operations**
+
+- `scan` — survey current USDC yield positions
+- `simulate` — preview expected yield before execution
+- `execute` — deploy USDC to the selected venue
+
+**Supported venues**
+
+| Venue | Asset |
+| --- | --- |
+| Kamino Finance | USDC |
+| Marginfi | USDC |
+
+**Read-only compare** — use `toreva earn-compare` in the CLI or call `toreva_earn`
+with `operation: scan` to compare live APYs before committing capital.
+
+Every execution returns a receipt triple: a read-evidence ID, a
+venue-intelligence receipt, and a sentinel review receipt.
+
 Execution only — not financial advice.

skills/toreva-establish-perps-agent.md

@@ -1,26 +1,42 @@
-# toreva-establish-perps-agent
+# toreva-establish-wallet
 
 Non-custodial execution primitives for Solana. Best-execution routing across Jupiter Perps, Pacifica, Drift, and Flash Trade. 1 bps to open. Everything else is free.
 
-Use this before perps execution when an agent needs a delegated authority graph.
+Use `toreva_establish` to attach a policy-controlled delegated authority to a
+Solana wallet before execution. The wallet holder remains the root owner; Toreva
+creates a bounded session key constrained by spend caps, allowed-token lists, and
+expiry policy. Non-custodial: Toreva never holds private key material. Every
+establishment is receipted and revocable.
 
-Recommended pattern:
+**Minimum call**
+
+Provide `walletAddress`. Capabilities and authority options are optional and
+default to a safe base policy.
+
+**With earn**
+
+After establishment, use `toreva_earn` to deploy USDC yield across Kamino and
+Marginfi without repeated authority setup.
+
+**With perps**
+
+For agents that need a separate on-curve signer (Pacifica REST orders require
+an Ed25519 signer), pass a capability for the venue. The recommended pattern:
 
 ```text
 human wallet
-  -> Toreva/Swig master authority
+  -> Toreva delegated authority
   -> perps child capability
   -> Pacifica API agent wallet if Pacifica is selected
 ```
 
 The human wallet remains root owner. The Pacifica API agent wallet is a
-venue-specific child signer for Pacifica REST orders. It is governed by Toreva
-policy, approvals, receipts, monitoring, and revocation.
+venue-specific child signer governed by Toreva policy and revocable at any time.
 
-For open-long/open-short, omit `venue` unless the user explicitly asks for one.
-Toreva will compare enabled venues and route by estimated all-in cost.
+For open-long/open-short, omit `venue` unless the user explicitly requests one.
+Toreva compares enabled venues and routes by estimated all-in cost.
 
-Use Gateway MCP fields: `walletAddress` for the human wallet, and for opens
-use `token`, `sizeUsd`, `leverage`, `collateralToken`, and `collateralAmount`.
+Use Gateway MCP fields: `walletAddress` for the human wallet; for opens use
+`token`, `sizeUsd`, `leverage`, `collateralToken`, and `collateralAmount`.
 
 Execution only — not financial advice.