@spectratools/aborean-cli 0.6.0 → 0.7.0

package/dist/cli.js

@@ -1352,10 +1352,32 @@ cl.command("pools", {
       poolStates.flatMap((pool) => [pool.token0, pool.token1])
     );
     const rows = poolStates.map((pool) => toPoolRow(pool, tokenMeta));
-    return c.ok({
-      count: rows.length,
-      pools: rows
-    });
+    const firstPool = rows[0];
+    return c.ok(
+      {
+        count: rows.length,
+        pools: rows
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Explore CL pools:",
+          commands: [
+            ...firstPool ? [
+              {
+                command: "cl pool",
+                args: { pool: firstPool.pool },
+                description: `Inspect ${firstPool.pair}`
+              }
+            ] : [],
+            {
+              command: "cl positions",
+              args: { owner: "<address>" },
+              description: "List CL positions for an address"
+            }
+          ]
+        }
+      }
+    );
   }
 });
 cl.command("pool", {
@@ -1378,9 +1400,33 @@ cl.command("pool", {
     const checksummedPool = checksumAddress(c.args.pool);
     const [poolState] = await readPoolStates(client, [checksummedPool]);
     const tokenMeta = await readTokenMetadata(client, [poolState.token0, poolState.token1]);
-    return c.ok({
-      pool: toPoolRow(poolState, tokenMeta)
-    });
+    const row = toPoolRow(poolState, tokenMeta);
+    return c.ok(
+      {
+        pool: row
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Next steps:",
+          commands: [
+            {
+              command: "cl quote",
+              args: {
+                tokenIn: row.token0.address,
+                tokenOut: row.token1.address,
+                amountIn: "1"
+              },
+              description: `Quote a ${row.token0.symbol} \u2192 ${row.token1.symbol} swap`
+            },
+            {
+              command: "cl positions",
+              args: { owner: "<address>" },
+              description: "List positions in this pool"
+            }
+          ]
+        }
+      }
+    );
   }
 });
 cl.command("positions", {
@@ -1466,11 +1512,35 @@ cl.command("positions", {
         }
       };
     });
-    return c.ok({
-      owner,
-      count: positions.length,
-      positions
-    });
+    const firstPosition = positions[0];
+    return c.ok(
+      {
+        owner,
+        count: positions.length,
+        positions
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Related commands:",
+          commands: firstPosition ? [
+            {
+              command: "cl pool",
+              args: { pool: "<poolAddress>" },
+              description: `Inspect pool for ${firstPosition.pair}`
+            },
+            {
+              command: "cl quote",
+              args: {
+                tokenIn: firstPosition.token0.address,
+                tokenOut: firstPosition.token1.address,
+                amountIn: "1"
+              },
+              description: `Quote a ${firstPosition.token0.symbol} \u2192 ${firstPosition.token1.symbol} swap`
+            }
+          ] : []
+        }
+      }
+    );
   }
 });
 cl.command("quote", {
@@ -1560,31 +1630,54 @@ cl.command("quote", {
     const inIsToken0 = normalizeAddress(inAddress) === normalizeAddress(selectedPool.token0);
     const poolMidPriceOutPerIn = inIsToken0 ? poolPrices.token1PerToken0 : poolPrices.token0PerToken1;
     const priceImpactPct = quotePriceOutPerIn === null || poolMidPriceOutPerIn === null || poolMidPriceOutPerIn === 0 ? null : finiteOrNull((poolMidPriceOutPerIn - quotePriceOutPerIn) / poolMidPriceOutPerIn * 100);
-    return c.ok({
-      pool: checksumAddress(selectedPool.pool),
-      selectedFee: selectedPool.fee,
-      selectedTickSpacing: selectedPool.tickSpacing,
-      tokenIn: inMeta,
-      tokenOut: outMeta,
-      amountIn: {
-        raw: amountInRaw.toString(),
-        decimal: amountInDecimal
-      },
-      amountOut: {
-        raw: amountOutRaw.toString(),
-        decimal: amountOutDecimal
-      },
-      execution: {
-        sqrtPriceX96After: quote[1].toString(),
-        initializedTicksCrossed: quote[2],
-        gasEstimate: quote[3].toString()
+    return c.ok(
+      {
+        pool: checksumAddress(selectedPool.pool),
+        selectedFee: selectedPool.fee,
+        selectedTickSpacing: selectedPool.tickSpacing,
+        tokenIn: inMeta,
+        tokenOut: outMeta,
+        amountIn: {
+          raw: amountInRaw.toString(),
+          decimal: amountInDecimal
+        },
+        amountOut: {
+          raw: amountOutRaw.toString(),
+          decimal: amountOutDecimal
+        },
+        execution: {
+          sqrtPriceX96After: quote[1].toString(),
+          initializedTicksCrossed: quote[2],
+          gasEstimate: quote[3].toString()
+        },
+        prices: {
+          poolMidPriceOutPerIn,
+          quotePriceOutPerIn,
+          priceImpactPct
+        }
       },
-      prices: {
-        poolMidPriceOutPerIn,
-        quotePriceOutPerIn,
-        priceImpactPct
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Related commands:",
+          commands: [
+            {
+              command: "cl pool",
+              args: { pool: checksumAddress(selectedPool.pool) },
+              description: "Inspect the pool used for this quote"
+            },
+            {
+              command: "cl quote",
+              args: {
+                tokenIn: outMeta.address,
+                tokenOut: inMeta.address,
+                amountIn: amountOutDecimal
+              },
+              description: `Reverse quote ${outMeta.symbol} \u2192 ${inMeta.symbol}`
+            }
+          ]
+        }
       }
-    });
+    );
   }
 });
 
@@ -1747,10 +1840,25 @@ gauges.command("list", {
         periodFinishRelative: relTime(periodFinish)
       };
     });
