feat(compound-v3-plugin): add quickstart command + H2 SUMMARY titles (v0.2.7)

skills/compound-v3-plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "compound-v3",
   "description": "Compound V3 (Comet) lending plugin: supply collateral, borrow/repay the base asset, and claim COMP rewards",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "author": {
     "name": "skylavis-sky",
     "github": "skylavis-sky"

skills/compound-v3-plugin/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "compound-v3-plugin"
-version = "0.2.6"
+version = "0.2.7"
 edition = "2021"
 
 [[bin]]

skills/compound-v3-plugin/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: compound-v3-plugin
 description: "Compound V3 (Comet) lending plugin: supply collateral, borrow/repay the base asset, and claim COMP rewards. Trigger phrases: compound supply, compound borrow, compound repay, compound withdraw, compound rewards, compound position, compound market."
-version: "0.2.6"
+version: "0.2.7"
 author: "skylavis-sky"
 tags:
   - lending
@@ -24,7 +24,7 @@ tags:
 # Check for skill updates (1-hour cache)
 UPDATE_CACHE="$HOME/.plugin-store/update-cache/compound-v3-plugin"
 CACHE_MAX=3600
-LOCAL_VER="0.2.6"
+LOCAL_VER="0.2.7"
 DO_CHECK=true
 
 if [ -f "$UPDATE_CACHE" ]; then
@@ -99,15 +99,15 @@ case "${OS}_${ARCH}" in
   mingw*_aarch64|msys*_aarch64|cygwin*_aarch64)  TARGET="aarch64-pc-windows-msvc"; EXT=".exe" ;;
 esac
 mkdir -p ~/.local/bin
-curl -fsSL "https://github.com/okx/plugin-store/releases/download/plugins/compound-v3-plugin@0.2.6/compound-v3-plugin-${TARGET}${EXT}" -o ~/.local/bin/.compound-v3-plugin-core${EXT}
+curl -fsSL "https://github.com/okx/plugin-store/releases/download/plugins/compound-v3-plugin@0.2.7/compound-v3-plugin-${TARGET}${EXT}" -o ~/.local/bin/.compound-v3-plugin-core${EXT}
 chmod +x ~/.local/bin/.compound-v3-plugin-core${EXT}
 
 # Symlink CLI name to universal launcher
 ln -sf "$LAUNCHER" ~/.local/bin/compound-v3-plugin
 
 # Register version
 mkdir -p "$HOME/.plugin-store/managed"
-echo "0.2.6" > "$HOME/.plugin-store/managed/compound-v3-plugin"
+echo "0.2.7" > "$HOME/.plugin-store/managed/compound-v3-plugin"
 ```
 
 ### Report install (auto-injected, runs once)
@@ -127,7 +127,7 @@ if [ ! -f "$REPORT_FLAG" ]; then
   # Report to Vercel stats
   curl -s -X POST "https://plugin-store-dun.vercel.app/install" \
     -H "Content-Type: application/json" \
-    -d '{"name":"compound-v3-plugin","version":"0.2.6"}' >/dev/null 2>&1 || true
+    -d '{"name":"compound-v3-plugin","version":"0.2.7"}' >/dev/null 2>&1 || true
   # Report to OKX API (with HMAC-signed device token)
   curl -s -X POST "https://www.okx.com/priapi/v1/wallet/plugins/download/report" \
     -H "Content-Type: application/json" \
@@ -301,6 +301,33 @@ Please connect your wallet first: run `onchainos wallet login`
 
 ## Commands
 
+### quickstart — Check state and get a guided next step
+
+```bash
+compound-v3-plugin [--chain 8453] [--market usdc] quickstart [--wallet 0x...]
+```
+
+**Auth required:** No
+
+**How it works:** Queries the Comet contract for `balanceOf` (supply balance) and `borrowBalanceOf` (borrow balance) for the given wallet, in parallel. Emits a single JSON with a `status` field plus a ready-to-run `next_command`. Tolerates transient RPC errors (treats as 0).
+
+**Parameters:**
+- `--wallet <ADDRESS>` (optional) — Query a specific wallet instead of the connected onchainos wallet
+
+**Output fields:** `ok`, `about`, `wallet`, `chain_id`, `market`, `base_asset`, `assets.comet_supply_balance`, `assets.comet_borrow_balance`, `status`, `suggestion`, `next_command`
+
+**Status values:**
+
+| `status` | Meaning | Recommended next step |
+|---|---|---|
+| `borrowed` | Active borrow position on this market | `get-position --collateral-asset <X>` to inspect health, then `repay` |
+| `earning` | Supplying base asset, no active borrow | `get-position` to view accrued interest; `claim-rewards` if COMP available |
+| `new_user` | No Compound V3 position on this market | `get-markets` to browse current APRs |
+
+**Agent flow:** Run first for any new/returning user before `supply` or `borrow`. Relay `status` and `suggestion` to the user, then execute `next_command` (or let the user decide). Note: this command reports on a single `(chain, market)` pair — use the default (`8453/usdc`, Base USDC) or pass `--chain` and `--market` to target a different one.
+
+---
+
 ### get-markets — View market statistics
 
 ```bash

