naracli 1.0.56 → 1.0.58

package/bin/nara-cli.ts

@@ -15,13 +15,13 @@ const program = new Command();
 // Set program metadata
 program
   .name("naracli")
-  .description("CLI for the Nara chain (Solana-compatible)")
+  .description("CLI for the Nara chain. Native coin is NARA (not SOL). Mine NARA for free via PoMI quests, manage wallets, register agents, and more. Run 'naracli <command> --help' for details on any command.")
   .version(version);
 
 // Add global options
 program
-  .option("-r, --rpc-url <url>", "RPC endpoint URL")
-  .option("-w, --wallet <path>", "Path to wallet keypair JSON file")
+  .option("-r, --rpc-url <url>", "RPC endpoint (default: https://mainnet-api.nara.build/)")
+  .option("-w, --wallet <path>", "Path to wallet keypair JSON file (default: ~/.config/nara/id.json)")
   .option("-j, --json", "Output in JSON format");
 
 // Register all command modules

package/dist/nara-cli-bundle.cjs

@@ -126972,6 +126972,29 @@ async function getStakeInfo(connection, user, options) {
     return null;
   }
 }
+async function getQuestConfig(connection, options) {
+  const kp = import_web390.Keypair.generate();
+  const program3 = createProgram2(connection, kp, options?.programId);
+  const programId = new import_web390.PublicKey(options?.programId ?? DEFAULT_QUEST_PROGRAM_ID);
+  const [configPda] = import_web390.PublicKey.findProgramAddressSync(
+    [new TextEncoder().encode("quest_config")],
+    programId
+  );
+  const config = await program3.account.gameConfig.fetch(configPda);
+  return {
+    authority: config.authority,
+    minRewardCount: config.minRewardCount,
+    maxRewardCount: config.maxRewardCount,
+    stakeBpsHigh: Number(config.stakeBpsHigh.toString()),
+    stakeBpsLow: Number(config.stakeBpsLow.toString()),
+    decayMs: Number(config.decayMs.toString()),
+    treasury: config.treasury,
+    questAuthority: config.questAuthority,
+    minQuestInterval: Number(config.minQuestInterval.toString()),
+    rewardPerShare: Number(config.rewardPerShare.toString()),
+    extraReward: Number(config.extraReward.toString())
+  };
+}
 
 // node_modules/.pnpm/nara-sdk@1.0.54_bufferutil@4.1.0_fastestsmallesttextencoderdecoder@1.0.22_typescript@5.9.3_utf-8-validate@6.0.6/node_modules/nara-sdk/src/skills.ts
 var import_web391 = __toESM(require_index_cjs(), 1);