-    return c.ok({
-      gauges: items,
-      count: items.length
-    });
+    const firstGauge = items[0];
+    return c.ok(
+      {
+        gauges: items,
+        count: items.length
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Explore gauges:",
+          commands: firstGauge ? [
+            {
+              command: "gauges info",
+              args: { gauge: firstGauge.gauge },
+              description: "Inspect top gauge details"
+            }
+          ] : []
+        }
+      }
+    );
   }
 });
 gauges.command("info", {
@@ -1877,24 +1985,46 @@ gauges.command("info", {
         functionName: "left"
       })
     ]);
-    return c.ok({
-      gauge: toChecksum(gauge),
-      pool: toChecksum(pool),
-      isAlive,
-      stakingToken: toChecksum(stakingToken),
-      rewardToken: toChecksum(rewardToken),
-      totalStaked: totalStaked.toString(),
-      rewardRate: rewardRate.toString(),
-      rewardPerTokenStored: rewardPerTokenStored.toString(),
-      fees0: fees0.toString(),
-      fees1: fees1.toString(),
-      left: left.toString(),
-      periodFinish: asNum(periodFinish),
-      periodFinishRelative: relTime(periodFinish),
-      lastUpdateTime: asNum(lastUpdateTime),
-      bribeContract: toChecksum(bribeContract),
-      feeContract: toChecksum(feeContract)
-    });
+    return c.ok(
+      {
+        gauge: toChecksum(gauge),
+        pool: toChecksum(pool),
+        isAlive,
+        stakingToken: toChecksum(stakingToken),
+        rewardToken: toChecksum(rewardToken),
+        totalStaked: totalStaked.toString(),
+        rewardRate: rewardRate.toString(),
+        rewardPerTokenStored: rewardPerTokenStored.toString(),
+        fees0: fees0.toString(),
+        fees1: fees1.toString(),
+        left: left.toString(),
+        periodFinish: asNum(periodFinish),
+        periodFinishRelative: relTime(periodFinish),
+        lastUpdateTime: asNum(lastUpdateTime),
+        bribeContract: toChecksum(bribeContract),
+        feeContract: toChecksum(feeContract)
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Related commands:",
+          commands: [
+            {
+              command: "ve stats",
+              description: "View veABX global stats"
+            },
+            {
+              command: "voter weights",
+              description: "Check pool voting weight distribution"
+            },
+            {
+              command: "voter bribes",
+              args: { pool: toChecksum(pool) },
+              description: "View bribe rewards for this pool"
+            }
+          ]
+        }
+      }
+    );
   }
 });
 gauges.command("staked", {
@@ -1973,11 +2103,33 @@ gauges.command("staked", {
       staked: position.staked.toString(),
       earned: position.earned.toString()
     }));
-    return c.ok({
-      address: toChecksum(c.args.address),
-      positions,
-      count: positions.length
-    });
+    const firstPosition = positions[0];
+    return c.ok(
+      {
+        address: toChecksum(c.args.address),
+        positions,
+        count: positions.length
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Related commands:",
+          commands: [
+            ...firstPosition ? [
+              {
+                command: "gauges info",
+                args: { gauge: firstPosition.gauge },
+                description: "Inspect gauge details"
+              }
+            ] : [],
+            {
+              command: "ve locks",
+              args: { address: toChecksum(c.args.address) },
+              description: "View veNFT locks for this address"
+            }
+          ]
+        }
+      }
+    );
   }
 });
 
