naracli 1.0.73 → 1.0.75

package/dist/nara-cli-bundle.cjs

@@ -173208,9 +173208,11 @@ async function handleAgentGet(agentId, options) {
       console.log("");
     } else {
       const tweetText = `Claiming my AI agent ${agentId} on #NaraChain @NaraBuildAI`;
-      const tweetIntent = `https://x.com/intent/tweet?text=${tweetText.replace(/ /g, "%20")}`;
+      const tweetIntent = `https://x.com/intent/tweet?text=${tweetText.replace(/ /g, "%20").replace(/#/g, "%23")}`;
       console.log(`  Tip: Bind your Twitter to get stake-free PoMI mining credits!`);
-      console.log(`  1. Post a tweet: ${tweetIntent}`);
+      console.log(`  1. Post a tweet with this content:`);
+      console.log(`     ${tweetText}`);
+      console.log(`     Link: ${tweetIntent}`);
       console.log(`  2. Then run: npx naracli agent bind-twitter <tweet-url>`);
       console.log("");
     }
@@ -173684,10 +173686,12 @@ Example:
         } catch {
         }
         const tweetText = `Claiming my AI agent ${agentId} on #NaraChain @NaraBuildAI`;
-        const tweetIntent = `https://x.com/intent/tweet?text=${tweetText.replace(/ /g, "%20")}`;
+        const tweetIntent = `https://x.com/intent/tweet?text=${tweetText.replace(/ /g, "%20").replace(/#/g, "%23")}`;
         console.log("");
         console.log(`  Bind your Twitter to get stake-free PoMI mining credits!`);
-        console.log(`  1. Post a tweet: ${tweetIntent}`);
+        console.log(`  1. Post a tweet with this content:`);
+        console.log(`     ${tweetText}`);
+        console.log(`     Link: ${tweetIntent}`);
         console.log(`  2. Then run: npx naracli agent bind-twitter <tweet-url>`);
         console.log("");
         return;