@@ -130513,8 +130536,8 @@ ${result.base64}`);
 var _DEFAULT_WALLET_PATH = process.env.WALLET_PATH || "~/.config/nara/id.json";
 var DEFAULT_WALLET_PATH2 = _DEFAULT_WALLET_PATH.startsWith("~") ? (0, import_node_path3.join)((0, import_node_os3.homedir)(), _DEFAULT_WALLET_PATH.slice(1)) : _DEFAULT_WALLET_PATH;
 function registerWalletCommands(program3) {
-  const wallet = program3.command("wallet").description("Wallet management commands");
-  wallet.command("create").description("Create a new wallet").option("-o, --output <path>", "Output path for wallet file (default: ~/.config/nara/id.json)").action(async (options) => {
+  const wallet = program3.command("wallet").description("Wallet management \u2014 create or import a keypair for signing transactions");
+  wallet.command("create").description("Create a new wallet keypair (saved to ~/.config/nara/id.json by default)").option("-o, --output <path>", "Output path for wallet file (default: ~/.config/nara/id.json)").action(async (options) => {
     try {
       await handleWalletCreate(options);
     } catch (error) {
@@ -130963,6 +130986,14 @@ async function handleQuestGet(options) {
     }
     return;
   }
+  let stakeRequired = quest.effectiveStakeRequirement > 0;
+  try {
+    const config = await getQuestConfig(connection);
+    if (quest.rewardCount < config.maxRewardCount) {
+      stakeRequired = false;
+    }
+  } catch {
+  }
   const data = {
     round: quest.round,
     question: quest.question,
@@ -130974,7 +131005,8 @@ async function handleQuestGet(options) {
     deadline: new Date(quest.deadline * 1e3).toLocaleString(),
     timeRemaining: formatTimeRemaining(quest.timeRemaining),
     expired: quest.expired,
-    stakeRequirement: `${quest.effectiveStakeRequirement.toFixed(4)} NARA`,
+    stakeRequired,
+    stakeRequirement: stakeRequired ? `${quest.effectiveStakeRequirement.toFixed(4)} NARA` : "0 NARA",
     stakeHigh: `${quest.stakeHigh} NARA`,
     stakeLow: `${quest.stakeLow} NARA`,
     avgParticipantStake: `${quest.avgParticipantStake} NARA`
@@ -130991,8 +131023,10 @@ async function handleQuestGet(options) {
     console.log(
       `  Reward slots: ${quest.winnerCount}/${quest.rewardCount} (${quest.remainingSlots} remaining)`
     );
-    if (quest.effectiveStakeRequirement > 0) {
+    if (stakeRequired) {
       console.log(`  Stake requirement: ${quest.effectiveStakeRequirement.toFixed(4)} NARA (decays ${quest.stakeHigh} \u2192 ${quest.stakeLow})`);
+    } else {
+      console.log(`  Stake requirement: none`);
     }
     console.log(`  Deadline: ${new Date(quest.deadline * 1e3).toLocaleString()}`);
     if (quest.timeRemaining > 0) {
@@ -131003,6 +131037,49 @@ async function handleQuestGet(options) {
     console.log("");
   }
 }
+async function handleQuestConfig(options) {
+  const rpcUrl = getRpcUrl(options.rpcUrl);
+  const connection = new import_web398.Connection(rpcUrl, "confirmed");
+  let config;
+  try {
+    config = await getQuestConfig(connection);
+  } catch (err) {
+    printError(`Failed to fetch quest config: ${err.message}`);
+    process.exit(1);
+  }
+  const DECIMALS = 1e9;
+  const rewardPerShare = config.rewardPerShare / DECIMALS;
+  const extraReward = config.extraReward / DECIMALS;
+  const stakeBpsHigh = config.stakeBpsHigh;
+  const stakeBpsLow = config.stakeBpsLow;
+  const data = {
+    authority: config.authority.toBase58(),
+    questAuthority: config.questAuthority.toBase58(),
+    treasury: config.treasury.toBase58(),
+    minRewardCount: config.minRewardCount,
+    maxRewardCount: config.maxRewardCount,
+    rewardPerShare,
+    extraReward,
+    stakeBpsHigh,
+    stakeBpsLow,
+    decayMs: config.decayMs,
+    minQuestInterval: config.minQuestInterval
+  };
+  if (options.json) {
+    formatOutput(data, true);
+  } else {
+    console.log("");
+    console.log(`  Min Reward Count:   ${data.minRewardCount}`);
+    console.log(`  Max Reward Count:   ${data.maxRewardCount}`);
+    console.log(`  Reward Per Share:   ${rewardPerShare} NARA`);
+    console.log(`  Extra Reward:       ${extraReward} NARA`);
+    console.log(`  Stake BPS High:     ${stakeBpsHigh / 100}%`);
+    console.log(`  Stake BPS Low:      ${stakeBpsLow / 100}%`);
+    console.log(`  Decay (ms):         ${data.decayMs}`);
+    console.log(`  Min Quest Interval: ${data.minQuestInterval}s`);
+    console.log("");
+  }
+}
 async function handleQuestAnswer(answer, options) {
   const rpcUrl = getRpcUrl(options.rpcUrl);
   const connection = new import_web398.Connection(rpcUrl, "confirmed");
@@ -131208,8 +131285,8 @@ function handleSubmitError(err) {
   process.exit(1);
 }
 function registerQuestCommands(program3) {
-  const quest = program3.command("quest").description("Quest commands");
-  quest.command("get").description("Get current quest info").action(async (_opts, cmd) => {
+  const quest = program3.command("quest").description("PoMI quest commands \u2014 mine NARA by answering on-chain quests with ZK proofs");
+  quest.command("get").description("Get current quest info (question, deadline, difficulty, stake requirement)").action(async (_opts, cmd) => {
     try {
       const globalOpts = cmd.optsWithGlobals();
       await handleQuestGet(globalOpts);
@@ -131218,7 +131295,7 @@ function registerQuestCommands(program3) {
       process.exit(1);
     }
   });
-  quest.command("answer <answer>").description("Submit an answer").option("--relay [url]", `Submit via relay service, gasless (default: ${DEFAULT_QUEST_RELAY_URL2})`).option("--agent <name>", "Agent identifier (default: naracli)").option("--model <name>", "Model identifier").option("--referral <agent-id>", "Referral agent ID").option("--stake [amount]", 'Stake NARA before answering ("auto" to top-up to requirement, or a number)').action(async (answer, opts, cmd) => {
+  quest.command("answer <answer>").description("Submit a quest answer with ZK proof. Generates a proof locally and submits on-chain. Use --relay when balance is 0 (gasless). Always pass --agent and --model for reward tracking.").option("--relay [url]", `Submit via gasless relay (default: ${DEFAULT_QUEST_RELAY_URL2}, backup: https://quest2-api.nara.build/)`).option("--agent <name>", "Agent/platform type: claude-code, cursor, chatgpt, openclaw, etc. (default: naracli)").option("--model <name>", "AI model used: claude-opus-4-6, claude-sonnet-4-6, gpt-4o, etc.").option("--referral <agent-id>", "Referral agent ID for earning referral points").option("--stake [amount]", 'Stake NARA in the same tx ("auto" to top-up to requirement, or an exact amount)').action(async (answer, opts, cmd) => {
     try {
       const globalOpts = cmd.optsWithGlobals();
       const relayUrl = opts.relay === true ? DEFAULT_QUEST_RELAY_URL2 : opts.relay;
@@ -131229,6 +131306,15 @@ function registerQuestCommands(program3) {
       process.exit(1);
     }
   });