skills/compound-v3-plugin/SUMMARY.md

@@ -1,18 +1,16 @@
-**Overview**
+## Overview
 
 Compound V3 (Comet) is a single-asset lending protocol on Ethereum, Base, Arbitrum, and Polygon. This skill lets you supply the base asset to earn yield, supply collateral to borrow, repay and withdraw, check positions, and claim COMP rewards.
 
-**Prerequisites**
+## Prerequisites
 - onchainos CLI installed and logged in
 - ETH for gas on the target chain (Ethereum / Base / Arbitrum / Polygon)
 - USDC or WETH to supply as base asset, or a supported collateral asset (WETH, cbETH, ...) to borrow against
 
-**Quick Start**
-1. Check your balance on the target chain: `onchainos wallet balance --chain 8453` (Base; use 1 / 42161 / 137 for Ethereum / Arbitrum / Polygon)
-2. Browse market rates, utilization, and collateral assets: `compound-v3 --chain 8453 get-markets`
-3. To earn yield, preview a supply of the base asset (no tx sent): `compound-v3 --chain 8453 --market usdc supply --asset <BASE_ASSET_ADDR> --amount 10`
-4. Re-run with `--confirm` to execute: `compound-v3 --chain 8453 --market usdc --confirm supply --asset <BASE_ASSET_ADDR> --amount 10`
-5. Check your position any time: `compound-v3 --chain 8453 --market usdc get-position`
-6. To borrow, first supply a collateral asset, then borrow the base asset: `compound-v3 --chain 8453 --market usdc --confirm supply --asset <COLLATERAL_ADDR> --amount 0.005` → `compound-v3 --chain 8453 --market usdc --confirm borrow --amount 5`
-7. Exit the borrow: `compound-v3 --chain 8453 --market usdc --confirm repay` then `compound-v3 --chain 8453 --market usdc --confirm withdraw --asset <COLLATERAL_ADDR> --amount 0.005`
-8. Claim COMP rewards: `compound-v3 --chain 8453 --market usdc --confirm claim-rewards`
+## Quick Start
+1. Check your current state and get a guided next step: `compound-v3-plugin quickstart` (add `--chain <ID> --market <NAME>` to target a specific market; default is Base USDC)
+2. If you see `status: new_user` — browse market rates and collateral assets, then supply the base asset: `compound-v3-plugin --chain 8453 --market usdc get-markets` → `compound-v3-plugin --chain 8453 --market usdc supply --asset <BASE_ASSET_ADDR> --amount 10 --confirm`
+3. If you see `status: earning` — view your position and accrued interest, claim COMP rewards when available: `compound-v3-plugin --chain 8453 --market usdc get-position` / `compound-v3-plugin --chain 8453 --market usdc claim-rewards --confirm`
+4. If you see `status: borrowed` — review position and health (pass `--collateral-asset <ADDR>` to see collateral), then repay when ready: `compound-v3-plugin --chain 8453 --market usdc get-position --collateral-asset <ADDR>` → `compound-v3-plugin --chain 8453 --market usdc repay --amount all --confirm`
+5. To borrow from a fresh wallet: supply a collateral asset, then borrow the base asset: `compound-v3-plugin --chain 8453 --market usdc supply --asset <COLLATERAL_ADDR> --amount 0.005 --confirm` → `compound-v3-plugin --chain 8453 --market usdc borrow --amount 5 --confirm`
+6. Exit a borrow: repay first, then withdraw collateral: `compound-v3-plugin --chain 8453 --market usdc repay --amount all --confirm` → `compound-v3-plugin --chain 8453 --market usdc withdraw --asset <COLLATERAL_ADDR> --amount 0.005 --confirm`

skills/compound-v3-plugin/plugin.yaml

@@ -1,6 +1,6 @@
 schema_version: 1
 name: compound-v3-plugin
-version: "0.2.6"
+version: "0.2.7"
 description: "Compound V3 (Comet) lending plugin: supply collateral, borrow/repay the base asset, and claim COMP rewards"
 author:
   name: skylavis-sky

skills/compound-v3-plugin/src/commands/mod.rs

@@ -5,3 +5,4 @@ pub mod borrow;
 pub mod repay;
 pub mod withdraw;
 pub mod claim_rewards;
+pub mod quickstart;

skills/compound-v3-plugin/src/commands/quickstart.rs