@@ -2354,12 +2506,33 @@ lending.command("markets", {
     const rows = markets.map((market) => toMarketRow(market.marketId, market.params, market.state, tokenMeta)).sort(
       (a, b) => BigInt(a.totalSupplyAssets) > BigInt(b.totalSupplyAssets) ? -1 : BigInt(a.totalSupplyAssets) < BigInt(b.totalSupplyAssets) ? 1 : 0
     ).slice(0, c.args.limit);
-    return c.ok({
-      morpho: toChecksum(ABOREAN_LENDING_ADDRESSES.morphoBlue),
-      marketCount: marketIds.length,
-      markets: rows,
-      totalsByLoanToken: summarizeByLoanToken(markets, tokenMeta)
-    });
+    const firstMarket = rows[0];
+    return c.ok(
+      {
+        morpho: toChecksum(ABOREAN_LENDING_ADDRESSES.morphoBlue),
+        marketCount: marketIds.length,
+        markets: rows,
+        totalsByLoanToken: summarizeByLoanToken(markets, tokenMeta)
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Explore lending:",
+          commands: [
+            ...firstMarket ? [
+              {
+                command: "lending market",
+                args: { marketId: firstMarket.marketId },
+                description: `Inspect ${firstMarket.loanToken.symbol}/${firstMarket.collateralToken.symbol} market`
+              }
+            ] : [],
+            {
+              command: "pools list",
+              description: "View V2 AMM pools"
+            }
+          ]
+        }
+      }
+    );
   }
 });
 lending.command("market", {
@@ -2401,7 +2574,26 @@ lending.command("market", {
     const params = normalizeMarketParams(paramsRaw);
     const state = normalizeMarketState(stateRaw);
     const tokenMeta = await readTokenMetadata2(client, [params.loanToken, params.collateralToken]);
-    return c.ok(toMarketRow(marketId, params, state, tokenMeta));
+    const row = toMarketRow(marketId, params, state, tokenMeta);
+    return c.ok(
+      row,
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Related commands:",
+          commands: [
+            {
+              command: "lending position",
+              args: { marketId, user: "<address>" },
+              description: "Inspect a user position in this market"
+            },
+            {
+              command: "lending markets",
+              description: "List all Morpho markets"
+            }
+          ]
+        }
+      }
+    );
   }
 });
 lending.command("position", {
@@ -2508,34 +2700,52 @@ lending.command("position", {
       state.totalBorrowShares,
       state.totalBorrowAssets
     );
-    return c.ok({
-      marketId,
-      user: toChecksum(user),
-      loanToken: {
-        address: toChecksum(loanMeta.address),
-        symbol: loanMeta.symbol,
-        decimals: loanMeta.decimals
-      },
-      collateralToken: {
-        address: toChecksum(collateralMeta.address),
-        symbol: collateralMeta.symbol,
-        decimals: collateralMeta.decimals
-      },
-      supplyShares: position.supplyShares.toString(),
-      supplyAssetsEstimate: {
-        raw: supplyAssetsEstimate.toString(),
-        decimal: formatUnits2(supplyAssetsEstimate, loanMeta.decimals)
-      },
-      borrowShares: position.borrowShares.toString(),
-      borrowAssetsEstimate: {
-        raw: borrowAssetsEstimate.toString(),
-        decimal: formatUnits2(borrowAssetsEstimate, loanMeta.decimals)
+    return c.ok(
+      {
+        marketId,
+        user: toChecksum(user),
+        loanToken: {
+          address: toChecksum(loanMeta.address),
+          symbol: loanMeta.symbol,
+          decimals: loanMeta.decimals
+        },
+        collateralToken: {
+          address: toChecksum(collateralMeta.address),
+          symbol: collateralMeta.symbol,
+          decimals: collateralMeta.decimals
+        },
+        supplyShares: position.supplyShares.toString(),
+        supplyAssetsEstimate: {
+          raw: supplyAssetsEstimate.toString(),
+          decimal: formatUnits2(supplyAssetsEstimate, loanMeta.decimals)
+        },
+        borrowShares: position.borrowShares.toString(),
+        borrowAssetsEstimate: {
+          raw: borrowAssetsEstimate.toString(),
+          decimal: formatUnits2(borrowAssetsEstimate, loanMeta.decimals)
+        },
+        collateralAssets: {
+          raw: position.collateral.toString(),
+          decimal: formatUnits2(BigInt(position.collateral), collateralMeta.decimals)
+        }
       },
-      collateralAssets: {
-        raw: position.collateral.toString(),
-        decimal: formatUnits2(BigInt(position.collateral), collateralMeta.decimals)
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Related commands:",
+          commands: [
+            {
+              command: "lending market",
+              args: { marketId },
+              description: "View market details"
+            },
+            {
+              command: "lending markets",
+              description: "List all Morpho markets"
+            }
+          ]
+        }
       }
-    });
+    );
   }
 });
 