+  quest.command("config").description("Show quest program config (reward counts, stake params, decay, intervals)").action(async (_opts, cmd) => {
+    try {
+      const globalOpts = cmd.optsWithGlobals();
+      await handleQuestConfig(globalOpts);
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
   quest.command("stake <amount>").description("Stake NARA to participate in quests").action(async (amount, _opts, cmd) => {
     try {
       const globalOpts = cmd.optsWithGlobals();
@@ -133147,7 +133233,7 @@ async function handleSkillsDelete(name, options) {
   }
 }
 function registerSkillsCommands(program3) {
-  const skills = program3.command("skills").description("Skills hub commands");
+  const skills = program3.command("skills").description("On-chain skill registry \u2014 register, publish, install, and manage AI agent skills");
   skills.command("register <name> <author>").description("Register a new skill on-chain").action(async (name, author, _opts, cmd) => {
     try {
       const globalOpts = cmd.optsWithGlobals();
@@ -133813,8 +133899,8 @@ async function handleAgentClear(options) {
   }
 }
 function registerAgentCommands(program3) {
-  const agent = program3.command("agent").description("Agent Registry commands (on-chain AI agents)");
-  agent.command("register <agent-id>").description("Register a new agent on-chain").option("--referral <agent-id>", "Referral agent ID").action(async (agentId, opts, cmd) => {
+  const agent = program3.command("agent").description("Agent Registry \u2014 register an on-chain AI agent identity to earn extra rewards and points from PoMI mining");
+  agent.command("register <agent-id>").description("Register a new agent on-chain (costs 1 NARA, 50% off with referral). Agent ID must be lowercase alphanumeric with hyphens.").option("--referral <agent-id>", "Referral agent ID \u2014 saves 50% on registration fee").action(async (agentId, opts, cmd) => {
     try {
       const globalOpts = cmd.optsWithGlobals();
       await handleAgentRegister(agentId, { ...globalOpts, ...opts });
@@ -134048,7 +134134,7 @@ function registerCommands(program3) {
   registerZkIdCommands(program3);
   registerAgentCommands(program3);
   registerConfigCommands(program3);
-  program3.command("address").description("Show wallet address").action(async () => {
+  program3.command("address").description("Show wallet public address (run this first to check if a wallet exists)").action(async () => {
     const opts = program3.opts();
     try {
       await handleWalletAddress(opts);
@@ -134057,7 +134143,7 @@ function registerCommands(program3) {
       process.exit(1);
     }
   });
-  program3.command("balance").description("Check NARA balance").argument("[address]", "Wallet address (optional, defaults to current wallet)").action(async (address) => {
+  program3.command("balance").description("Check NARA balance (native coin, not SOL)").argument("[address]", "Wallet address (optional, defaults to current wallet)").action(async (address) => {
     const opts = program3.opts();
     try {
       await handleWalletBalance(address, opts);
@@ -134066,7 +134152,7 @@ function registerCommands(program3) {
       process.exit(1);
     }
   });
-  program3.command("token-balance <token-address>").description("Check token balance").option("--owner <address>", "Owner address (optional, defaults to current wallet)").action(async (tokenAddress, options) => {
+  program3.command("token-balance <token-address>").description("Check token balance (supports SPL Token and Token-2022)").option("--owner <address>", "Owner address (optional, defaults to current wallet)").action(async (tokenAddress, options) => {
     const opts = program3.opts();
     try {
       await handleTokenBalance(tokenAddress, { ...opts, ...options });
@@ -134123,7 +134209,7 @@ function registerCommands(program3) {
       process.exit(1);
     }
   });
-  program3.command("sign <base64-tx>").description("Sign a base64-encoded transaction").option("--send", "Send the signed transaction", false).action(async (base64Tx, options) => {
+  program3.command("sign <base64-tx>").description("Sign a base64-encoded transaction (supports legacy and versioned transactions)").option("--send", "Sign and broadcast the transaction on-chain", false).action(async (base64Tx, options) => {
     const opts = program3.opts();
     try {
       const wallet = await loadWallet(opts.wallet);
@@ -134174,10 +134260,10 @@ function registerCommands(program3) {
 }
 
 // bin/nara-cli.ts
-var version2 = true ? "1.0.56" : "dev";
+var version2 = true ? "1.0.58" : "dev";
 var program2 = new Command();
-program2.name("naracli").description("CLI for the Nara chain (Solana-compatible)").version(version2);
-program2.option("-r, --rpc-url <url>", "RPC endpoint URL").option("-w, --wallet <path>", "Path to wallet keypair JSON file").option("-j, --json", "Output in JSON format");
+program2.name("naracli").description("CLI for the Nara chain. Native coin is NARA (not SOL). Mine NARA for free via PoMI quests, manage wallets, register agents, and more. Run 'naracli <command> --help' for details on any command.").version(version2);
+program2.option("-r, --rpc-url <url>", "RPC endpoint (default: https://mainnet-api.nara.build/)").option("-w, --wallet <path>", "Path to wallet keypair JSON file (default: ~/.config/nara/id.json)").option("-j, --json", "Output in JSON format");
 registerCommands(program2);
 if (!process.argv.slice(2).length) {
   program2.outputHelp();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "naracli",
-  "version": "1.0.56",
+  "version": "1.0.58",
   "description": "CLI for the Nara chain (Solana-compatible)",
   "homepage": "https://nara.build",
   "repository": {

package/src/cli/commands/agent.ts

@@ -304,13 +304,13 @@ async function handleAgentClear(options: GlobalOptions) {
 export function registerAgentCommands(program: Command): void {
   const agent = program
     .command("agent")
-    .description("Agent Registry commands (on-chain AI agents)");
+    .description("Agent Registry — register an on-chain AI agent identity to earn extra rewards and points from PoMI mining");
 
   // agent register
   agent
     .command("register <agent-id>")
-    .description("Register a new agent on-chain")
-    .option("--referral <agent-id>", "Referral agent ID")
+    .description("Register a new agent on-chain (costs 1 NARA, 50% off with referral). Agent ID must be lowercase alphanumeric with hyphens.")
+    .option("--referral <agent-id>", "Referral agent ID — saves 50% on registration fee")
     .action(async (agentId: string, opts: { referral?: string }, cmd: Command) => {
       try {
         const globalOpts = cmd.optsWithGlobals() as GlobalOptions;

package/src/cli/commands/quest.ts

@@ -16,6 +16,7 @@ import {
 import type { GlobalOptions } from "../types";
 import {
   getQuestInfo,
+  getQuestConfig,
   hasAnswered,
   generateProof,
   submitAnswer,
@@ -106,6 +107,17 @@ async function handleQuestGet(options: GlobalOptions) {
     return;
   }
 
+  // Stake only applies when reward slots have reached maxRewardCount
+  let stakeRequired = quest.effectiveStakeRequirement > 0;
+  try {
+    const config = await getQuestConfig(connection);
+    if (quest.rewardCount < config.maxRewardCount) {
+      stakeRequired = false;
+    }
+  } catch {
+    // If config fetch fails, fall back to showing stake as-is
+  }
+
   const data: Record<string, any> = {
     round: quest.round,
     question: quest.question,
@@ -117,7 +129,8 @@ async function handleQuestGet(options: GlobalOptions) {
     deadline: new Date(quest.deadline * 1000).toLocaleString(),
     timeRemaining: formatTimeRemaining(quest.timeRemaining),
     expired: quest.expired,
-    stakeRequirement: `${quest.effectiveStakeRequirement.toFixed(4)} NARA`,
+    stakeRequired,
+    stakeRequirement: stakeRequired ? `${quest.effectiveStakeRequirement.toFixed(4)} NARA` : "0 NARA",
     stakeHigh: `${quest.stakeHigh} NARA`,
     stakeLow: `${quest.stakeLow} NARA`,
     avgParticipantStake: `${quest.avgParticipantStake} NARA`,
@@ -135,8 +148,10 @@ async function handleQuestGet(options: GlobalOptions) {
     console.log(
       `  Reward slots: ${quest.winnerCount}/${quest.rewardCount} (${quest.remainingSlots} remaining)`
     );
-    if (quest.effectiveStakeRequirement > 0) {
+    if (stakeRequired) {
       console.log(`  Stake requirement: ${quest.effectiveStakeRequirement.toFixed(4)} NARA (decays ${quest.stakeHigh} → ${quest.stakeLow})`);
+    } else {
+      console.log(`  Stake requirement: none`);
     }
     console.log(`  Deadline: ${new Date(quest.deadline * 1000).toLocaleString()}`);
     if (quest.timeRemaining > 0) {
@@ -148,6 +163,55 @@ async function handleQuestGet(options: GlobalOptions) {
   }
 }
 
+// ─── Command: quest config ───────────────────────────────────────
+async function handleQuestConfig(options: GlobalOptions) {
+  const rpcUrl = getRpcUrl(options.rpcUrl);
+  const connection = new Connection(rpcUrl, "confirmed");
+
+  let config;
+  try {
+    config = await getQuestConfig(connection);
+  } catch (err: any) {
+    printError(`Failed to fetch quest config: ${err.message}`);
+    process.exit(1);
+  }
+
+  const DECIMALS = 1e9;
+  const rewardPerShare = config.rewardPerShare / DECIMALS;
+  const extraReward = config.extraReward / DECIMALS;
+  const stakeBpsHigh = config.stakeBpsHigh;
+  const stakeBpsLow = config.stakeBpsLow;
+
+  const data = {
+    authority: config.authority.toBase58(),
+    questAuthority: config.questAuthority.toBase58(),
+    treasury: config.treasury.toBase58(),
+    minRewardCount: config.minRewardCount,
+    maxRewardCount: config.maxRewardCount,
+    rewardPerShare,
+    extraReward,
+    stakeBpsHigh,
+    stakeBpsLow,
+    decayMs: config.decayMs,
+    minQuestInterval: config.minQuestInterval,
+  };
+
+  if (options.json) {
+    formatOutput(data, true);
+  } else {
+    console.log("");
+    console.log(`  Min Reward Count:   ${data.minRewardCount}`);
+    console.log(`  Max Reward Count:   ${data.maxRewardCount}`);
+    console.log(`  Reward Per Share:   ${rewardPerShare} NARA`);
+    console.log(`  Extra Reward:       ${extraReward} NARA`);
+    console.log(`  Stake BPS High:     ${stakeBpsHigh / 100}%`);
+    console.log(`  Stake BPS Low:      ${stakeBpsLow / 100}%`);
+    console.log(`  Decay (ms):         ${data.decayMs}`);
+    console.log(`  Min Quest Interval: ${data.minQuestInterval}s`);
+    console.log("");
+  }
+}
+
 // ─── Command: quest answer ───────────────────────────────────────
 async function handleQuestAnswer(
   answer: string,
@@ -400,12 +464,12 @@ function handleSubmitError(err: any) {
 export function registerQuestCommands(program: Command): void {
   const quest = program
     .command("quest")
-    .description("Quest commands");
+    .description("PoMI quest commands — mine NARA by answering on-chain quests with ZK proofs");
 
   // quest get
   quest
     .command("get")
-    .description("Get current quest info")
+    .description("Get current quest info (question, deadline, difficulty, stake requirement)")
     .action(async (_opts: any, cmd: Command) => {
       try {
         const globalOpts = cmd.optsWithGlobals() as GlobalOptions;
@@ -419,12 +483,12 @@ export function registerQuestCommands(program: Command): void {
   // quest answer
   quest
     .command("answer <answer>")
-    .description("Submit an answer")
-    .option("--relay [url]", `Submit via relay service, gasless (default: ${DEFAULT_QUEST_RELAY_URL})`)
-    .option("--agent <name>", "Agent identifier (default: naracli)")
-    .option("--model <name>", "Model identifier")
-    .option("--referral <agent-id>", "Referral agent ID")
-    .option("--stake [amount]", 'Stake NARA before answering ("auto" to top-up to requirement, or a number)')
+    .description("Submit a quest answer with ZK proof. Generates a proof locally and submits on-chain. Use --relay when balance is 0 (gasless). Always pass --agent and --model for reward tracking.")
+    .option("--relay [url]", `Submit via gasless relay (default: ${DEFAULT_QUEST_RELAY_URL}, backup: https://quest2-api.nara.build/)`)
+    .option("--agent <name>", "Agent/platform type: claude-code, cursor, chatgpt, openclaw, etc. (default: naracli)")
+    .option("--model <name>", "AI model used: claude-opus-4-6, claude-sonnet-4-6, gpt-4o, etc.")
+    .option("--referral <agent-id>", "Referral agent ID for earning referral points")
+    .option("--stake [amount]", 'Stake NARA in the same tx ("auto" to top-up to requirement, or an exact amount)')
     .action(async (answer: string, opts: any, cmd: Command) => {
       try {
         const globalOpts = cmd.optsWithGlobals() as GlobalOptions;
@@ -437,6 +501,20 @@ export function registerQuestCommands(program: Command): void {
       }
     });
 
+  // quest config
+  quest
+    .command("config")
+    .description("Show quest program config (reward counts, stake params, decay, intervals)")
+    .action(async (_opts: any, cmd: Command) => {
+      try {
+        const globalOpts = cmd.optsWithGlobals() as GlobalOptions;
+        await handleQuestConfig(globalOpts);
+      } catch (error: any) {
+        printError(error.message);
+        process.exit(1);
+      }
+    });
+
   // quest stake
   quest
     .command("stake <amount>")

package/src/cli/commands/skills.ts

@@ -281,7 +281,7 @@ async function handleSkillsDelete(name: string, options: GlobalOptions & { yes?:
 export function registerSkillsCommands(program: Command): void {
   const skills = program
     .command("skills")
-    .description("Skills hub commands");
+    .description("On-chain skill registry — register, publish, install, and manage AI agent skills");
 
   // skills register
   skills

package/src/cli/commands/wallet.ts

@@ -55,12 +55,12 @@ const DEFAULT_WALLET_PATH = _DEFAULT_WALLET_PATH.startsWith("~")
 export function registerWalletCommands(program: Command): void {
   const wallet = program
     .command("wallet")
-    .description("Wallet management commands");
+    .description("Wallet management — create or import a keypair for signing transactions");
 
   // wallet create
   wallet
     .command("create")
-    .description("Create a new wallet")
+    .description("Create a new wallet keypair (saved to ~/.config/nara/id.json by default)")
     .option("-o, --output <path>", "Output path for wallet file (default: ~/.config/nara/id.json)")
     .action(async (options: { output?: string }) => {
       try {

package/src/cli/index.ts

@@ -85,7 +85,7 @@ export function registerCommands(program: Command): void {
   // Top-level: address
   program
     .command("address")
-    .description("Show wallet address")
+    .description("Show wallet public address (run this first to check if a wallet exists)")
     .action(async () => {
       const opts = program.opts() as GlobalOptions;
       try {
@@ -99,7 +99,7 @@ export function registerCommands(program: Command): void {
   // Top-level: balance
   program
     .command("balance")
-    .description("Check NARA balance")
+    .description("Check NARA balance (native coin, not SOL)")
     .argument("[address]", "Wallet address (optional, defaults to current wallet)")
     .action(async (address: string | undefined) => {
       const opts = program.opts() as WalletBalanceOptions;
@@ -114,7 +114,7 @@ export function registerCommands(program: Command): void {
   // Top-level: token-balance
   program
     .command("token-balance <token-address>")
-    .description("Check token balance")
+    .description("Check token balance (supports SPL Token and Token-2022)")
     .option("--owner <address>", "Owner address (optional, defaults to current wallet)")
     .action(async (tokenAddress: string, options: { owner?: string }) => {
       const opts = program.opts() as TokenBalanceOptions;
@@ -199,8 +199,8 @@ export function registerCommands(program: Command): void {
   // Top-level: sign
   program
     .command("sign <base64-tx>")
-    .description("Sign a base64-encoded transaction")
-    .option("--send", "Send the signed transaction", false)
+    .description("Sign a base64-encoded transaction (supports legacy and versioned transactions)")
+    .option("--send", "Sign and broadcast the transaction on-chain", false)
     .action(async (base64Tx: string, options: { send?: boolean }) => {
       const opts = program.opts() as GlobalOptions;
       try {