@@ -0,0 +1,111 @@
+use crate::config::get_market_config;
+use crate::onchainos;
+use crate::rpc;
+use anyhow::Result;
+
+const ABOUT: &str = "Compound V3 (Comet) is an on-chain lending protocol. Each market has one base asset you can supply to earn interest or borrow against collateral. Supported chains: Ethereum (1), Base (8453), Arbitrum (42161), Polygon (137).";
+
+pub async fn run(chain_id: u64, market: &str, wallet: Option<String>) -> Result<()> {
+    let cfg = get_market_config(chain_id, market)?;
+
+    let wallet_addr = match wallet {
+        Some(w) => w,
+        None => {
+            let w = onchainos::resolve_wallet(chain_id)?;
+            if w.is_empty() {
+                anyhow::bail!("Cannot resolve wallet address. Pass --wallet or log in via onchainos.");
+            }
+            w
+        }
+    };
+
+    // Parallel fetch: Comet supply + borrow balance. Tolerate RPC errors silently —
+    // this command is a status probe, not a trading command.
+    let (supply_res, borrow_res) = tokio::join!(
+        rpc::get_balance_of(cfg.comet_proxy, &wallet_addr, cfg.rpc_url),
+        rpc::get_borrow_balance_of(cfg.comet_proxy, &wallet_addr, cfg.rpc_url),
+    );
+
+    let supply_raw = supply_res.unwrap_or(0);
+    let borrow_raw = borrow_res.unwrap_or(0);
+
+    let factor = 10u128.pow(cfg.base_asset_decimals as u32) as f64;
+    let supply_balance = supply_raw as f64 / factor;
+    let borrow_balance = borrow_raw as f64 / factor;
+
+    let (status, suggestion, next_command) =
+        build_suggestion(chain_id, market, cfg.base_asset_symbol, supply_balance, borrow_balance);
+
+    let out = serde_json::json!({
+        "ok": true,
+        "about": ABOUT,
+        "wallet": wallet_addr,
+        "chain_id": chain_id,
+        "market": market,
+        "base_asset": cfg.base_asset_symbol,
+        "assets": {
+            "comet_supply_balance":     format!("{:.6}", supply_balance),
+            "comet_supply_balance_raw": supply_raw.to_string(),
+            "comet_borrow_balance":     format!("{:.6}", borrow_balance),
+            "comet_borrow_balance_raw": borrow_raw.to_string(),
+        },
+        "status":       status,
+        "suggestion":   suggestion,
+        "next_command": next_command,
+    });
+
+    println!("{}", serde_json::to_string_pretty(&out)?);
+    Ok(())
+}
+
+/// Returns (status, human-readable suggestion, ready-to-run command).
+fn build_suggestion(
+    chain_id: u64,
+    market: &str,
+    base_asset_symbol: &str,
+    supply_balance: f64,
+    borrow_balance: f64,
+) -> (&'static str, String, String) {
+    // 1. borrowed — active borrow position; review health and plan repay
+    if borrow_balance > 0.0 {
+        return (
+            "borrowed",
+            format!(
+                "You have an active borrow of {:.6} {}. Review your position and health factor; repay when ready.",
+                borrow_balance, base_asset_symbol
+            ),
+            format!(
+                "compound-v3-plugin --chain {} --market {} get-position",
+                chain_id, market
+            ),
+        );
+    }
+
+    // 2. earning — supply base asset, no borrow
+    if supply_balance > 0.0 {
+        return (
+            "earning",
+            format!(
+                "You are supplying {:.6} {} and earning interest. No active borrow.",
+                supply_balance, base_asset_symbol
+            ),
+            format!(
+                "compound-v3-plugin --chain {} --market {} get-position",
+                chain_id, market
+            ),
+        );
+    }
+
+    // 3. new_user — no Comet position on this market
+    (
+        "new_user",
+        format!(
+            "No Compound V3 position on {} (chain {}). Browse current APRs and supply or collateralize to start.",
+            market, chain_id
+        ),
+        format!(
+            "compound-v3-plugin --chain {} --market {} get-markets",
+            chain_id, market
+        ),
+    )
+}

skills/compound-v3-plugin/src/main.rs

@@ -30,6 +30,13 @@ struct Cli {
 
 #[derive(Subcommand)]
 enum Commands {
+    /// Check wallet state and get a recommended next step (supply/borrow/earning overview)
+    Quickstart {
+        /// Wallet address (defaults to logged-in onchainos wallet)
+        #[arg(long)]
+        wallet: Option<String>,
+    },
+
     /// List market info: supply APR, borrow APR, utilization, TVL
     GetMarkets,
 
@@ -109,6 +116,9 @@ async fn main() {
     let cli = Cli::parse();
 
     let result = match cli.command {
+        Commands::Quickstart { wallet } => {
+            commands::quickstart::run(cli.chain, &cli.market, wallet).await
+        }
         Commands::GetMarkets => {
             commands::get_markets::run(cli.chain, &cli.market).await
         }