@@ -2827,13 +3037,40 @@ pools.command("list", {
       client,
       poolStates.map((pool) => ({ pool: pool.pool, stable: pool.stable }))
     );
-    return c.ok({
-      total,
-      offset,
-      limit: c.options.limit,
-      count: poolStates.length,
-      pools: poolStates.map((pool, index) => toPoolSummary(pool, tokenMeta, fees[index] ?? null))
-    });
+    const summaries = poolStates.map(
+      (pool, index) => toPoolSummary(pool, tokenMeta, fees[index] ?? null)
+    );
+    const firstPool = summaries[0];
+    return c.ok(
+      {
+        total,
+        offset,
+        limit: c.options.limit,
+        count: summaries.length,
+        pools: summaries
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Explore pools:",
+          commands: [
+            ...firstPool ? [
+              {
+                command: "pools pool",
+                args: { address: firstPool.pool },
+                description: `Inspect ${firstPool.pair}`
+              }
+            ] : [],
+            ...firstPool ? [
+              {
+                command: "pools fees",
+                args: { pool: firstPool.pool },
+                description: `Check fees for ${firstPool.pair}`
+              }
+            ] : []
+          ]
+        }
+      }
+    );
   }
 });
 pools.command("pool", {
@@ -2896,26 +3133,50 @@ pools.command("pool", {
     ]);
     const tokenMeta = await readTokenMetadata3(client, [token0, token1]);
     const [fee] = await readPoolFees(client, [{ pool: poolAddress, stable }]);
-    return c.ok({
-      pool: {
-        ...toPoolSummary(
-          {
-            pool: poolAddress,
-            token0,
-            token1,
-            stable,
-            reserve0: reserves[0],
-            reserve1: reserves[1],
-            blockTimestampLast: reserves[2],
-            totalSupply
-          },
-          tokenMeta,
-          fee ?? null
-        ),
-        poolFees: checksumAddress4(poolFees),
-        factory: checksumAddress4(factory)
+    const summary = toPoolSummary(
+      {
+        pool: poolAddress,
+        token0,
+        token1,
+        stable,
+        reserve0: reserves[0],
+        reserve1: reserves[1],
+        blockTimestampLast: reserves[2],
+        totalSupply
+      },
+      tokenMeta,
+      fee ?? null
+    );
+    return c.ok(
+      {
+        pool: {
+          ...summary,
+          poolFees: checksumAddress4(poolFees),
+          factory: checksumAddress4(factory)
+        }
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Next steps:",
+          commands: [
+            {
+              command: "pools quote",
+              args: {
+                tokenIn: summary.token0.address,
+                tokenOut: summary.token1.address,
+                amountIn: "1"
+              },
+              description: `Quote a ${summary.token0.symbol} \u2192 ${summary.token1.symbol} swap`
+            },
+            {
+              command: "pools fees",
+              args: { pool: checksumAddress4(poolAddress) },
+              description: "Check fee configuration"
+            }
+          ]
+        }
       }
-    });
+    );
   }
 });
 pools.command("quote", {
@@ -2994,21 +3255,44 @@ pools.command("quote", {
     const amountInDecimal = formatUnits3(amountInRaw, inMeta.decimals);
     const amountOutDecimal = formatUnits3(amountOutRaw, outMeta.decimals);
     const ratio = Number(amountOutDecimal) / Number(amountInDecimal);
-    return c.ok({
-      pool: checksumAddress4(poolAddress),
-      stable: c.options.stable,
-      tokenIn: inMeta,
-      tokenOut: outMeta,
-      amountIn: {
-        raw: amountInRaw.toString(),
-        decimal: amountInDecimal
-      },
-      amountOut: {
-        raw: amountOutRaw.toString(),
-        decimal: amountOutDecimal
+    return c.ok(
+      {
+        pool: checksumAddress4(poolAddress),
+        stable: c.options.stable,
+        tokenIn: inMeta,
+        tokenOut: outMeta,
+        amountIn: {
+          raw: amountInRaw.toString(),
+          decimal: amountInDecimal
+        },
+        amountOut: {
+          raw: amountOutRaw.toString(),
+          decimal: amountOutDecimal
+        },
+        priceOutPerIn: Number(amountInDecimal) === 0 ? null : finiteOrNull3(ratio)
       },
-      priceOutPerIn: Number(amountInDecimal) === 0 ? null : finiteOrNull3(ratio)
-    });
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Related commands:",
+          commands: [
+            {
+              command: "pools pool",
+              args: { address: checksumAddress4(poolAddress) },
+              description: "Inspect the pool used for this quote"
+            },
+            {
+              command: "pools quote",
+              args: {
+                tokenIn: outMeta.address,
+                tokenOut: inMeta.address,
+                amountIn: amountOutDecimal
+              },
+              description: `Reverse quote ${outMeta.symbol} \u2192 ${inMeta.symbol}`
+            }
+          ]
+        }
+      }
+    );
   }
 });
 pools.command("fees", {
@@ -3060,14 +3344,37 @@ pools.command("fees", {
     ]);
     const stableFee = toFeeInfo(stableFeeRaw ?? null);
     const volatileFee = toFeeInfo(volatileFeeRaw ?? null);
-    return c.ok({
-      pool: checksumAddress4(pool),
-      pair: `${token0Meta.symbol}/${token1Meta.symbol}`,
-      stable,
-      activeFee: stable ? stableFee : volatileFee,
-      stableFee,
-      volatileFee
-    });
+    return c.ok(
+      {
+        pool: checksumAddress4(pool),
+        pair: `${token0Meta.symbol}/${token1Meta.symbol}`,
+        stable,
+        activeFee: stable ? stableFee : volatileFee,
+        stableFee,
+        volatileFee
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Related commands:",
+          commands: [
+            {
+              command: "pools pool",
+              args: { address: checksumAddress4(pool) },
+              description: "View full pool state"
+            },
+            {
+              command: "pools quote",
+              args: {
+                tokenIn: token0Meta.address,
+                tokenOut: token1Meta.address,
+                amountIn: "1"
+              },
+              description: `Quote a ${token0Meta.symbol} \u2192 ${token1Meta.symbol} swap`
+            }
+          ]
+        }
+      }
+    );
   }
 });
 
