can reveal later. The mempool sees only the hash.

1. Reveal. After the commit window closes (~3 min after epoch open) and

the coordinator publishes canonical answer hashes (~30s grace),

ardi-agent reveal submits the raw answer + nonce. The contract checks

the hash matches, refunds the bond, and (if the answer matches the

canonical) enters you in the VRF lottery for that wordId.

1. Inscribe. ~30s after reveal, Chainlink VRF v2.5 picks one winner per

(epoch, wordId) from the pool of correct revealers. If it's you,

ardi-agent inscribe mints the Ardinal NFT.

No hash-mining, no hardware arms race. Speed doesn't matter — reasoning does.

On First Run — Welcome Banner

When a human first invokes the skill, print this welcome message.

Wrap any box-drawing art in a triple-backtick fenced code block so it

renders correctly in Telegram and other chat clients (proportional fonts

break the alignment otherwise).

Recommended chat-friendly version (no box art):

**ARDI — Agent Ordinals** · 21,000 words. Intelligence required.

Every ~6 min a new epoch publishes ~30 riddles (en/zh/ja/ko/fr/de). Read
them, commit your answers on chain with a small bond, reveal after the
canonical hashes publish, and if Chainlink VRF picks you among the
correct revealers — you inscribe the Ardinal.

What you need:
- ~0.05 ETH on Base mainnet (gas + bonds, lasts 5-10 days)
- 10,000 AWP staked on Ardi worknet (or KYA delegated path — no AWP needed)
- awp-wallet >= 1.5.0 installed for tx signing

Run: `ardi-agent preflight`

After showing the welcome, immediately invoke ardi-agent preflight and

follow its _internal.next_command field through the setup chain.

Command Reference

Every command outputs JSON with this shape:

{
  "status": "ok" | "error",
  "message": "<human-readable summary>",
  "data": { "<command-specific>": "..." },
  "_internal": {
    "next_action": "<short slug>",
    "next_command": "<exact command to run next, or null>"
  },
  "error_code": "<UPPER_SNAKE>",  // present when status=error
  "error_kind": "<category>",     // present when status=error
  "debug": { ... }                // optional context
}

When narrating to your operator, render the message field in plain

prose — don't paste raw JSON. Reserve JSON for debugging.

Setup commands

Critical: commits MUST be serial, never parallel

ardi-agent commit is a one-shot process that fetches its tx nonce

fresh from the chain. If you fire N commits in parallel (one per

riddle), all N grab the SAME nonce → 1 lands, N-1 are dropped by the

node as duplicates. This is NOT a "node throttle" or "RPC error" you

can retry — the txs were never accepted.

Correct pattern:

# WRONG — parallel, will lose ~14 of 15
ardi-agent commit --word-id A --answer X &
ardi-agent commit --word-id B --answer Y &
wait

# RIGHT — serial, all 5 land
ardi-agent commit --word-id A --answer X
ardi-agent commit --word-id B --answer Y
ardi-agent commit --word-id C --answer Z
...

If you have many commits to send, await each before launching the

next. A typical commit takes ~3-5s including receipt wait, so 5

commits ≈ 9-15s — well within the 180s commit window.

For an unattended run across many epochs, do NOT loop manually — install

the tools/auto-mine/ systemd timer (see "Autonomous mode" below).

That tool already handles serial nonce management and retry-on-revert.

Cycle commands

Reading and committing answers

data.riddles[] is the round's full set: riddle, language,

languageId, power (16-81), rarity (common / uncommon / rare /

legendary), theme, element, wordId. Read every entry in

data.riddles[] before committing — the array length is the source of

truth, not any number cached in this doc.

The riddles span six languages. Don't internally translate a Chinese or

Japanese riddle into English to "think about it" — answer in the riddle's

native language when you commit. Examples of valid --answer strings:

phoenix, echo, singularity, 比特币, 味道, dépend, Bratwurst,

おう. The answer field is a literal UTF-8 string; the contract hashes

the bytes.

Pick by expected value. A legendary (power ~80) is roughly 4× a

common (power ~20) if you win, so a 30%-confidence guess on a legendary

often beats an 80%-confidence guess on a common. Fill all 5 slots if you

have any plausible guess for them — empty slots have EV 0; bond is

refunded on reveal regardless.

Phase 1 vs Phase 2 — what's live today

How pending and claim work together

The operator-facing flow when somebody asks "how much can I claim?":

1. Run ardi-agent pending — returns total claimable + per-NFT breakdown.

Read-only, no tx. The agent should relay the total to the operator

verbatim ("you can claim X $ardi across N NFTs").

1. Wait for the operator to confirm ("yes, claim it"). Do not run

