@demath-ai/cli 0.1.0 → 0.1.2

package/README.md

@@ -1,5 +1,28 @@
+<a href="https://demath.org"><img src="https://raw.githubusercontent.com/demath-ai/DeMath/main/assets/banner.png" alt="DeMath — Decentralized Math Research Infrastructure" /></a>
+
+<p align="center">
+  <a href="https://github.com/demath-ai/DeMath/actions/workflows/test.yml"><img alt="tests" src="https://img.shields.io/github/actions/workflow/status/demath-ai/DeMath/test.yml?branch=main&style=flat-square&color=0057B8&label=tests" /></a>
+  <a href="https://www.npmjs.com/package/@demath-ai/cli"><img alt="npm version" src="https://img.shields.io/npm/v/@demath-ai/cli?style=flat-square&color=0057B8&label=npm" /></a>
+  <img alt="MIT licensed" src="https://img.shields.io/npm/l/@demath-ai/cli?style=flat-square&color=0057B8" />
+  <img alt="node 18 plus" src="https://img.shields.io/badge/node-18%2B-0057B8?style=flat-square" />
+  <a href="https://demath.org"><img alt="demath.org" src="https://img.shields.io/badge/web-demath.org-0057B8?style=flat-square" /></a>
+</p>
+
 # @demath-ai/cli
 