@@ -3299,7 +3606,32 @@ vaults.command("list", {
   async run(c) {
     const client = createAboreanPublicClient(c.env.ABSTRACT_RPC_URL);
     const snapshot = await readVaultSummary(client);
-    return c.ok(snapshot);
+    const firstRelay = snapshot.relays[0];
+    return c.ok(
+      snapshot,
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Related commands:",
+          commands: [
+            ...firstRelay ? [
+              {
+                command: "vaults relay",
+                args: { relay: firstRelay.relay },
+                description: `Inspect ${firstRelay.label}`
+              }
+            ] : [],
+            {
+              command: "lending markets",
+              description: "View Morpho lending markets"
+            },
+            {
+              command: "ve stats",
+              description: "View veABX global stats"
+            }
+          ]
+        }
+      }
+    );
   }
 });
 vaults.command("relay", {
@@ -3334,7 +3666,25 @@ vaults.command("relay", {
     }
     const client = createAboreanPublicClient(c.env.ABSTRACT_RPC_URL);
     const snapshot = await readRelaySnapshot(client, known);
-    return c.ok(snapshot);
+    return c.ok(
+      snapshot,
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Related commands:",
+          commands: [
+            {
+              command: "vaults list",
+              description: "List all relay vaults"
+            },
+            {
+              command: "ve lock",
+              args: { tokenId: Number(snapshot.managedTokenId) },
+              description: `Inspect managed veNFT #${snapshot.managedTokenId}`
+            }
+          ]
+        }
+      }
+    );
   }
 });
 