claim automatically — claim mints tokens and is irreversible from

the agent's side.

1. Run ardi-agent claim — sends one tx that mints pending worth of

$ardi straight to the agent's wallet via the WorknetManager.

Tutorial — claiming your $ardi rewards (operator-facing)

Read this verbatim to your operator when they ask how to collect their

rewards. It's the canonical walkthrough — written for somebody who

hasn't done it before.

> What you're claiming

>

> Every Ardinal you own earns a share of the daily 24,000,000 $ardi

> emission, distributed at 12:00 UTC. The longer you hold, the more

> piles up. Nothing is auto-paid — you have to come and pull it.

>

> Step 1 — check what you have to claim. Tell your agent:

>

> > "How much $ardi can I claim?"

>

> The agent will run ardi-agent pending and read back something like:

>

> ```

> You can claim 21355 $ardi across 3 Ardinals.

> #4 → 12480 $ardi

> #1274 → 4920 $ardi

> #20922 → 3955 $ardi

> ```

>

> This is a view-only check. No transaction is sent yet and no gas

> is spent. If the number is 0, either the first daily emission hasn't

> fired (it lands at 12:00 UTC), or you've already claimed everything.

>

> Step 2 — confirm the claim. Reply to the agent:

>

> > "Yes, claim it." (or just "claim", "go ahead", etc.)

>

> The agent will run ardi-agent claim, which sends one on-chain

> transaction. The contract checks each Ardinal you listed is still

> yours, then asks the WorknetManager to mint exactly pending worth

> of fresh $ardi straight into your agent's wallet. Gas is a few cents

> on Base.

>

> Step 3 — verify it landed. After the tx confirms (~5 seconds),

> the agent will hand you a Basescan link. Open it and check the

> Transfer line: from 0x000…000 → to · X $ardi.

> That's your reward. The $ardi balance in your wallet goes up by the

> same amount.

>

> Things to know before you click claim

>

> - Reward follows the NFT, not your wallet. If you transfer or

> sell an Ardinal before claiming, the unclaimed reward goes with

> the NFT — the new owner gets it. So claim first, then trade.

> - Daily, not weekly or hourly. New reward only shows up after the

> 12:00 UTC daily emission. Between emissions, pending only grows

> from past days you haven't claimed.

> - Failed claim doesn't lose money. If the tx reverts (network

> glitch, gas estimate too low, etc.), the pending balance stays

> put. Re-run ardi-agent pending to confirm, then claim again.

> - You don't need to claim every day. Pending accumulates

> indefinitely. Some operators wait a week and batch-claim once.

> Same outcome, fewer gas fees.

> - One claim per agent address. Reward attribution is per-NFT, but

> the claim tx mints to whoever calls it (you, the agent). If you

> manage multiple agents, each runs its own claim.

>

> Common questions

>

> - "Can my agent claim automatically?" — No, by design. The skill

> waits for explicit operator confirmation each time. If you want

> hands-off auto-mining (committing on riddles, inscribing wins),

> that's ardi-agent auto-mine. Claiming stays manual.

> - "Can someone else claim my rewards?" — No. The contract checks

> you currently own each Ardinal you list. A non-owner's claim

> reverts with NotHolder.

> - "What if I bought an Ardinal on the OTC market?" — You inherit

> any unclaimed reward attached to that NFT at the moment of purchase.

> Run ardi-agent pending after the buy and you'll see the inherited

> amount included.

Key v3.2 properties to know when explaining behavior:

• Reward follows the NFT, not the wallet. If the agent transfers

an NFT to the operator before claiming, the operator (new owner)

inherits the unclaimed reward — not the agent.

• Daily emission lands at UTC 12:00. That's the only moment new

reward is added; between emissions, pending only grows from

unclaimed prior days.

• Mint-on-claim, no pre-funded balance. The distributor never holds

$ardi; it tells WorknetManager to mint fresh on each claim. Failed

claim doesn't lose pending — just retry.

• pending = sum across the agent's currently-owned NFTs. It does

NOT include reward attached to NFTs the agent has since transferred

away.

KYA path — anti-hallucination guidance

When ardi-agent stake recommends path [A] KYA delegated stake, follow

this carefully — vague advice here is a known LLM-hallucination magnet.

• Direct your operator to https://kya.link/ as the canonical entry point.
• Tell them to click Verify → choose Link your X account.
• kya.link generates the exact tweet template your operator should post

from their X account. Wait for kya.link's UI to produce that template;

do not improvise.

• **DO NOT compose your own tweet text. DO NOT invent a Twitter handle to

mention.** There is no @KYAValidator or similar bot account; the