+Official command-line client for the [DeMath](https://demath.org)
+protocol. Mine $DEMATH from any terminal with Node 18+ and an API key
+from one of the four supported providers (OpenRouter, Anthropic,
+OpenAI, Google Gemini).
+
+```sh
+npm install -g @demath-ai/cli
+demath skill        # drop into an AI agent for project context
+demath problems     # list the curated open problems
+```
+
+## What is DeMath
+
 DeMath is the first decentralized math research infrastructure on
 Base. The biggest mission in math history is wide open — Erdős
 conjectures, Collatz, twin primes, Hadwiger-Nelson, Beal, and a
@@ -22,28 +45,15 @@ attempt — full chain of thought — is pinned to IPFS as a permanent
 public dataset. A treasury funded by LP fees pays a solver bounty on
 the first independently verified proof of any listed problem.
 
-Key parameters:
-
-- **Emission**: 16M $DEMATH per 24h epoch at launch, halving every 25
-  days. Hard 800M mining cap (~4.4 years until full distribution).
-  The first 25 days release half the entire mining bucket — early
-  miners earn at rates the protocol will never see again.
-- **Settlement**: one epoch per UTC day, settled on-chain at ~00:10
-  UTC via a Merkle root posted by the protocol oracle.
-- **Pro-rata split**: your daily $DEMATH = (your epoch USD spend ÷
-  total epoch USD spend) × that epoch's emission.
-- **Wallet lock-for-life**: your first attempt binds the wallet to one
-  team (Claude / GPT / Gemini). Use different wallets for different
-  teams.
-- **Solver bounty**: a treasury funded by LP fees pays out to the
-  miner who lands the first verified proof / disproof of a listed
-  problem.
-
-This package is the official command-line client. Mine from any
-terminal with Node 18+ and an API key from one of the four supported
-providers.
-
-→ Protocol docs and web miner: https://demath.org
+| Parameter | Value |
+|---|---|
+| **Emission** | 16M $DEMATH per 24h epoch at launch, halving every 25 days |
+| **Mining cap** | 800M $DEMATH (~4.4 years until full distribution) |
+| **Early-miner edge** | First 25 days release half the entire mining bucket |
+| **Settlement** | one epoch per UTC day, ~00:10 UTC, Merkle root on-chain |
+| **Pro-rata** | your daily $DEMATH = (your epoch USD ÷ total epoch USD) × emission |
+| **Wallet lock-for-life** | first attempt binds the wallet to one team (Claude / GPT / Gemini) |
+| **Solver bounty** | LP-fees treasury pays out on the first verified proof |
 
 ## For AI agents
 
@@ -55,15 +65,20 @@ mine $DEMATH:
    npm install -g @demath-ai/cli
    ```
 
-2. **Discover the problems** — pick one whose `expected_difficulty` and
-   per-problem budget fit your spend cap. The test problem
-   `irrationality-of-e` (the problem with `expected_difficulty: "test"`)
-   costs well under a dollar end-to-end and is the right first call:
+2. **Read the skill file** — short, agent-facing project intro:
+   ```sh
+   demath skill
+   ```
+
+3. **Discover problems** — list the curated set and pick one. The
+   test problem `irrationality-of-e` (the entry with
+   `expected_difficulty: "test"`) is the cheapest to mine and the
+   recommended first call:
    ```sh
    demath problems --json
    ```
 
-3. **Verify the user's API key works** before committing any real spend:
+4. **Verify the user's API key works** before committing real spend:
    ```sh
    demath probe --model anthropic/claude-opus-4-7 --key "$ANTHROPIC_KEY" --json
    ```
@@ -72,66 +87,54 @@ mine $DEMATH:
    is under $0.0001). Non-zero means stop and surface the `detail`
    field to the human.
 
-4. **Run the attempt** with a hard USD cap. Stream NDJSON so you can
-   react per-iteration:
+5. **Run the attempt**. Stream NDJSON so you can react
+   per-iteration:
    ```sh
    demath mine \
      --problem  irrationality-of-e \
      --model    anthropic/claude-opus-4-7 \
      --key      "$ANTHROPIC_KEY" \
      --wallet   0xYourEvmAddress \
-     --max-usd  1.0 \
      --json
    ```
-   stdout emits one JSON object per line. The final `{"event":"final",...}`
-   line carries the terminal `status` (`proof_complete`, `counterexample`,
-   `breakthrough`, `stopped`, or `error`) and the IPFS CID of the full
-   chain-of-thought bundle.
+   stdout emits one JSON object per line. The final
+   `{"event":"final",...}` line carries the terminal `status`
+   (`proof_complete`, `counterexample`, `breakthrough`, `stopped`, or
+   `error`) and the IPFS CID of the full chain-of-thought bundle.
 
-5. **Exit codes** are the contract. `0` = the attempt reached a graded
+6. **Exit codes** are the contract. `0` = the attempt reached a graded
    success status. `1` = ended without success. `2` = invalid input or
    backend error. `3` = network error. `130` = SIGINT (the CLI sent a
    stop request to the backend on the way out).
 
-6. **Lock-for-life**: the wallet address you pass to `mine` is bound to
-   the chosen team (`anthropic` / `openai` / `google`) on its first
-   successful attempt. The backend returns HTTP 409 if you later submit
-   the same wallet with a different team. Surface this clearly to the
-   human; use a fresh EVM address per team if needed.
+7. **Lock-for-life**: the wallet address you pass to `mine` is bound
+   to the chosen team (`anthropic` / `openai` / `google`) on its first
+   successful attempt. The backend returns HTTP 409 if you later
+   submit the same wallet with a different team. Surface this clearly
+   to the human; use a fresh EVM address per team if needed.
 
-7. **Key handling**: the CLI holds the API key in process memory only.
+8. **Key handling**: the CLI holds the API key in process memory only.
    Never logs it, never writes it to disk, never sends it anywhere
-   except the configured `--api-url` (default `https://api.demath.org`).
+   except the configured `--api-url` (default
+   `https://api.demath.org`).
 
 For the short skill doc (project intro + mine-in-three-steps), run
 `demath skill`. For more invocations, run `demath examples`.
 
-## Install
-
-```sh
-npm install -g @demath-ai/cli
-# or, project-local
-npm install --save-dev @demath-ai/cli
-```
-
-Requirements: Node 18 or newer. No native deps, no Python, no build
-step on install — ships pre-bundled ESM + CJS.
-
 ## Usage
 
 ```
 demath <command> [options]
 ```
 
-Commands:
-
 | Command | What it does |
 |---|---|
-| `demath problems` | List active problems with id, name, difficulty, classification. |
-| `demath probe` | Verify an API key works against a model (no real spend). |
-| `demath mine` | Start an attempt and stream live progress until terminal. |
-| `demath status` | Fetch the current state of an attempt by id. |
-| `demath examples` | Print copy-pasteable example invocations. |
+| `demath problems` | List active problems with id, name, difficulty, classification |
+| `demath probe` | Verify an API key works against a model (no real spend) |
+| `demath mine` | Start an attempt and stream live progress until terminal |
+| `demath status` | Fetch the current state of an attempt by id |
+| `demath examples` | Print copy-pasteable example invocations |
+| `demath skill` | Print the SKILL.md doc to stdout (for AI agents) |
 
 Every command supports `--help`, `--api-url <url>`, and `--json`.
 
@@ -156,8 +159,7 @@ demath mine \
   --problem irrationality-of-e \
   --model   anthropic/claude-opus-4-7 \
   --key     sk-ant-... \
-  --wallet  0xYourEvmAddress \
-  --max-usd 1.0
+  --wallet  0xYourEvmAddress
 ```
 
 With `--json`, stdout receives one NDJSON event per iteration:
@@ -190,15 +192,16 @@ provider. The backend auto-detects from the key prefix.
 
 ## Lock-for-life
 
-The first attempt from a wallet binds that wallet to a single team. The
-backend rejects later attempts from the same wallet with a different
-team using HTTP 409. Different wallets for different teams works.
+The first attempt from a wallet binds that wallet to a single team.
+The backend rejects later attempts from the same wallet with a
+different team using HTTP 409. Different wallets for different teams
+works.
 
 ## Environment
 
 | Variable | Default | Purpose |
 |---|---|---|
-| `DEMATH_API_URL` | `https://api.demath.org` | Override the backend base URL (testing, self-host). |
+| `DEMATH_API_URL` | `https://api.demath.org` | Override the backend base URL (testing, self-host) |
 
 ## Programmatic use
 
@@ -209,6 +212,26 @@ const client = new DemathClient({ apiUrl: "https://api.demath.org" });
 const { problems } = await client.listProblems();
 ```
 
+## Build from source
+
+```sh
+git clone https://github.com/demath-ai/DeMath
+cd DeMath
+npm install
+npm run build       # prebuild embeds SKILL.md, then tsup bundles
+npm test            # 12 tests pass; no provider keys required
+node bin/demath.mjs --help
+```
+
+Zero runtime dependencies. ESM + CJS dual-bundle, ~33 kB each.
+
+## Links
+
+- **Web miner**: [demath.org](https://demath.org)
+- **API**: `https://api.demath.org` ([OpenAPI docs](https://api.demath.org/docs))
+- **npm**: [`@demath-ai/cli`](https://www.npmjs.com/package/@demath-ai/cli)
+- **Issues**: [github.com/demath-ai/DeMath/issues](https://github.com/demath-ai/DeMath/issues)
+
 ## License
 
 MIT.

package/SKILL.md

@@ -26,7 +26,7 @@ You are an AI agent reading this skill. To mine on a human's behalf:
     demath problems --json
     demath probe --model <slug> --key $KEY --json   # exit 0 = ready
     demath mine  --problem <id> --model <slug> --key $KEY \
-                 --wallet 0x... --max-usd 1.0 --json
+                 --wallet 0x... --json
 
 The terminal `event:final` line on the mine stream carries the
 attempt's `status` (`proof_complete`, `counterexample`, `breakthrough`,

package/dist/cli.cjs

@@ -204,8 +204,11 @@ REQUIRED
                     (locks to the chosen team on first use)
 
 OPTIONAL
-  --max-iterations  cap on agent loop iterations (default: backend default)
-  --max-usd         cost cap in USD (default: backend default)
+  --max-iterations  upper bound on agent loop iterations (default: backend default)
+  --max-usd         upper bound on USD spend. Leave unset (default: backend
+                    default) unless you specifically need to limit the run.
+                    Reasoning models can ramp spend mid-attempt on legitimate
+                    progress; a tight cap will stop them before they finish.
   --json            emit one NDJSON event per iteration on stdout
 
 EXAMPLES
@@ -213,8 +216,7 @@ EXAMPLES
     --problem irrationality-of-e \\
     --model   anthropic/claude-opus-4-7 \\
     --key     sk-ant-... \\
-    --wallet  0xYourEvmAddress \\
-    --max-usd 1.0
+    --wallet  0xYourEvmAddress
 
   demath mine --problem collatz --model openai/gpt-5.5 \\
     --key sk-or-v1-... --wallet 0xAbc... --json | tee run.ndjson
@@ -263,14 +265,13 @@ var EXAMPLES = `DeMath CLI \u2014 worked examples
          --key   sk-ant-... \\
          --json
 
-  3) Start a budget-capped attempt on the test problem (a few cents):
+  3) Start an attempt on the test problem (a few cents end-to-end):
 
        demath mine \\
          --problem irrationality-of-e \\
          --model   anthropic/claude-opus-4-7 \\
          --key     sk-ant-... \\
-         --wallet  0xYourEvmAddress \\
-         --max-usd 1.0
+         --wallet  0xYourEvmAddress
 
   4) Same flow but routing via OpenRouter (one key, any team):
 
@@ -279,8 +280,6 @@ var EXAMPLES = `DeMath CLI \u2014 worked examples
          --model   openai/gpt-5.5 \\
          --key     sk-or-v1-... \\
          --wallet  0xYourEvmAddress \\
-         --max-iterations 8 \\
-         --max-usd 5.0 \\
          --json
 
   5) Inspect an attempt by id after the fact (e.g. for a background run):
@@ -644,7 +643,7 @@ async function runProbe(args) {
 }
 
 // src/skillContent.generated.ts
-var SKILL_MD_CONTENT = "# DeMath skill\n\nDeMath is the first decentralized math research infrastructure on\nBase. The biggest mission in math history is wide open \u2014 Erd\u0151s\nconjectures, Collatz, twin primes, Hadwiger-Nelson, Beal, and a\ncurated list of problems mathematicians have worked on for decades.\nDeMath is the coordination layer for putting frontier AI compute on\nall of them, in public.\n\nMiners spend API budget on Anthropic / OpenAI / Google / OpenRouter\nand earn $DEMATH pro-rata to their compute spend per 24h epoch. Every\nattempt is pinned to IPFS with full chain-of-thought as a permanent\npublic dataset.\n\nYou are an AI agent reading this skill. To mine on a human's behalf:\n\n1. Install once: `npm install -g @demath-ai/cli`\n2. Run `demath --help` \u2014 the authoritative reference for flags and\n   exit codes. Re-read it before every invocation; nothing in this\n   skill replaces it.\n3. The four commands: `problems`, `probe`, `mine`, `status`. Each has\n   its own `--help`. Use `--json` for machine output.\n\n## Mine in three steps\n\n    demath problems --json\n    demath probe --model <slug> --key $KEY --json   # exit 0 = ready\n    demath mine  --problem <id> --model <slug> --key $KEY \\\n                 --wallet 0x... --max-usd 1.0 --json\n\nThe terminal `event:final` line on the mine stream carries the\nattempt's `status` (`proof_complete`, `counterexample`, `breakthrough`,\n`stopped`, or `error`) and the IPFS CID of the full chain-of-thought\nbundle.\n\n## Wallet lock-for-life\n\nThe wallet you submit to `mine` binds to a single team (Claude / GPT /\nGemini) on its first successful attempt. The backend rejects later\nattempts from that same wallet against a different team with HTTP 409.\nUse a fresh EVM address per team.\n\n## What DeMath does NOT do with the human's API key\n\nThe CLI sends the key once per attempt to the backend, which forwards\nit inline to the upstream provider and drops it from memory the moment\nthe attempt finishes. No disk write, no log line, no IPFS bundle, no\ntelemetry, no SQLite, no env files. The human's billing relationship\nwith the upstream provider stays theirs.\n\n## Claim\n\nClaiming the earned emission is a web step at https://demath.org/claim.\nThe CLI does not sign on-chain transactions in v0.1.\n";
+var SKILL_MD_CONTENT = "# DeMath skill\n\nDeMath is the first decentralized math research infrastructure on\nBase. The biggest mission in math history is wide open \u2014 Erd\u0151s\nconjectures, Collatz, twin primes, Hadwiger-Nelson, Beal, and a\ncurated list of problems mathematicians have worked on for decades.\nDeMath is the coordination layer for putting frontier AI compute on\nall of them, in public.\n\nMiners spend API budget on Anthropic / OpenAI / Google / OpenRouter\nand earn $DEMATH pro-rata to their compute spend per 24h epoch. Every\nattempt is pinned to IPFS with full chain-of-thought as a permanent\npublic dataset.\n\nYou are an AI agent reading this skill. To mine on a human's behalf:\n\n1. Install once: `npm install -g @demath-ai/cli`\n2. Run `demath --help` \u2014 the authoritative reference for flags and\n   exit codes. Re-read it before every invocation; nothing in this\n   skill replaces it.\n3. The four commands: `problems`, `probe`, `mine`, `status`. Each has\n   its own `--help`. Use `--json` for machine output.\n\n## Mine in three steps\n\n    demath problems --json\n    demath probe --model <slug> --key $KEY --json   # exit 0 = ready\n    demath mine  --problem <id> --model <slug> --key $KEY \\\n                 --wallet 0x... --json\n\nThe terminal `event:final` line on the mine stream carries the\nattempt's `status` (`proof_complete`, `counterexample`, `breakthrough`,\n`stopped`, or `error`) and the IPFS CID of the full chain-of-thought\nbundle.\n\n## Wallet lock-for-life\n\nThe wallet you submit to `mine` binds to a single team (Claude / GPT /\nGemini) on its first successful attempt. The backend rejects later\nattempts from that same wallet against a different team with HTTP 409.\nUse a fresh EVM address per team.\n\n## What DeMath does NOT do with the human's API key\n\nThe CLI sends the key once per attempt to the backend, which forwards\nit inline to the upstream provider and drops it from memory the moment\nthe attempt finishes. No disk write, no log line, no IPFS bundle, no\ntelemetry, no SQLite, no env files. The human's billing relationship\nwith the upstream provider stays theirs.\n\n## Claim\n\nClaiming the earned emission is a web step at https://demath.org/claim.\nThe CLI does not sign on-chain transactions in v0.1.\n";
 
 // src/commands/skill.ts
 function runSkill() {

package/dist/cli.js

@@ -202,8 +202,11 @@ REQUIRED
                     (locks to the chosen team on first use)
 
 OPTIONAL
-  --max-iterations  cap on agent loop iterations (default: backend default)
-  --max-usd         cost cap in USD (default: backend default)
+  --max-iterations  upper bound on agent loop iterations (default: backend default)
+  --max-usd         upper bound on USD spend. Leave unset (default: backend
+                    default) unless you specifically need to limit the run.
+                    Reasoning models can ramp spend mid-attempt on legitimate
+                    progress; a tight cap will stop them before they finish.
   --json            emit one NDJSON event per iteration on stdout
 
 EXAMPLES
@@ -211,8 +214,7 @@ EXAMPLES
     --problem irrationality-of-e \\
     --model   anthropic/claude-opus-4-7 \\
     --key     sk-ant-... \\
-    --wallet  0xYourEvmAddress \\
-    --max-usd 1.0
+    --wallet  0xYourEvmAddress
 
   demath mine --problem collatz --model openai/gpt-5.5 \\
     --key sk-or-v1-... --wallet 0xAbc... --json | tee run.ndjson
@@ -261,14 +263,13 @@ var EXAMPLES = `DeMath CLI \u2014 worked examples
          --key   sk-ant-... \\
          --json
 
-  3) Start a budget-capped attempt on the test problem (a few cents):
+  3) Start an attempt on the test problem (a few cents end-to-end):
 
        demath mine \\
          --problem irrationality-of-e \\
          --model   anthropic/claude-opus-4-7 \\
          --key     sk-ant-... \\
-         --wallet  0xYourEvmAddress \\
-         --max-usd 1.0
+         --wallet  0xYourEvmAddress
 
   4) Same flow but routing via OpenRouter (one key, any team):
 
@@ -277,8 +278,6 @@ var EXAMPLES = `DeMath CLI \u2014 worked examples
          --model   openai/gpt-5.5 \\
          --key     sk-or-v1-... \\
          --wallet  0xYourEvmAddress \\
-         --max-iterations 8 \\
-         --max-usd 5.0 \\
          --json
 
   5) Inspect an attempt by id after the fact (e.g. for a background run):
@@ -642,7 +641,7 @@ async function runProbe(args) {
 }
 
 // src/skillContent.generated.ts
-var SKILL_MD_CONTENT = "# DeMath skill\n\nDeMath is the first decentralized math research infrastructure on\nBase. The biggest mission in math history is wide open \u2014 Erd\u0151s\nconjectures, Collatz, twin primes, Hadwiger-Nelson, Beal, and a\ncurated list of problems mathematicians have worked on for decades.\nDeMath is the coordination layer for putting frontier AI compute on\nall of them, in public.\n\nMiners spend API budget on Anthropic / OpenAI / Google / OpenRouter\nand earn $DEMATH pro-rata to their compute spend per 24h epoch. Every\nattempt is pinned to IPFS with full chain-of-thought as a permanent\npublic dataset.\n\nYou are an AI agent reading this skill. To mine on a human's behalf:\n\n1. Install once: `npm install -g @demath-ai/cli`\n2. Run `demath --help` \u2014 the authoritative reference for flags and\n   exit codes. Re-read it before every invocation; nothing in this\n   skill replaces it.\n3. The four commands: `problems`, `probe`, `mine`, `status`. Each has\n   its own `--help`. Use `--json` for machine output.\n\n## Mine in three steps\n\n    demath problems --json\n    demath probe --model <slug> --key $KEY --json   # exit 0 = ready\n    demath mine  --problem <id> --model <slug> --key $KEY \\\n                 --wallet 0x... --max-usd 1.0 --json\n\nThe terminal `event:final` line on the mine stream carries the\nattempt's `status` (`proof_complete`, `counterexample`, `breakthrough`,\n`stopped`, or `error`) and the IPFS CID of the full chain-of-thought\nbundle.\n\n## Wallet lock-for-life\n\nThe wallet you submit to `mine` binds to a single team (Claude / GPT /\nGemini) on its first successful attempt. The backend rejects later\nattempts from that same wallet against a different team with HTTP 409.\nUse a fresh EVM address per team.\n\n## What DeMath does NOT do with the human's API key\n\nThe CLI sends the key once per attempt to the backend, which forwards\nit inline to the upstream provider and drops it from memory the moment\nthe attempt finishes. No disk write, no log line, no IPFS bundle, no\ntelemetry, no SQLite, no env files. The human's billing relationship\nwith the upstream provider stays theirs.\n\n## Claim\n\nClaiming the earned emission is a web step at https://demath.org/claim.\nThe CLI does not sign on-chain transactions in v0.1.\n";
+var SKILL_MD_CONTENT = "# DeMath skill\n\nDeMath is the first decentralized math research infrastructure on\nBase. The biggest mission in math history is wide open \u2014 Erd\u0151s\nconjectures, Collatz, twin primes, Hadwiger-Nelson, Beal, and a\ncurated list of problems mathematicians have worked on for decades.\nDeMath is the coordination layer for putting frontier AI compute on\nall of them, in public.\n\nMiners spend API budget on Anthropic / OpenAI / Google / OpenRouter\nand earn $DEMATH pro-rata to their compute spend per 24h epoch. Every\nattempt is pinned to IPFS with full chain-of-thought as a permanent\npublic dataset.\n\nYou are an AI agent reading this skill. To mine on a human's behalf:\n\n1. Install once: `npm install -g @demath-ai/cli`\n2. Run `demath --help` \u2014 the authoritative reference for flags and\n   exit codes. Re-read it before every invocation; nothing in this\n   skill replaces it.\n3. The four commands: `problems`, `probe`, `mine`, `status`. Each has\n   its own `--help`. Use `--json` for machine output.\n\n## Mine in three steps\n\n    demath problems --json\n    demath probe --model <slug> --key $KEY --json   # exit 0 = ready\n    demath mine  --problem <id> --model <slug> --key $KEY \\\n                 --wallet 0x... --json\n\nThe terminal `event:final` line on the mine stream carries the\nattempt's `status` (`proof_complete`, `counterexample`, `breakthrough`,\n`stopped`, or `error`) and the IPFS CID of the full chain-of-thought\nbundle.\n\n## Wallet lock-for-life\n\nThe wallet you submit to `mine` binds to a single team (Claude / GPT /\nGemini) on its first successful attempt. The backend rejects later\nattempts from that same wallet against a different team with HTTP 409.\nUse a fresh EVM address per team.\n\n## What DeMath does NOT do with the human's API key\n\nThe CLI sends the key once per attempt to the backend, which forwards\nit inline to the upstream provider and drops it from memory the moment\nthe attempt finishes. No disk write, no log line, no IPFS bundle, no\ntelemetry, no SQLite, no env files. The human's billing relationship\nwith the upstream provider stays theirs.\n\n## Claim\n\nClaiming the earned emission is a web step at https://demath.org/claim.\nThe CLI does not sign on-chain transactions in v0.1.\n";
 
 // src/commands/skill.ts
 function runSkill() {

package/dist/index.cjs

@@ -318,8 +318,11 @@ REQUIRED
                     (locks to the chosen team on first use)
 
 OPTIONAL
-  --max-iterations  cap on agent loop iterations (default: backend default)
-  --max-usd         cost cap in USD (default: backend default)
+  --max-iterations  upper bound on agent loop iterations (default: backend default)
+  --max-usd         upper bound on USD spend. Leave unset (default: backend
+                    default) unless you specifically need to limit the run.
+                    Reasoning models can ramp spend mid-attempt on legitimate
+                    progress; a tight cap will stop them before they finish.
   --json            emit one NDJSON event per iteration on stdout
 
 EXAMPLES
@@ -327,8 +330,7 @@ EXAMPLES
     --problem irrationality-of-e \\
     --model   anthropic/claude-opus-4-7 \\
     --key     sk-ant-... \\
-    --wallet  0xYourEvmAddress \\
-    --max-usd 1.0
+    --wallet  0xYourEvmAddress
 
   demath mine --problem collatz --model openai/gpt-5.5 \\
     --key sk-or-v1-... --wallet 0xAbc... --json | tee run.ndjson
@@ -377,14 +379,13 @@ var EXAMPLES = `DeMath CLI \u2014 worked examples
          --key   sk-ant-... \\
          --json
 
-  3) Start a budget-capped attempt on the test problem (a few cents):
+  3) Start an attempt on the test problem (a few cents end-to-end):
 
        demath mine \\
          --problem irrationality-of-e \\
          --model   anthropic/claude-opus-4-7 \\
          --key     sk-ant-... \\
-         --wallet  0xYourEvmAddress \\
-         --max-usd 1.0
+         --wallet  0xYourEvmAddress
 
   4) Same flow but routing via OpenRouter (one key, any team):
 
@@ -393,8 +394,6 @@ var EXAMPLES = `DeMath CLI \u2014 worked examples
          --model   openai/gpt-5.5 \\
          --key     sk-or-v1-... \\
          --wallet  0xYourEvmAddress \\
-         --max-iterations 8 \\
-         --max-usd 5.0 \\
          --json
 
   5) Inspect an attempt by id after the fact (e.g. for a background run):
@@ -644,7 +643,7 @@ async function runProbe(args) {
 }
 
 // src/skillContent.generated.ts
-var SKILL_MD_CONTENT = "# DeMath skill\n\nDeMath is the first decentralized math research infrastructure on\nBase. The biggest mission in math history is wide open \u2014 Erd\u0151s\nconjectures, Collatz, twin primes, Hadwiger-Nelson, Beal, and a\ncurated list of problems mathematicians have worked on for decades.\nDeMath is the coordination layer for putting frontier AI compute on\nall of them, in public.\n\nMiners spend API budget on Anthropic / OpenAI / Google / OpenRouter\nand earn $DEMATH pro-rata to their compute spend per 24h epoch. Every\nattempt is pinned to IPFS with full chain-of-thought as a permanent\npublic dataset.\n\nYou are an AI agent reading this skill. To mine on a human's behalf:\n\n1. Install once: `npm install -g @demath-ai/cli`\n2. Run `demath --help` \u2014 the authoritative reference for flags and\n   exit codes. Re-read it before every invocation; nothing in this\n   skill replaces it.\n3. The four commands: `problems`, `probe`, `mine`, `status`. Each has\n   its own `--help`. Use `--json` for machine output.\n\n## Mine in three steps\n\n    demath problems --json\n    demath probe --model <slug> --key $KEY --json   # exit 0 = ready\n    demath mine  --problem <id> --model <slug> --key $KEY \\\n                 --wallet 0x... --max-usd 1.0 --json\n\nThe terminal `event:final` line on the mine stream carries the\nattempt's `status` (`proof_complete`, `counterexample`, `breakthrough`,\n`stopped`, or `error`) and the IPFS CID of the full chain-of-thought\nbundle.\n\n## Wallet lock-for-life\n\nThe wallet you submit to `mine` binds to a single team (Claude / GPT /\nGemini) on its first successful attempt. The backend rejects later\nattempts from that same wallet against a different team with HTTP 409.\nUse a fresh EVM address per team.\n\n## What DeMath does NOT do with the human's API key\n\nThe CLI sends the key once per attempt to the backend, which forwards\nit inline to the upstream provider and drops it from memory the moment\nthe attempt finishes. No disk write, no log line, no IPFS bundle, no\ntelemetry, no SQLite, no env files. The human's billing relationship\nwith the upstream provider stays theirs.\n\n## Claim\n\nClaiming the earned emission is a web step at https://demath.org/claim.\nThe CLI does not sign on-chain transactions in v0.1.\n";
+var SKILL_MD_CONTENT = "# DeMath skill\n\nDeMath is the first decentralized math research infrastructure on\nBase. The biggest mission in math history is wide open \u2014 Erd\u0151s\nconjectures, Collatz, twin primes, Hadwiger-Nelson, Beal, and a\ncurated list of problems mathematicians have worked on for decades.\nDeMath is the coordination layer for putting frontier AI compute on\nall of them, in public.\n\nMiners spend API budget on Anthropic / OpenAI / Google / OpenRouter\nand earn $DEMATH pro-rata to their compute spend per 24h epoch. Every\nattempt is pinned to IPFS with full chain-of-thought as a permanent\npublic dataset.\n\nYou are an AI agent reading this skill. To mine on a human's behalf:\n\n1. Install once: `npm install -g @demath-ai/cli`\n2. Run `demath --help` \u2014 the authoritative reference for flags and\n   exit codes. Re-read it before every invocation; nothing in this\n   skill replaces it.\n3. The four commands: `problems`, `probe`, `mine`, `status`. Each has\n   its own `--help`. Use `--json` for machine output.\n\n## Mine in three steps\n\n    demath problems --json\n    demath probe --model <slug> --key $KEY --json   # exit 0 = ready\n    demath mine  --problem <id> --model <slug> --key $KEY \\\n                 --wallet 0x... --json\n\nThe terminal `event:final` line on the mine stream carries the\nattempt's `status` (`proof_complete`, `counterexample`, `breakthrough`,\n`stopped`, or `error`) and the IPFS CID of the full chain-of-thought\nbundle.\n\n## Wallet lock-for-life\n\nThe wallet you submit to `mine` binds to a single team (Claude / GPT /\nGemini) on its first successful attempt. The backend rejects later\nattempts from that same wallet against a different team with HTTP 409.\nUse a fresh EVM address per team.\n\n## What DeMath does NOT do with the human's API key\n\nThe CLI sends the key once per attempt to the backend, which forwards\nit inline to the upstream provider and drops it from memory the moment\nthe attempt finishes. No disk write, no log line, no IPFS bundle, no\ntelemetry, no SQLite, no env files. The human's billing relationship\nwith the upstream provider stays theirs.\n\n## Claim\n\nClaiming the earned emission is a web step at https://demath.org/claim.\nThe CLI does not sign on-chain transactions in v0.1.\n";
 
 // src/commands/skill.ts
 function runSkill() {

package/dist/index.js

@@ -316,8 +316,11 @@ REQUIRED
                     (locks to the chosen team on first use)
 
 OPTIONAL
-  --max-iterations  cap on agent loop iterations (default: backend default)
-  --max-usd         cost cap in USD (default: backend default)
+  --max-iterations  upper bound on agent loop iterations (default: backend default)
+  --max-usd         upper bound on USD spend. Leave unset (default: backend
+                    default) unless you specifically need to limit the run.
+                    Reasoning models can ramp spend mid-attempt on legitimate
+                    progress; a tight cap will stop them before they finish.
   --json            emit one NDJSON event per iteration on stdout
 
 EXAMPLES
@@ -325,8 +328,7 @@ EXAMPLES
     --problem irrationality-of-e \\
     --model   anthropic/claude-opus-4-7 \\
     --key     sk-ant-... \\
-    --wallet  0xYourEvmAddress \\
-    --max-usd 1.0
+    --wallet  0xYourEvmAddress
 
   demath mine --problem collatz --model openai/gpt-5.5 \\
     --key sk-or-v1-... --wallet 0xAbc... --json | tee run.ndjson
@@ -375,14 +377,13 @@ var EXAMPLES = `DeMath CLI \u2014 worked examples
          --key   sk-ant-... \\
          --json
 
-  3) Start a budget-capped attempt on the test problem (a few cents):
+  3) Start an attempt on the test problem (a few cents end-to-end):
 
        demath mine \\
          --problem irrationality-of-e \\
          --model   anthropic/claude-opus-4-7 \\
          --key     sk-ant-... \\
-         --wallet  0xYourEvmAddress \\
-         --max-usd 1.0
+         --wallet  0xYourEvmAddress
 
   4) Same flow but routing via OpenRouter (one key, any team):
 
@@ -391,8 +392,6 @@ var EXAMPLES = `DeMath CLI \u2014 worked examples
          --model   openai/gpt-5.5 \\
          --key     sk-or-v1-... \\
          --wallet  0xYourEvmAddress \\
-         --max-iterations 8 \\
-         --max-usd 5.0 \\
          --json
 
   5) Inspect an attempt by id after the fact (e.g. for a background run):
@@ -642,7 +641,7 @@ async function runProbe(args) {
 }
 
 // src/skillContent.generated.ts
-var SKILL_MD_CONTENT = "# DeMath skill\n\nDeMath is the first decentralized math research infrastructure on\nBase. The biggest mission in math history is wide open \u2014 Erd\u0151s\nconjectures, Collatz, twin primes, Hadwiger-Nelson, Beal, and a\ncurated list of problems mathematicians have worked on for decades.\nDeMath is the coordination layer for putting frontier AI compute on\nall of them, in public.\n\nMiners spend API budget on Anthropic / OpenAI / Google / OpenRouter\nand earn $DEMATH pro-rata to their compute spend per 24h epoch. Every\nattempt is pinned to IPFS with full chain-of-thought as a permanent\npublic dataset.\n\nYou are an AI agent reading this skill. To mine on a human's behalf:\n\n1. Install once: `npm install -g @demath-ai/cli`\n2. Run `demath --help` \u2014 the authoritative reference for flags and\n   exit codes. Re-read it before every invocation; nothing in this\n   skill replaces it.\n3. The four commands: `problems`, `probe`, `mine`, `status`. Each has\n   its own `--help`. Use `--json` for machine output.\n\n## Mine in three steps\n\n    demath problems --json\n    demath probe --model <slug> --key $KEY --json   # exit 0 = ready\n    demath mine  --problem <id> --model <slug> --key $KEY \\\n                 --wallet 0x... --max-usd 1.0 --json\n\nThe terminal `event:final` line on the mine stream carries the\nattempt's `status` (`proof_complete`, `counterexample`, `breakthrough`,\n`stopped`, or `error`) and the IPFS CID of the full chain-of-thought\nbundle.\n\n## Wallet lock-for-life\n\nThe wallet you submit to `mine` binds to a single team (Claude / GPT /\nGemini) on its first successful attempt. The backend rejects later\nattempts from that same wallet against a different team with HTTP 409.\nUse a fresh EVM address per team.\n\n## What DeMath does NOT do with the human's API key\n\nThe CLI sends the key once per attempt to the backend, which forwards\nit inline to the upstream provider and drops it from memory the moment\nthe attempt finishes. No disk write, no log line, no IPFS bundle, no\ntelemetry, no SQLite, no env files. The human's billing relationship\nwith the upstream provider stays theirs.\n\n## Claim\n\nClaiming the earned emission is a web step at https://demath.org/claim.\nThe CLI does not sign on-chain transactions in v0.1.\n";
+var SKILL_MD_CONTENT = "# DeMath skill\n\nDeMath is the first decentralized math research infrastructure on\nBase. The biggest mission in math history is wide open \u2014 Erd\u0151s\nconjectures, Collatz, twin primes, Hadwiger-Nelson, Beal, and a\ncurated list of problems mathematicians have worked on for decades.\nDeMath is the coordination layer for putting frontier AI compute on\nall of them, in public.\n\nMiners spend API budget on Anthropic / OpenAI / Google / OpenRouter\nand earn $DEMATH pro-rata to their compute spend per 24h epoch. Every\nattempt is pinned to IPFS with full chain-of-thought as a permanent\npublic dataset.\n\nYou are an AI agent reading this skill. To mine on a human's behalf:\n\n1. Install once: `npm install -g @demath-ai/cli`\n2. Run `demath --help` \u2014 the authoritative reference for flags and\n   exit codes. Re-read it before every invocation; nothing in this\n   skill replaces it.\n3. The four commands: `problems`, `probe`, `mine`, `status`. Each has\n   its own `--help`. Use `--json` for machine output.\n\n## Mine in three steps\n\n    demath problems --json\n    demath probe --model <slug> --key $KEY --json   # exit 0 = ready\n    demath mine  --problem <id> --model <slug> --key $KEY \\\n                 --wallet 0x... --json\n\nThe terminal `event:final` line on the mine stream carries the\nattempt's `status` (`proof_complete`, `counterexample`, `breakthrough`,\n`stopped`, or `error`) and the IPFS CID of the full chain-of-thought\nbundle.\n\n## Wallet lock-for-life\n\nThe wallet you submit to `mine` binds to a single team (Claude / GPT /\nGemini) on its first successful attempt. The backend rejects later\nattempts from that same wallet against a different team with HTTP 409.\nUse a fresh EVM address per team.\n\n## What DeMath does NOT do with the human's API key\n\nThe CLI sends the key once per attempt to the backend, which forwards\nit inline to the upstream provider and drops it from memory the moment\nthe attempt finishes. No disk write, no log line, no IPFS bundle, no\ntelemetry, no SQLite, no env files. The human's billing relationship\nwith the upstream provider stays theirs.\n\n## Claim\n\nClaiming the earned emission is a web step at https://demath.org/claim.\nThe CLI does not sign on-chain transactions in v0.1.\n";
 
 // src/commands/skill.ts
 function runSkill() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@demath-ai/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Pure JS/TS CLI for mining $DEMATH — AI-agent-friendly client for the DeMath public API.",
   "license": "MIT",
   "author": "demath-ai",