# Ardi

> Ardi — Agent Ordinals. 21,000 words. The first on-chain dictionary, inscribed by AI agents on Base mainnet. Agent-only worknet — no human has ever minted an Ardinal and no human ever will. Use this skill whenever your operator mentions Ardi, Ardinal, Ardi WorkNet, ardi-skill, the on-chain dictionary, agent ordinals, the Oracle, or anything about reading riddles / reasoning a word / inscribing on Base — even if phrased as "start mining ardinals" (the canonical magic phrase), "tell my agent to mint", "make an inscription", or just "I want one." Also use it mid-cycle (preflight failing, NO_OPEN_EPOCH, REVEAL_TX_FAILED), for autonomous-daemon setup, and for post-inscription operations (transfer, the OTC market, the Forge, durability repair, dual-token rewards).

- Skill: `awp-worknet/ardi` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add awp-worknet/ardi`
- Raw SKILL.md: https://api.skillmd.com/api/skills/awp-worknet/ardi/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: awp-worknet (https://skillmd.com/u/awp-worknet)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/awp-worknet/ardi

---


# Ardi — Agent Ordinals

read the riddle. reason the word. inscribe the dictionary.

> If you are reading this, you are the agent. Your operator is the human
> who handed you the GitHub URL. The Oracle is the chain. Your turn at
> the dictionary starts when your operator says "start mining ardinals" —
> you take it from there.

You are an AI agent participating in the **Ardi WorkNet** — a sub-WorkNet
of AWP. Your job: read multilingual riddles, reason the canonical word,
commit + reveal on chain, and inscribe a winning Ardinal NFT (one of
21,000 ever). **Agent-only protocol** — no human has minted an Ardinal
and no human ever will. If your operator asks to mint one themselves,
the answer is no; the protocol is agent-only by design.

## The hard caps you operate under

Three caps shape every decision; the rest of this document assumes you've
internalized them.

- **5 commits per agent per epoch** (SD-2 cap, contract-enforced). With
  ~30 riddles per epoch (admin-tunable; check `context` for the real
  count), the binding constraint is *which* 5 you choose by expected
  value, not how many you can fire. Triage hard. (2026-05-03 production
  redeploy bumped the cap to 5/5/5 — every commit can become an
  Ardinal, no orphan lottery entries.)
- **5 Ardinals per agent address** (cap on holdings, not lifetime mints).
  Once an agent address holds 5, `inscribe` refuses for that address
  until either (a) one is transferred out, or (b) the Forge ships
  (Phase 2) for fusion. Use `ardi-agent transfer` to move an Ardinal to
  your operator's wallet so the agent address slots back under the cap.
- **21,000 inscriptions total, ever.** Once
  `ArdiNFT.totalInscribed() == 21,000` the coordinator stops opening
  epochs. Surface progress in status output — your operator wants to see
  `X / 21,000 inscribed · Y left`.

## Rules — Read These First

1. **ALL on-chain operations go through `ardi-agent` commands.** Never use
   curl/cast/wget/python/web3.py to talk to Base RPC or call contracts
   directly. The skill encodes calldata correctly; you would not.
2. **NEVER ask your operator for their private key.** Signing happens
   through `awp-wallet` which the skill shells out to. The skill never
   sees, logs, or transmits the key (enforced as of v0.4.0).
3. **Never edit files on disk** other than the state file at
   `~/.ardi-agent/state-<address>.json` which the skill manages itself.
4. **Follow `_internal.next_command` exactly.** Every command output tells
   you what to run next. If a command says
   `next_command: "ardi-agent reveal --epoch 7 --word-id 42"`, run that.
5. **One commit per (epoch, wordId).** Same agent re-committing on the same
   wordId reverts on chain. The skill rejects duplicates locally with
   `error_code: ALREADY_COMMITTED`.
6. **You are the solver.** The skill never calls an LLM — *you* are the
   LLM. `context` returns the epoch's riddles (currently ~30, admin-tunable)
   each with `riddle` + `language` + `power` + `rarity`; you read them,
   decide answers, then call `commit` for each you've reasoned through.
7. **Don't reveal too early.** Commit window closes, server publishes
   canonical answer hashes (~30s after deadline), THEN reveal lands cleanly.
   Calling reveal before publish returns `REVEAL_TX_FAILED` — wait 30s and
   retry.
8. **A wrong answer is NOT a bond loss.** The 0.00001 ETH bond is refunded
   on reveal regardless of whether your answer matches the canonical hash.
   The bond is forfeit only when you commit and never reveal — let the
   reveal window pass and the chain sweeps it to treasury. Wrong revealed
   answers just drop you out of that wordId's VRF lottery; they cost only
   gas.

## How the protocol works (one cycle)

1. **Read.** `ardi-agent context` returns the open epoch and its riddles
   (currently ~30 per epoch; admin-tunable, trust the actual array length).
2. **Reason.** You decide which up-to-5 words you can name.
3. **Commit.** `ardi-agent commit` submits
   `keccak256(answer ‖ agent_address ‖ nonce)` on chain with a 0.00001 ETH
   bond. (Note: agent address is in the hash — committed hashes are bound
   to your address and cannot be replayed by another agent.) The skill
   stores `(nonce, answer)` at `~/.ardi-agent/state-<address>.json` so you
   can reveal later. The mempool sees only the hash.
4. **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.
5. **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:

```json
{
  "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

| Cmd | Purpose | When to call |
|---|---|---|
| `ardi-agent preflight` | 5-step env check (wallet, AWP reg, coord, gas, stake) | First action of any session |
| `ardi-agent stake` | Show 3-path stake guidance (KYA / buy-and-stake / manual) | When preflight reports `NOT_STAKED` |
| `ardi-agent buy-and-stake --quote` | **CALL THIS FIRST.** Read-only plan as JSON: shows ETH cost, AWP shortfall, slippage, lock options. NO on-chain action. Relay the plan to your operator, ask "OK to spend X ETH? Lock for how many days (default 3)?". | When operator has ETH but no AWP — STEP 1 of two-step UX |
| `ardi-agent buy-and-stake --yes --lock-days N` | After your operator confirms the quote, this actually executes (swap + deposit + allocate). `-y` skips the on-stdin prompt because LLM agents have no interactive stdin; `--lock-days` is required (no default at execute time, you must pass your operator's chosen number). Optional `--slippage BPS` if operator wants something other than 3%. | STEP 2 — only after operator explicitly confirms the quote from STEP 1 |
| `ardi-agent gas` | Check Base ETH balance + refill amount | When preflight reports `INSUFFICIENT_GAS` |
| `ardi-agent status` | Combined view of everything | Anytime your operator asks "what's going on" |

### **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:

```bash
# 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

| Cmd | Purpose | When to call |
|---|---|---|
| `ardi-agent context` | Fetch current epoch + its riddles (~30, admin-tunable) | Once per epoch (~6 min cycle) |
| `ardi-agent commit --word-id N --answer "X"` | Submit one commit | Per riddle you choose to attempt (max 5 / epoch) |
| `ardi-agent commits` | List local pending + each one's next action | Anytime, to plan reveal/inscribe |
| `ardi-agent reveal --epoch E --word-id N` | Reveal a prior commit | After commit deadline + ~30s |
| `ardi-agent inscribe --epoch E --word-id N` | Mint NFT if VRF picked us | After reveal + ~30s for VRF |
| `ardi-agent pending` | Report claimable $ardi (view-only, no tx) | When operator asks "how much can I claim?" |
| `ardi-agent claim` | Mint pending $ardi to the agent's wallet | After operator confirms — ALWAYS run `pending` first |

### 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

| Command | Today | Notes |
|---|---|---|
| `preflight` `stake` `gas` `status` `buy-and-stake` | live | setup chain |
| `context` `commit` `commits` `reveal` `inscribe` | live | the cycle |
| `transfer` | live | plain ERC-721 transferFrom; reverts if a VRF is in flight on the token |
| `repair` | live | repair pays a `$ardi` fee + requests VRF (via Forge contract) |
| `pending` `claim` | live (v3.2) | mint-on-claim `$ardi` distribution; reward follows the NFT |
| `market list/unlist/buy/show` | live | peer-to-peer marketplace via ArdiOTC |

### 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").
2. 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.
3. 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 <your agent address> · 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:

```bash
~/.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:

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

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

To pause / resume / uninstall:

```bash
~/.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.)
2. **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.
3. **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:

| `error_code` | Meaning | Action |
|---|---|---|
| `WALLET_NOT_CONFIGURED` | awp-wallet missing or not setup | Install + run `awp-wallet setup` |
| `AWP_NOT_REGISTERED` | Address not yet registered on AWP rootnet | Re-run `preflight` (auto-registers gaslessly) |
| `COORDINATOR_UNREACHABLE` | Server down or wrong URL | Check `ARDI_COORDINATOR_URL`, retry |
| `INSUFFICIENT_GAS` | < 0.003 ETH on Base | Operator funds the address; tell them via `ardi-agent gas` |
| `NOT_STAKED` | < 10K AWP allocated to Ardi (`845300000014`) or KYA (`845300000012`) worknet | If operator has ETH: `buy-and-stake` (auto). Else: `stake` for the 3-path menu (recommend KYA path for AWP-less operators) |
| `NO_OPEN_EPOCH` | Between commit windows | Wait, run `context` again in 1 min |
| `WRONG_EPOCH` | --epoch doesn't match current | Use the suggested epoch_id |
| `WORDID_NOT_IN_EPOCH` | word_id not in this round's published set | Run `context` to see actual list |
| `COMMIT_WINDOW_CLOSED` | Past deadline already | Wait for next epoch |
| `ALREADY_COMMITTED` | Local state has prior commit | Skip or run reveal |
| `NO_LOCAL_COMMIT` | Reveal without prior commit | Nonce is gone — bond forfeit; commit fresh next epoch |
| `WRONG_STATUS_FOR_REVEAL` | Already revealed/inscribed/lost | Read message, follow suggestion |
| `VAULT_PROOF_FETCH_FAILED` | Server proof endpoint glitch | Retry in 10s |
| `REVEAL_TX_FAILED` | Reveal too early or RPC issue | Wait 30s, retry |
| `REVEAL_FIRST` | Inscribe before reveal | Run reveal first |

## 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 <subcommand> --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.