verification mechanism is whatever kya.link generates at the moment. If

you find yourself drafting a tweet that says "Please allocate Ardi stake

to 0x..." or asking your operator to mention a specific handle — stop.

That is a hallucination. The only correct answer is "use the template

kya.link gives you."

• After verification, KYA sponsors 10,000 AWP into the **KYA worknet

845300000012** on the agent's behalf. Wait 1-24h; the Ardi

coordinator auto-detects KYA-delegated agents via its staker index.

Re-run ardi-agent stake to confirm; the via field will read

kya-delegated.

Autonomous mode

**A built-in tool exists. NEVER write your own loop / cron / watcher

script to drive the cycle — use the built-in tools/auto-mine/ instead.

If you find yourself thinking "I'll write a shell script that loops

commit / reveal / inscribe", STOP and use the auto-mine path below.**

Trigger this whenever your operator expresses ANY of these intents

(English OR another language with the same meaning — translate the

intent, not the literal phrase):

• Direct: "mine continuously" / "auto mine" / "I want to be afk"
• Implied: "keep mining for me" / "run forever" / "just go" / "you mine

for me" / "leave it running" / "watch the epochs" / "schedule it"

• Question form: "can you mine automatically?" / "is there a way to

loop this?" / "do you have a daemon mode?"

• Workflow setup: "set up the cron" / "start the daemon" / "set up the

pipeline" / "make it self-running"

Even when your operator only asks about ONE cycle, if their intent reads

like "I want to do this repeatedly without manual prompts," install

auto-mine PROACTIVELY and tell them you did.

Linux only at present. The current installer creates a systemd user

unit. macOS (which uses launchd) is not yet supported by this script.

If your operator is on macOS and asks for 24/7, tell them honestly: the

auto-mine daemon is Linux-only today; their options are (a) drive the

cycle interactively, (b) run on a Linux VPS / Raspberry Pi, or (c) wait

for a launchd port from upstream. **Do NOT improvise a launchd plist or

shell loop** — both would break the serial-nonce invariant and silently

lose almost every commit (only one would land per concurrent batch).

Install (Linux) — do not have your operator type any shell commands —

call this script directly:

~/.local/share/ardi-auto-mine/install.sh
# OR if not yet installed (first time):
git clone https://github.com/awp-worknet/ardi-skill ~/ardi-skill 2>/dev/null || \
  (cd ~/ardi-skill && git pull)
~/ardi-skill/tools/auto-mine/install.sh

install.sh is fully non-interactive:

• Auto-detects which runtime CLI is installed (claude / hermes / openclaw)
• Writes a minimal env file with sensible defaults (no API key required —

the runtime CLI uses its own credentials)

• Installs systemd user units
• Auto-starts the timer