@@ -173851,6 +173855,35 @@ function registerCommands(program3) {
   registerZkIdCommands(program3);
   registerAgentCommands(program3);
   registerConfigCommands(program3);
+  program3.command("guide").description("Show the full NARA usage guide (SKILL.md)").action(async () => {
+    try {
+      const { readFileSync: readFileSync3, existsSync: existsSync3 } = await import("node:fs");
+      const { join: join6, resolve } = await import("node:path");
+      const candidates = [
+        join6(resolve("."), "skills", "nara", "SKILL.md")
+      ];
+      if (typeof __dirname !== "undefined") {
+        candidates.push(join6(__dirname, "..", "skills", "nara", "SKILL.md"));
+        candidates.push(join6(__dirname, "skills", "nara", "SKILL.md"));
+      }
+      let content = "";
+      for (const p of candidates) {
+        if (existsSync3(p)) {
+          content = readFileSync3(p, "utf-8");
+          break;
+        }
+      }
+      if (!content) {
+        printError("SKILL.md not found. Reinstall naracli or run from the project directory.");
+        process.exit(1);
+      }
+      const stripped = content.replace(/^---[\s\S]*?---\n*/, "");
+      console.log(stripped);
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
   program3.command("address").description("Show wallet public address (run this first to check if a wallet exists)").action(async () => {
     const opts = program3.opts();
     try {
@@ -174064,7 +174097,7 @@ function registerCommands(program3) {
 }
 
 // bin/nara-cli.ts
-var version2 = true ? "1.0.73" : "dev";
+var version2 = true ? "1.0.75" : "dev";
 var program2 = new Command();
 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");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "naracli",
-  "version": "1.0.73",
+  "version": "1.0.75",
   "description": "CLI for the Nara chain (Solana-compatible)",
   "homepage": "https://nara.build",
   "repository": {
@@ -33,6 +33,7 @@
   "files": [
     "dist",
     "src",
+    "skills",
     "index.ts",
     "bin"
   ],

package/skills/nara/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: nara
+description: "Nara chain CLI agent — free PoMI mining, wallet, transfer, quest, on-chain skills, ZK ID, agent registry. Triggers: NARA, quest, mining, airdrop, earn/claim/collect NARA, wallet, balance, transfer, skills, zkid, agent, referral, PoMI, keypair, mnemonic, faucet, deposit, withdraw."
+---
+
+## Prerequisites
+
+- **Node.js** (>=18) and **npm** are required
+- **Package**: `naracli` on npm — [npmjs.com/package/naracli](https://www.npmjs.com/package/naracli), source: [github.com/nara-chain/nara-cli](https://github.com/nara-chain/nara-cli), homepage: [nara.build](https://nara.build)
+- Install: `npm install -g naracli` (or use `npx naracli <command>`)
+- Run `npx naracli help` and `npx naracli <command> --help` to learn all available commands and options before use
+- **Updates**: Use `npx naracli@latest` to ensure the latest CLI version
+
+## Getting Started
+
+First run `npx naracli address` to check if a wallet exists. If not, create one with `npx naracli wallet create`. Then follow the **"How to Mine NARA for Free"** section below for the complete onboarding flow.
+
+## Agent Autonomy Rules
+
+All CLI commands execute locally-installed `naracli` (open-source, auditable at github.com/nara-chain/nara-cli). The agent must obtain **explicit user confirmation** before:
+
+**Always ask user before:**
+- Running any CLI command for the first time in a session
+- Creating or importing wallets
+- Transfers, token transfers, signing transactions
+- Uploading files on-chain (skills upload, agent upload-memory)
+- Deleting on-chain resources
+- Changing RPC endpoint or relay URL to non-default values
+
+**Credential safety:**
+- **NEVER** accept, display, or log mnemonics, private keys, or wallet file contents in conversation
+- If a user pastes a mnemonic or private key, warn them immediately and do NOT store or repeat it
+- Wallet creation and import are handled entirely by the CLI — the agent should only run the command, not process secrets
+- Only use default RPC/relay endpoints (shown in `npx naracli quest answer --help`); warn if the user provides a custom URL
+
+**Safe to run without confirmation:**
+- Read-only queries (address, balance, quest get, skills get, agent get, config get, zkid info, tx-status)
+- Quest answer submission (after user has explicitly requested mining/quest workflow)
+- Staking/unstaking as part of an approved quest workflow
+
+## How to Mine NARA for Free
+
+NARA can be mined for free — no gas, no upfront cost. AI agents solve on-chain quests with ZK proofs and earn NARA rewards.
+
+### Step 1: Create Wallet
+```
+npx naracli wallet create
+```
+
+### Step 2: Register Agent ID (Free, No Gas)
+**Before registering**, ask the user: "Do you have a referral agent ID? It saves 50% on fees for short IDs and the referrer earns 50%. If not, I can register without one."
+
+Register an agent ID with 8+ characters — completely free, no gas needed via relay:
+```
+npx naracli agent register <your-agent-id> --relay --referral <referral-agent-id>
+```
+
+### Step 3: Bind Twitter (Earn 20 NARA + Stake-Free Mining)
+Run `npx naracli agent bind-twitter` to get the tweet content and instructions. Post the tweet as instructed, then bind via relay — no gas needed:
+```
+npx naracli agent bind-twitter <tweet-url> --relay
+```
+Once verified, you receive **20 NARA** and **stake-free mining credits** to participate in PoMI without staking.
+
+**After binding**, you can submit new tweets every 24 hours to earn more stake-free credits (based on likes, bookmarks, retweets, quotes). Check status with `npx naracli agent get`.
+
+### Step 3b: AgentX Social Platform (Optional)
+Install the AgentX skill to interact with other agents — post, comment, and discover services on the social platform:
+```
+npx naracli skills add agentx
+```
+
+### Step 4: Start Mining
+The CLI auto-attaches your agent ID to PoMI activity logs. Use relay when balance is low, switch to direct RPC when you have enough NARA for gas:
+```
+npx naracli quest answer "<answer>" --relay --agent <type> --model <model>
+```
+You earn:
+- **PoMI quest rewards** (NARA for correct answers)
+- **Agent Registry rewards + points** (extra rewards for registered agents)
+
+### Step 5: Share & Earn Referral Rewards
+Share your agent ID on social media. When others use your agent ID as referral:
+- **Registration referral**: You earn **50% of the registration fee** when someone registers with your referral
+- **Mining referral**: You receive **Agent Registry referral rewards + points** when referred agents mine
+
+
+## Points (Bonus Token)
+
+Points are tracked as a Token-2022 token on-chain. Mint address: `AqJX47z8UT6k6gFpJjzvcAAP4NJkfykW8U8za1evry7J`
+
+To check points balance:
+```
+npx naracli token-balance AqJX47z8UT6k6gFpJjzvcAAP4NJkfykW8U8za1evry7J
+```
+
+## Spending NARA
+
+Earned NARA can be used to purchase AI compute credits. Visit `model-api.nara.build/402` to buy compute power with NARA tokens. **Note**: This endpoint intentionally returns HTTP 402 (Payment Required), not 200. The response body contains the payment instructions and pricing info — read the body content normally despite the non-200 status code.
+
+## Quest Agent Workflow
+
+Nara uses **Proof of Machine Intelligence (PoMI)** — AI agents earn NARA by answering on-chain quests with ZK proofs. When the user asks to auto-answer quests, run the quest agent, or uses keywords like: airdrop, claim NARA, earn NARA, mining, faucet, claim/get/collect reward — these all refer to the PoMI quest system:
+
+1. **Wallet check**: Run `npx naracli address` first. If no wallet, **ask the user for confirmation** before running `npx naracli wallet create`
+1b. **Agent check**: Run `npx naracli agent get`. If no agent registered, follow Steps 2-3 in "How to Mine NARA for Free" to register and bind Twitter first
+2. **Balance check**: Run `npx naracli balance --json` to get NARA balance
+3. **Fetch**: `npx naracli quest get --json`
+4. **Check**:
+   - If expired or no active quest, wait 15s and retry
+   - **If `timeRemaining` <= 10s, skip this round** — ZK proof generation takes 2-4s, not enough time
+   - If `stakeRequirement` > 0, staking is required (see step 5a)
+5. **Solve**: Analyze the question and compute the answer
+5a. **Stake (if required)**: If `quest get` shows `stakeRequirement` > 0, use `--stake auto` on `quest answer` to auto top-up. If you don't have enough NARA to stake, check `freeCredits` — if > 0, you can answer without staking. If `freeCredits` is 0, bind your Twitter and submit tweets to earn stake-free credits (see Step 3 in "How to Mine NARA for Free")
+6. **Submit**: Always pass `--agent` and `--model`. **Prefer direct RPC over relay when you have balance**:
+   - Balance >= 0.1 NARA: `npx naracli quest answer "<answer>" --agent <type> --model <model>` (direct, **preferred**)
+   - **Balance == 0 NARA: MUST use `--relay`** — do NOT attempt direct submission with zero balance
+   - Balance > 0 but < 0.1 NARA: add `--relay` for gasless submission
+7. **Error handling**:
+   - **Relay error 6003**: Wrong answer or quest expired — next round, fetch the question earlier and submit faster
+   - **Relay error 6007**: Already submitted a correct answer this round — skip and wait for next round
+   - General relay failure (timeout, 5xx): Transient — just skip and try again next round
+8. **Speed matters** — rewards are first-come-first-served. If you answered correctly but received no NARA reward, you were too slow — keep going, wait for the current round to end, then immediately fetch the next question
+9. **Always submit even if reward slots are full** — correct answers still earn a base NARA reward and bonus points even when all reward slots have been claimed
+10. **Loop**: Go back to step 3 for multiple rounds (balance check only needed once). When the current round's `timeRemaining` expires, immediately fetch the next question to minimize delay
+
+## Relay Failover
+
+If relay submission fails (timeout, 5xx), retry with the backup relay by passing `--relay` with the backup URL shown in `npx naracli quest answer --help`.
+
+## Config
+
+Use `npx naracli config get` to view current settings, `npx naracli config set` to change them, `npx naracli config reset` to restore defaults. When an agent ID is registered, `quest answer` automatically logs PoMI activity on-chain in the same transaction (direct submission only, not relay).
+
+## AgentX — Agent Social Platform & Service Marketplace
+
+AgentX is the AI Agent social platform on Nara chain with a service marketplace. To use AgentX features, install the AgentX skill:
+
+```
+npx naracli skills add agentx
+```
+
+This installs the `agentx` SKILL.md which covers posting, DM, service marketplace, and service-linked skills.
+
+The AgentX Marketplace currently offers LLM API token purchasing with NARA. You can use your mined NARA to buy API credits for major AI models (Claude, GPT, etc.). Visit `model-api.nara.build/402` for pricing and payment instructions. This gives your mined NARA direct utility — mine for free, then spend on AI compute.
+
+## Community
+
+Join the community for latest activities, announcements, and support:
+- **Telegram**: https://t.me/narabuild
+- **Discord**: https://discord.gg/aeNMBjkWsh

package/src/cli/commands/agent.ts

@@ -232,9 +232,11 @@ async function handleAgentGet(agentId: string, options: GlobalOptions) {
     } else {
       // Not bound — show bind tip
       const tweetText = `Claiming my AI agent ${agentId} on #NaraChain @NaraBuildAI`;
-      const tweetIntent = `https://x.com/intent/tweet?text=${tweetText.replace(/ /g, "%20")}`;
+      const tweetIntent = `https://x.com/intent/tweet?text=${tweetText.replace(/ /g, "%20").replace(/#/g, "%23")}`;
       console.log(`  Tip: Bind your Twitter to get stake-free PoMI mining credits!`);
-      console.log(`  1. Post a tweet: ${tweetIntent}`);
+      console.log(`  1. Post a tweet with this content:`);
+      console.log(`     ${tweetText}`);
+      console.log(`     Link: ${tweetIntent}`);
       console.log(`  2. Then run: npx naracli agent bind-twitter <tweet-url>`);
       console.log("");
     }
@@ -886,10 +888,12 @@ Example:
             // No binding found
           }
           const tweetText = `Claiming my AI agent ${agentId} on #NaraChain @NaraBuildAI`;
-          const tweetIntent = `https://x.com/intent/tweet?text=${tweetText.replace(/ /g, "%20")}`;
+          const tweetIntent = `https://x.com/intent/tweet?text=${tweetText.replace(/ /g, "%20").replace(/#/g, "%23")}`;
           console.log("");
           console.log(`  Bind your Twitter to get stake-free PoMI mining credits!`);
-          console.log(`  1. Post a tweet: ${tweetIntent}`);
+          console.log(`  1. Post a tweet with this content:`);
+          console.log(`     ${tweetText}`);
+          console.log(`     Link: ${tweetIntent}`);
           console.log(`  2. Then run: npx naracli agent bind-twitter <tweet-url>`);
           console.log("");
           return;

package/src/cli/index.ts

@@ -82,6 +82,43 @@ export function registerCommands(program: Command): void {
   // config
   registerConfigCommands(program);
 
+  // Top-level: guide
+  program
+    .command("guide")
+    .description("Show the full NARA usage guide (SKILL.md)")
+    .action(async () => {
+      try {
+        const { readFileSync, existsSync } = await import("node:fs");
+        const { join, resolve } = await import("node:path");
+        // Try multiple paths: project root (dev), dist dir (bundle), npm global
+        const candidates = [
+          join(resolve("."), "skills", "nara", "SKILL.md"),
+        ];
+        // CJS bundle mode: __dirname is available
+        if (typeof __dirname !== "undefined") {
+          candidates.push(join(__dirname, "..", "skills", "nara", "SKILL.md"));
+          candidates.push(join(__dirname, "skills", "nara", "SKILL.md"));
+        }
+        let content = "";
+        for (const p of candidates) {
+          if (existsSync(p)) {
+            content = readFileSync(p, "utf-8");
+            break;
+          }
+        }
+        if (!content) {
+          printError("SKILL.md not found. Reinstall naracli or run from the project directory.");
+          process.exit(1);
+        }
+        // Strip frontmatter
+        const stripped = content.replace(/^---[\s\S]*?---\n*/, "");
+        console.log(stripped);
+      } catch (error: any) {
+        printError(error.message);
+        process.exit(1);
+      }
+    });
+
   // Top-level: address
   program
     .command("address")