@@ -3396,17 +3746,35 @@ ve.command("stats", {
       functionName: "pointHistory",
       args: [epoch]
     });
-    return c.ok({
-      token: toChecksum(token),
-      totalVotingPower: totalVotingPower.toString(),
-      totalLocked: totalLocked.toString(),
-      permanentLocked: permanentLocked.toString(),
-      epoch: asNum(epoch),
-      decayBias: point.bias.toString(),
-      decaySlope: point.slope.toString(),
-      lastCheckpointTimestamp: asNum(point.ts),
-      lastCheckpointBlock: asNum(point.blk)
-    });
+    return c.ok(
+      {
+        token: toChecksum(token),
+        totalVotingPower: totalVotingPower.toString(),
+        totalLocked: totalLocked.toString(),
+        permanentLocked: permanentLocked.toString(),
+        epoch: asNum(epoch),
+        decayBias: point.bias.toString(),
+        decaySlope: point.slope.toString(),
+        lastCheckpointTimestamp: asNum(point.ts),
+        lastCheckpointBlock: asNum(point.blk)
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Explore veABX:",
+          commands: [
+            {
+              command: "ve locks",
+              args: { address: "<owner>" },
+              description: "List veNFT locks for an address"
+            },
+            {
+              command: "voter epoch",
+              description: "View current emissions epoch timing"
+            }
+          ]
+        }
+      }
+    );
   }
 });
 ve.command("lock", {
@@ -3447,14 +3815,33 @@ ve.command("lock", {
         args: [tokenId]
       })
     ]);
-    return c.ok({
-      tokenId: c.args.tokenId,
-      owner: toChecksum(owner),
-      amount: locked.amount.toString(),
-      unlockTime: asNum(locked.end),
-      isPermanent: locked.isPermanent,
-      votingPower: votingPower.toString()
-    });
+    return c.ok(
+      {
+        tokenId: c.args.tokenId,
+        owner: toChecksum(owner),
+        amount: locked.amount.toString(),
+        unlockTime: asNum(locked.end),
+        isPermanent: locked.isPermanent,
+        votingPower: votingPower.toString()
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Related commands:",
+          commands: [
+            {
+              command: "ve voting-power",
+              args: { tokenId: c.args.tokenId },
+              description: "Check current voting power"
+            },
+            {
+              command: "voter rewards",
+              args: { tokenId: c.args.tokenId },
+              description: "Check claimable rewards for this veNFT"
+            }
+          ]
+        }
+      }
+    );
   }
 });
 ve.command("locks", {
@@ -3537,11 +3924,31 @@ ve.command("locks", {
         votingPower: votingPower.toString()
       };
     });
-    return c.ok({
-      address: toChecksum(c.args.address),
-      locks,
-      count: locks.length
-    });
+    const firstLock = locks[0];
+    return c.ok(
+      {
+        address: toChecksum(c.args.address),
+        locks,
+        count: locks.length
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Explore locks:",
+          commands: firstLock ? [
+            {
+              command: "ve lock",
+              args: { tokenId: Number(firstLock.tokenId) },
+              description: `Inspect veNFT #${firstLock.tokenId}`
+            },
+            {
+              command: "voter rewards",
+              args: { tokenId: Number(firstLock.tokenId) },
+              description: `Check rewards for veNFT #${firstLock.tokenId}`
+            }
+          ] : []
+        }
+      }
+    );
   }
 });
 ve.command("voting-power", {
@@ -3563,10 +3970,29 @@ ve.command("voting-power", {
       functionName: "balanceOfNFT",
       args: [BigInt(c.args.tokenId)]
     });
-    return c.ok({
-      tokenId: c.args.tokenId,
-      votingPower: votingPower.toString()
-    });
+    return c.ok(
+      {
+        tokenId: c.args.tokenId,
+        votingPower: votingPower.toString()
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Related commands:",
+          commands: [
+            {
+              command: "ve lock",
+              args: { tokenId: c.args.tokenId },
+              description: "View full lock details"
+            },
+            {
+              command: "voter rewards",
+              args: { tokenId: c.args.tokenId },
+              description: "Check claimable rewards"
+            }
+          ]
+        }
+      }
+    );
   }
 });
 