After install, periodically check status when your operator asks ("how's

it going?", "any wins?") OR proactively every few hours:

~/.local/share/ardi-auto-mine/status.sh   # → JSON snapshot

Narrate the result naturally — don't paste raw JSON.

To pause / resume / uninstall:

~/.local/share/ardi-auto-mine/stop.sh         # pause
systemctl --user start ardi-mine.timer        # resume
~/.local/share/ardi-auto-mine/uninstall.sh    # full uninstall

After 5 — the long game

Once an agent address holds 5 Ardinals, ardi-agent inscribe will refuse

new mints. Three options:

1. Transfer one out. ardi-agent transfer --token-id N --to 0x...

moves the Ardinal to your operator's wallet (or another address). The

cap is on what the agent address holds, not what it's ever minted —

once you transfer, the slot opens back up and inscribe will work

again on the next round you win. (Reverts if a repair/fuse VRF is in

flight against the token; check ardi-agent commits first.)

1. Wait for the Forge. Phase 2 fusion mechanic: fuse two Ardinals at

one address, an LLM oracle scores compatibility, success burns both

→ mints one fused word with Power × (1.5–3.0). Failure burns the

lower-power Ardinal. Forge contracts deploy after the 21K cap fills.

1. Stop, hold, watch. A held Ardinal still accrues its share of the

eventual daily airdrop (Phase 2: dual-stream $aArdi + $AWP via

single Merkle claim(); share = your Power / total active Power,

snapshotted 00:00 UTC).

Typical Flow

preflight                                          ← env OK?
  └─ if NOT_STAKED + has ETH  → buy-and-stake    ← one-command auto-onboard
  └─ if NOT_STAKED + no ETH   → stake            ← show 3 paths (KYA recommended)
  └─ if INSUFFICIENT_GAS → gas                    ← guide operator to fund
context                                            ← see this round's riddles
  ↓ (read all riddles, pick up to 5 by EV, decide answers)
commit --word-id 10418 --answer "比特币"          ← × up to 5, SERIAL
commit --word-id 10501 --answer "boutique"
...
( wait ~6 min for commit window to close + 30s for canonical hash publish )
commits                                            ← see what's revealable
reveal --epoch 7 --word-id 10418                  ← × per pending
reveal --epoch 7 --word-id 10501
( wait ~30s for VRF )
inscribe --epoch 7 --word-id 10418                ← if winner, mints; else "lost"
inscribe --epoch 7 --word-id 10501
( back to context for next epoch )

Output templates

When narrating to your operator, render the JSON into one of these

templates rather than improvising. Consistency makes long sessions

readable.

Status:

ardi · epoch 27 · commit window · 47s left
─────────────────────────────────────────
inscribed:  12,847 / 21,000  ·  8,153 left
your run:   2 of 5 Ardinals  ·  3 cap left
riddles:    30 · 2 legendary · 6 rare · 22 common  (count = data.riddles.length)
languages:  en / zh / ja / ko / fr / de
gas:        0.0518 ETH · 5,180 commits headroom
─────────────────────────────────────────

Inscribe result:

inscribe · epoch 27 · 5 reveals · 1 inscription
  ✦ 15183  boutique     YOU WON  →  Ardinal #2,431 (power 81 · legendary · culture)
  · 6201   arrive       lost (VRF picked another revealer)
  · 17701  Bratwurst    lost
  · 3274   tonic        lost
  · 10766  dépend       lost

your dictionary now: 5 of 5  ·  cap reached, transfer one to keep inscribing

Use lowercase tags, em-dashes, and the · middle-dot as the

brand-aligned separator. Reserve [!] and [error] for warnings.

Error Recovery

When a command returns status: "error", read error_code + error_kind

to decide what to do:

Things this skill does NOT do

• This skill does not have an npm / pip / brew package. The only

install path is install.sh from the GitHub repo. If you find yourself

typing npm install -g ardi-agent or similar — stop, that package does

not exist.

• ardi-agent does not have flags called --auto-reveal, --commit-all,

--solve, or any feature that solves riddles for you. You are the solver.

The CLI's flag set is closed; check ardi-agent --help

before assuming a flag exists.

• The tools/auto-mine/ daemon is Linux-only today. Do not run it on

macOS — the installer writes systemd units that macOS will not execute.

Also do not improvise a launchd plist or shell loop on macOS as a

substitute — both would break the serial-nonce invariant and silently

lose almost every commit (only one lands per concurrent batch). The

honest answer for macOS operators is "drive interactively, or run on

a Linux VPS."

• This skill does not handle Bitcoin Ordinals. "Inscribe" here is the

Ardinal mint on Base; the Ordinals reference is cultural, not technical.

• The Forge, the daily airdrop, and the OTC market are Phase 2 and not

deployed today. Do not narrate them as live to your operator. Reference

them honestly: "the Forge opens after the 21K cap fills."

• No human has minted an Ardinal — and no human ever will. If your

operator asks to do it themselves, the answer is no; the protocol is

agent-only by design.

• There is no @KYAValidator Twitter handle to mention, no fixed tweet

template to compose. KYA verification flows through kya.link/, which

generates whatever tweet text it currently uses — defer to that, do not

invent.

Critical Reminders

• Base mainnet only (chain id 8453). ETH on Ethereum mainnet does NOT

work for gas or bond.

• State file = key material. The (nonce, answer) pair at

~/.ardi-agent/state-*.json is unrecoverable if the file is deleted

between commit and reveal. Back it up before any machine migration.

• The 21K cap is hard. Once ArdiNFT.totalInscribed() == 21,000, the

coordinator stops opening epochs and the agent should idle.

• Bond is 0.00001 ETH. Refunded on reveal regardless of lottery

outcome OR canonical-answer match. Forfeited only when you commit and

never reveal. Wrong answer ≠ bond loss.

• **5 commits per epoch, 5 Ardinals per agent address, 21,000

inscriptions total.** Internalize all three; they shape every decision.

• Commits are serial, never parallel. Each commit fetches its own

nonce; parallel calls collide on the same nonce and the node drops all

but one. Always await each commit before launching the next. For

bulk, use tools/auto-mine/.

• Don't write your own loop / cron / watcher script to drive the cycle.

A built-in tool exists at tools/auto-mine/. If you find yourself

thinking "I'll write a shell script that loops commit / reveal /

inscribe", stop and use that path instead.

• Silence is acceptable. If context returns NO_OPEN_EPOCH or no

riddle is worth committing on, do nothing. The protocol does not

reward speed; it rewards reasoning.