@@ -3654,15 +4080,32 @@ voter.command("epoch", {
     ]);
     const now = Math.floor(Date.now() / 1e3);
     const epochEnd = asNum(activePeriod + weekSeconds);
-    return c.ok({
-      activePeriod: asNum(activePeriod),
-      epochEnd,
-      secondsRemaining: clampPositive(epochEnd - now),
-      timeRemaining: relTime(activePeriod + weekSeconds),
-      weekSeconds: asNum(weekSeconds),
-      epochCount: asNum(epochCount),
-      weeklyEmission: weeklyEmission.toString()
-    });
+    return c.ok(
+      {
+        activePeriod: asNum(activePeriod),
+        epochEnd,
+        secondsRemaining: clampPositive(epochEnd - now),
+        timeRemaining: relTime(activePeriod + weekSeconds),
+        weekSeconds: asNum(weekSeconds),
+        epochCount: asNum(epochCount),
+        weeklyEmission: weeklyEmission.toString()
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Related commands:",
+          commands: [
+            {
+              command: "voter weights",
+              description: "View pool voting weight distribution"
+            },
+            {
+              command: "gauges list",
+              description: "List active gauges"
+            }
+          ]
+        }
+      }
+    );
   }
 });
 voter.command("weights", {
@@ -3726,11 +4169,32 @@ voter.command("weights", {
       gauge: toChecksum(entry.gauge),
       weight: entry.weight.toString()
     }));
-    return c.ok({
-      totalWeight: totalWeight.toString(),
-      pools: entries,
-      count: entries.length
-    });
+    const firstEntry = entries[0];
+    return c.ok(
+      {
+        totalWeight: totalWeight.toString(),
+        pools: entries,
+        count: entries.length
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Related commands:",
+          commands: [
+            {
+              command: "voter epoch",
+              description: "View current epoch timing"
+            },
+            ...firstEntry ? [
+              {
+                command: "voter bribes",
+                args: { pool: firstEntry.pool },
+                description: "View bribe rewards for top-weighted pool"
+              }
+            ] : []
+          ]
+        }
+      }
+    );
   }
 });
 voter.command("rewards", {
@@ -3802,16 +4266,34 @@ voter.command("rewards", {
         args: [tokenId]
       })
     ]);
-    return c.ok({
-      tokenId: c.args.tokenId,
-      rewardToken: toChecksum(rewardToken),
-      claimableRebase: claimableRebase.toString(),
-      timeCursor: asNum(timeCursor),
-      lastTokenTime: asNum(lastTokenTime),
-      distributorStartTime: asNum(distributorStartTime),
-      usedWeight: usedWeight.toString(),
-      lastVoted: asNum(lastVoted)
-    });
+    return c.ok(
+      {
+        tokenId: c.args.tokenId,
+        rewardToken: toChecksum(rewardToken),
+        claimableRebase: claimableRebase.toString(),
+        timeCursor: asNum(timeCursor),
+        lastTokenTime: asNum(lastTokenTime),
+        distributorStartTime: asNum(distributorStartTime),
+        usedWeight: usedWeight.toString(),
+        lastVoted: asNum(lastVoted)
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Related commands:",
+          commands: [
+            {
+              command: "ve lock",
+              args: { tokenId: c.args.tokenId },
+              description: "View lock details for this veNFT"
+            },
+            {
+              command: "voter weights",
+              description: "Check pool voting weight distribution"
+            }
+          ]
+        }
+      }
+    );
   }
 });
 voter.command("bribes", {
@@ -3916,14 +4398,32 @@ voter.command("bribes", {
       token: toChecksum(token),
       epochAmount: epochAmounts[index].toString()
     }));
-    return c.ok({
-      pool: toChecksum(c.args.pool),
-      gauge: toChecksum(gauge),
-      bribeContract: toChecksum(bribeContract),
-      epochStart: asNum(epochStart),
-      rewardTokens: items,
-      count: items.length
-    });
+    return c.ok(
+      {
+        pool: toChecksum(c.args.pool),
+        gauge: toChecksum(gauge),
+        bribeContract: toChecksum(bribeContract),
+        epochStart: asNum(epochStart),
+        rewardTokens: items,
+        count: items.length
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Related commands:",
+          commands: [
+            {
+              command: "gauges info",
+              args: { gauge: toChecksum(gauge) },
+              description: "Inspect gauge details"
+            },
+            {
+              command: "voter epoch",
+              description: "View current epoch timing"
+            }
+          ]
+        }
+      }
+    );
   }
 });
 
@@ -4430,38 +4930,63 @@ cli.command("status", {
     }
     const now = Math.floor(Date.now() / 1e3);
     const epochEnd = Number(activePeriod) + Number(weekSeconds);
-    return c.ok({
-      v2PoolCount: Number(v2PoolCount),
-      clPoolCount: Number(clPoolCount),
-      gaugeCount: Number(gaugeCount),
-      totalVotingWeight: String(totalVotingWeight),
-      veABXTotalSupply: String(veABXTotalSupply),
-      veABXLockedSupply: String(veABXLockedSupply),
-      epoch: {
-        activePeriod: Number(activePeriod),
-        epochEnd,
-        secondsRemaining: Math.max(0, epochEnd - now),
-        epochCount: Number(epochCount),
-        weeklyEmission: String(weeklyEmission)
-      },
-      topPools: v2PoolSnapshot.topPools,
-      tvl: {
-        v2ReserveUnitEstimate: v2PoolSnapshot.reserveUnitTvl,
-        vaultManagedVotingPower
-      },
-      vaults: {
-        relayCount: vaultRelayCount,
-        managedVotingPower: vaultManagedVotingPower,
-        note: vaultNote
+    return c.ok(
+      {
+        v2PoolCount: Number(v2PoolCount),
+        clPoolCount: Number(clPoolCount),
+        gaugeCount: Number(gaugeCount),
+        totalVotingWeight: String(totalVotingWeight),
+        veABXTotalSupply: String(veABXTotalSupply),
+        veABXLockedSupply: String(veABXLockedSupply),
+        epoch: {
+          activePeriod: Number(activePeriod),
+          epochEnd,
+          secondsRemaining: Math.max(0, epochEnd - now),
+          epochCount: Number(epochCount),
+          weeklyEmission: String(weeklyEmission)
+        },
+        topPools: v2PoolSnapshot.topPools,
+        tvl: {
+          v2ReserveUnitEstimate: v2PoolSnapshot.reserveUnitTvl,
+          vaultManagedVotingPower
+        },
+        vaults: {
+          relayCount: vaultRelayCount,
+          managedVotingPower: vaultManagedVotingPower,
+          note: vaultNote
+        },
+        lending: {
+          available: lendingAvailable,
+          morpho: lendingMorpho,
+          marketCount: lendingMarketCount,
+          supplyByLoanToken: lendingSupplyByLoanToken,
+          note: lendingNote
+        }
       },
-      lending: {
-        available: lendingAvailable,
-        morpho: lendingMorpho,
-        marketCount: lendingMarketCount,
-        supplyByLoanToken: lendingSupplyByLoanToken,
-        note: lendingNote
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Drill down:",
+          commands: [
+            {
+              command: "pools list",
+              description: "List V2 AMM pools"
+            },
+            {
+              command: "cl pools",
+              description: "List Slipstream CL pools"
+            },
+            {
+              command: "gauges list",
+              description: "List active gauges"
+            },
+            {
+              command: "ve stats",
+              description: "View veABX global stats"
+            }
+          ]
+        }
       }
-    });
+    );
   }
 });
 applyFriendlyErrorHandling(cli);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spectratools/aborean-cli",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "CLI for Aborean Finance DEX on Abstract (pools, swaps, gauges, voting escrow).",
   "type": "module",
   "license": "MIT",