@aeon-ai-pay/aigateway 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-05-18
+
+Initial release of **AEON AI Gateway**, merging the prior `@aeon-ai-pay/aicard` and `@aeon-ai-pay/agentos` projects into a single unified CLI and agent skill.
+
+### Added
+
+- Unified CLI surface (`aigateway`) supporting both **virtual card** and **AI image** capabilities backed by a shared session-key wallet.
+- Commands:
+  - `wallet-init` — pure-local session-wallet check / auto-create (no QR, no on-chain).
+  - `wallet-topup` — WalletConnect USDT top-up (≥5 USDT, presets 5/10/20/50) + one-time facilitator approve.
+  - `wallet-balance` — query session-key USDT / BNB balance + saved main wallet.
+  - `wallet-gas` — main wallet → session BNB transfer (for withdraw gas).
+  - `wallet-withdraw` — on-chain reclaim of USDT + BNB back to main wallet.
+  - `create-card` — x402-paid virtual debit card issuance ($0.6 ~ $800), `--poll` and `--dry-run` supported.
+  - `create-image` — x402-paid Skill Boss image generation, with prompt / aspect-ratio / format / model controls.
+  - `create-card-status` — query the status of a `create-card` order.
+  - `clean` — uninstall skill and clear npm/npx caches.
+- Stable JSON envelope on stdout for every command: `{ ok, command, version, data | error }`.
+- Stable `error.code` taxonomy (24 codes) mapped to four exit-code categories: `1` user / `2` timeout / `3` service / `4` internal.
+- `--app-id <id>` on every command (default `TEST000001`) for merchant attribution.
+- `--legacy-output` flag for consumers still parsing the pre-envelope JSON shape.
+- `--verbose` / `--quiet` global logging controls.
+- `--dry-run` on `create-card` for preflight validation without signing or transacting.
+- Foreground auto-upgrade via `src/update-check.mjs`: every CLI invocation checks `npm view` and silently background-installs the new version + re-syncs the skill via `postinstall`.
+- Multi-IDE adoption templates under `templates/` for Cursor, Windsurf, Cline / Roo Code, and Codex.
+- Agent skill at `skills/aigateway/SKILL.md` with end-user workflow, copy-exact templates, and decision routing.
+- Developer documentation:
+  - `docs/output-schema.md` — full envelope schema per command.
+  - `docs/exit-codes.md` — exit code + `error.code` reference.
+  - `docs/env-vars.md` — environment variable reference.
+  - `docs/troubleshooting.md` — common issues & remedies.
+  - `docs/release-process.md` — release workflow + version lock-step rules.
+  - `docs/ide-setup.md` — manual IDE adoption guide.
+  - `docs/recipes/integrate-in-agent.md` — generic spawn-and-parse Node.js / Python wrappers.
+  - `docs/recipes/error-recovery.md` — recovery actions per error code.
+  - `docs/recipes/cron-issue-cards.md` — scheduled paid calls.
+  - `docs/recipes/merchant-integration.md` — merchant integration patterns (user-managed vs. custodial wallet).
+
+### Removed (compared to upstream `aicard` / `agentos`)
+
+- `setup --check` (folded into the new `wallet-init` command).
+- `setup --service-url` / per-command `--service-url` flag (use `AIGATEWAY_SERVICE_URL` env var instead).
+- `aicard topup` (renamed to `wallet-topup`).
+- `agentos prepare` (folded into `wallet-topup`).
+- `aicard create` (renamed to `create-card`).
+- `aicard wallet` / `aicard gas` / `aicard withdraw` (renamed to `wallet-balance` / `wallet-gas` / `wallet-withdraw`).
+- `aicard status` (renamed to `create-card-status` to match `create-card-*` naming).
+- `INVALID_USAGE` error code (no longer needed after `setup` simplification).
+
+[Unreleased]: https://github.com/AEON-Project/aigateway/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/AEON-Project/aigateway/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AEON-Project
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# AEON AI Gateway
+
+> AI Agents discover, invoke, and settle paid LLMs, APIs, and Skills — starting with **Skill Boss**.
+>
+> **No manual key setup. No prepayment. Pay-per-call via x402 or Agent Card.**
+
+A unified CLI + agent skill that lets an AI agent **purchase virtual debit cards** *and* **invoke AI services (image generation via Skill Boss)** in the same wallet, paid per-call with USDT on BSC via the [x402 protocol](https://www.x402.org/).
+
+Published as `@aeon-ai-pay/aigateway` (CLI: `aigateway`).
+
+## Install Skill
+
+```bash
+# Install to all detected agents (Claude Code, Cursor, Codex, OpenClaw, Gemini CLI, etc.)
+npx skills add AEON-Project/aigateway -g -y
+
+# Install to specific agents
+npx skills add AEON-Project/aigateway -a claude-code -a cursor -a codex -g -y
+```
+
+Supported agents: Claude Code, Cursor, Codex, OpenClaw, Gemini CLI, GitHub Copilot, Windsurf, Roo Code, and [39+ more](https://agentskills.io).
+
+## One-Glance Flow
+
+```
+aigateway wallet-init            # 1. auto-create local session wallet (pure local, no QR)
+aigateway wallet-topup --amount 5       # 2. WalletConnect: USDT top-up + one-time facilitator approve
+aigateway create-card --amount 5 # 3a. paid call: $5 virtual card via x402
+aigateway create-image --prompt "cyberpunk fox"  # 3b. paid call: AI image via x402
+```
+
+Step 2 covers the **only** manual moment — scanning a WalletConnect QR with your phone wallet to load ≥5 USDT once. Every subsequent paid call is a gasless EIP-712 signature against the local session key.
+
+## CLI Commands
+
+Every command accepts `--app-id <id>` (merchant identifier, default `TEST000001`). Every command emits a JSON *envelope* on stdout (`{ ok, command, version, data | error }`).
+
+| Command | Description | Key Options |
+| --- | --- | --- |
+| `wallet-init` | Check / create the local session wallet (pure local — no QR, no on-chain) | `--app-id <id>` |
+| `wallet-topup` | WalletConnect USDT top-up (≥5 USDT, presets 5/10/20/50) + one-time facilitator approve | `--amount <usdt>`, `--app-id <id>`, `--private-key <key>` |
+| `create-card` | Issue a one-time virtual Visa/Mastercard ($0.6 ~ $800) | `--amount <usd>` (required), `--app-id <id>`, `--poll`, `--dry-run`, `--topup-amount <usdt>` |
+| `create-image` | Generate an AI image via Skill Boss | `--prompt <text>` (required), `--app-id <id>`, `--aspect-ratio`, `--output-format`, `--model`, `--output <dir>`, `--topup-amount <usdt>` |
+| `create-card-status` | Query the status of a card issued via `create-card` | `--order-no <orderNo>` (required), `--app-id <id>`, `--poll` |
+| `wallet` | Show local wallet USDT + BNB balance | `--app-id <id>`, `--private-key` |
+| `wallet-gas` | Send BNB from main wallet to session key via WalletConnect | `--amount <bnb>` (default `0.001`), `--app-id <id>` |
+| `wallet-withdraw` | Reclaim USDT + BNB from session key back to main wallet | `--amount <usdt>` (default: all), `--to <address>`, `--app-id <id>` |
+| `clean` | Remove skill + uninstall global package | — |
+
+Global flags: `--legacy-output` (old JSON shape), `--verbose`, `--quiet`.
+
+## Wallet & Funding Model
+
+- **Session key**: A locally-generated private key stored at `~/.aigateway/config.json` (mode 0o600). It signs all paid calls and never leaves your machine.
+- **Main wallet**: Your existing MetaMask / OKX / Trust wallet. Connects only via WalletConnect QR — its key never touches the CLI.
+- **First-funding floor**: ≥ **1 USDT** (`LOW_BALANCE_THRESHOLD`) is enforced before any paid call.
+- **Per-top-up minimum**: ≥ **5 USDT** (`MIN_TOPUP_USDT`). Presets: 5 / 10 / 20 / 50, or custom ≥ 5.
+- **Approve once**: `wallet-topup` broadcasts a one-time `ERC20.approve(facilitator, MaxUint256)` (consumes ~0.0003 BNB). Subsequent paid calls reuse this allowance — no more on-chain transactions for the user.
+- **Gasless paid calls**: Both `create-card` and `create-image` are pure EIP-712 signatures; the facilitator pays gas for the actual USDT transfer.
+
+## Prerequisites
+
+- Node.js ≥ 25
+- A mobile wallet app with WalletConnect support (MetaMask, OKX Wallet, Trust Wallet, etc.)
+- USDT (BEP-20) and a small BNB balance in your main wallet for the one-time approve gas (~$0.002)
+
+## Quickstart for Developers
+
+Bundling `aigateway` inside your own agent product or merchant service? See:
+
+**Reference**
+- [docs/output-schema.md](docs/output-schema.md) — full envelope schema per command
+- [docs/exit-codes.md](docs/exit-codes.md) — exit code categories + `error.code` reference
+- [docs/env-vars.md](docs/env-vars.md) — `AIGATEWAY_SERVICE_URL`, `EVM_PRIVATE_KEY`, and the config-file fallback
+- [docs/troubleshooting.md](docs/troubleshooting.md) — common issues + remedies
+
+**Recipes**
+- [docs/recipes/integrate-in-agent.md](docs/recipes/integrate-in-agent.md) — generic Node.js / Python subprocess wrappers
+- [docs/recipes/merchant-integration.md](docs/recipes/merchant-integration.md) — merchant patterns (user-managed vs. custodial wallet, Express backend example)
+- [docs/recipes/error-recovery.md](docs/recipes/error-recovery.md) — code-by-code recovery strategy
+- [docs/recipes/cron-issue-cards.md](docs/recipes/cron-issue-cards.md) — scheduled paid calls
+
+**Agent / IDE adoption**
+- [docs/ide-setup.md](docs/ide-setup.md) — manual install templates for Cursor / Windsurf / Cline / Codex
+
+**Releasing**
+- [docs/release-process.md](docs/release-process.md) — version lock-step, publish, auto-upgrade flow
+- [CHANGELOG.md](CHANGELOG.md) — release history
+
+Minimal Node.js example:
+
+```js
+import { spawn } from "node:child_process";
+
+const child = spawn("aigateway", [
+  "--quiet", "create-card", "--amount", "5", "--app-id", "MY_AGENT_001", "--poll",
+]);
+let stdout = "";
+child.stdout.on("data", (b) => { stdout += b; });
+child.on("close", (code) => {
+  const env = JSON.parse(stdout.trim().split("\n").pop());
+  if (env.ok) console.log("Card ready:", env.data.orderNo);
+  else console.error(`[${env.error.code}] ${env.error.message}`);
+});
+```
+
+## Configuration
+
+Config lives at `~/.aigateway/config.json` (file mode 600). The default service URL (`https://ai-api.aeon.xyz`) is wired into the CLI; staging / custom backends can be overridden through environment variables only:
+
+- `AIGATEWAY_SERVICE_URL` — x402 service base URL
+- `EVM_PRIVATE_KEY` — override the saved session key (developer use)
+
+## License
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+
+const [major] = process.versions.node.split(".").map(Number);
+if (major < 25) {
+  console.error(`aigateway requires Node.js >= 25. Current: v${process.versions.node}`);
+  console.error("Upgrade: https://nodejs.org/");
+  process.exit(1);
+}
+
+// WalletConnect v2 SDK 已知缺陷：relay 偶发 null WebSocket 帧导致
+// isJsonRpcPayload 内部 'id' in null 抛 TypeError，不影响业务流程，静默忽略
+process.on("uncaughtException", (err) => {
+  if (
+    err instanceof TypeError &&
+    err.message.includes("Cannot use 'in' operator") &&
+    err.stack?.includes("isJsonRpcPayload")
+  ) {
+    console.error("[WC guard] Caught null-frame TypeError via uncaughtException, ignored.");
+    return;
+  }
+  console.error(err);
+  process.exit(1);
+});
+
+import { Command } from "commander";
+import { checkForUpdates } from "../src/update-check.mjs";
+import { setLegacyMode, setVerboseMode, setQuietMode } from "../src/output.mjs";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CURRENT_VERSION = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8")).version;
+checkForUpdates(CURRENT_VERSION);
+
+const program = new Command();
+
+const DEFAULT_APP_ID = "TEST000001";
+
+program
+  .name("aigateway")
+  .description("AEON AI Gateway — AI Agents discover, invoke, and settle paid LLMs, APIs, and Skills via x402 or Agent Card.")
+  .version(CURRENT_VERSION)
+  .option("--legacy-output", "Emit legacy JSON shape instead of the new envelope", false)
+  .option("--verbose", "Verbose stderr logs", false)
+  .option("--quiet", "Suppress non-error stderr logs", false)
+  .hook("preAction", (thisCommand) => {
+    const opts = thisCommand.opts();
+    setLegacyMode(opts.legacyOutput);
+    setVerboseMode(opts.verbose);
+    setQuietMode(opts.quiet);
+  });
+
+program
+  .command("wallet-init")
+  .description("Check / create the local session wallet (pure local, no on-chain, no QR)")
+  .option("--app-id <id>", "Merchant app ID", DEFAULT_APP_ID)
+  .action(async (opts) => {
+    const { initWallet } = await import("../src/commands/wallet-init.mjs");
+    return initWallet(opts);
+  });
+
+program
+  .command("wallet-topup")
+  .description("Top-up USDT (≥1 USDT floor / ≥5 USDT minimum per top-up) and one-time facilitator approve via WalletConnect")
+  .option("--app-id <id>", "Merchant app ID", DEFAULT_APP_ID)
+  .option("--amount <usdt>", "USDT amount to top-up (presets: 5/10/20/50, or custom ≥5)")
+  .option("--private-key <key>", "Override EVM private key")
+  .action(async (opts) => {
+    const { topup } = await import("../src/commands/wallet-topup.mjs");
+    return topup(opts);
+  });
+
+program
+  .command("wallet-balance")
+  .description("Check local wallet USDT/BNB balance on BSC")
+  .option("--app-id <id>", "Merchant app ID", DEFAULT_APP_ID)
+  .option("--private-key <key>", "Override EVM private key")
+  .action(async (opts) => {
+    const { wallet } = await import("../src/commands/wallet-balance.mjs");
+    return wallet(opts);
+  });
+
+program
+  .command("wallet-gas")
+  .description("Send BNB from main wallet to session key via WalletConnect (for withdraw / approve gas)")
+  .option("--app-id <id>", "Merchant app ID", DEFAULT_APP_ID)
+  .option("--amount <bnb>", "BNB amount to send", "0.001")
+  .option("--project-id <id>", "WalletConnect Cloud project ID")
+  .action(async (opts) => {
+    const { gas } = await import("../src/commands/wallet-gas.mjs");
+    return gas(opts);
+  });
+
+program
+  .command("wallet-withdraw")
+  .description("Withdraw USDT and remaining BNB from session key back to main wallet")
+  .option("--app-id <id>", "Merchant app ID", DEFAULT_APP_ID)
+  .option("--amount <usdt>", "USDT amount to withdraw (default: all)")
+  .option("--to <address>", "Override destination address")
+  .action(async (opts) => {
+    const { withdraw } = await import("../src/commands/wallet-withdraw.mjs");
+    return withdraw(opts);
+  });
+
+program
+  .command("create-card")
+  .description("Create a one-time virtual card by paying with USDT on BSC via x402")
+  .requiredOption("--amount <usd>", "Card amount in USD ($0.6 ~ $800)")
+  .option("--app-id <id>", "Merchant app ID", DEFAULT_APP_ID)
+  .option("--topup-amount <usdt>", "USDT top-up amount when balance is insufficient (≥5)")
+  .option("--private-key <key>", "Override EVM private key")
+  .option("--poll", "Auto-poll status after creation", false)
+  .option("--dry-run", "Run all preflight checks but do not sign/transact", false)
+  .action(async (opts) => {
+    const { createCard } = await import("../src/commands/create-card.mjs");
+    return createCard(opts);
+  });
+
+program
+  .command("create-image")
+  .description("Generate an AI image via Skill Boss, paying with USDT on BSC via x402")
+  .requiredOption("--prompt <text>", "Image prompt text")
+  .option("--app-id <id>", "Merchant app ID", DEFAULT_APP_ID)
+  .option("--aspect-ratio <ratio>", "Image aspect ratio", "16:9")
+  .option("--output-format <fmt>", "Image format (png/jpeg/webp)", "png")
+  .option("--model <id>", "Model identifier")
+  .option("--output <dir>", "Output directory (default ~/aigateway-images)")
+  .option("--topup-amount <usdt>", "USDT top-up amount when balance is insufficient (≥5)")
+  .option("--private-key <key>", "Override EVM private key")
+  .action(async (opts) => {
+    const { createImage } = await import("../src/commands/create-image.mjs");
+    return createImage(opts);
+  });
+
+program
+  .command("create-card-status")
+  .description("Query the status of a virtual card created via create-card")
+  .requiredOption("--order-no <orderNo>", "Order number returned by create-card")
+  .option("--app-id <id>", "Merchant app ID", DEFAULT_APP_ID)
+  .option("--poll", "Poll until terminal status", false)
+  .action(async (opts) => {
+    const { status } = await import("../src/commands/create-card-status.mjs");
+    return status(opts);
+  });
+
+program
+  .command("clean")
+  .description("Remove skill, uninstall package, and clear npm/npx cache")
+  .action(async () => {
+    const { clean } = await import("../src/commands/clean.mjs");
+    return clean();
+  });
+
+program.parse();

package/docs/env-vars.md

@@ -0,0 +1,73 @@
+# Environment Variables
+
+All environment variables that affect the `aigateway` CLI. Resolution priority for any setting: **CLI flag > env var > `~/.aigateway/config.json` > built-in default**.
+
+| Variable | Used by | Default | Purpose |
+| --- | --- | --- | --- |
+| `AIGATEWAY_SERVICE_URL` | All paid commands (`create-card`, `create-image`, `create-card-status`) | `https://ai-api.aeon.xyz` | Override the x402 service base URL. Useful for staging / local backends. |
+| `EVM_PRIVATE_KEY` | All commands needing a session key | (read from config file) | Override the saved session key. Required when running in custodial / containerised mode where you don't want a config file on disk. **Treat as a secret.** |
+| `AICARD_LEGACY_NOOP` | — | — | Reserved. Not currently used. |
+
+## Config file
+
+`~/.aigateway/config.json` (mode `0o600`). Persisted fields:
+
+```json
+{
+  "serviceUrl": "https://ai-api.aeon.xyz",
+  "privateKey": "0x...",
+  "address": "0x...",
+  "mode": "private-key",
+  "mainWallet": "0x..."
+}
+```
+
+- `serviceUrl` — written when overridden (rare).
+- `privateKey` / `address` / `mode` — written by `wallet-init` when auto-generating a session key.
+- `mainWallet` — auto-recorded after a successful `wallet-topup` so `wallet-withdraw` can default to that address.
+
+## CLI flag priority example
+
+```bash
+# All four set, --service-url wins
+AIGATEWAY_SERVICE_URL=https://env.example.com \
+  aigateway create-card --amount 5 --service-url=...   # (no such flag now — env wins)
+
+# Only env set
+AIGATEWAY_SERVICE_URL=https://staging.example.com \
+  aigateway create-card --amount 5
+
+# Nothing set → built-in default https://ai-api.aeon.xyz
+aigateway create-card --amount 5
+```
+
+The `--service-url` CLI flag has been removed in 0.1.0+ — use the env var or edit the config file directly.
+
+## Production hardening
+
+| Goal | How |
+| --- | --- |
+| Don't write key to disk | Set `EVM_PRIVATE_KEY` from a Vault / KMS fetch at process boot; never call `wallet-init` |
+| Pin to staging in CI | `export AIGATEWAY_SERVICE_URL=https://staging-x402.aeon.xyz` in your CI environment |
+| Confidential logging | Combine with `--quiet` to suppress stderr; pipe stdout to your structured logger |
+| Multi-tenant | Set `EVM_PRIVATE_KEY` per request via spawn `env` option (don't leak across tenants) |
+
+## Quick reference
+
+```bash
+# Default production
+aigateway wallet-init
+
+# Custodial server (key from Vault, no config file)
+EVM_PRIVATE_KEY=$(vault kv get -field=key merchants/acme-prod) \
+  aigateway create-card --amount 5 --app-id MERCHANT_ACME_001 --poll
+
+# Staging
+AIGATEWAY_SERVICE_URL=https://staging-x402.aeon.xyz \
+  aigateway create-card --amount 5 --app-id YOUR_TEST_APPID --poll
+
+# Both
+AIGATEWAY_SERVICE_URL=https://staging-x402.aeon.xyz \
+  EVM_PRIVATE_KEY=$STAGING_KEY \
+  aigateway wallet-balance
+```

package/docs/exit-codes.md

@@ -0,0 +1,65 @@
+# Exit Codes
+
+The `aigateway` CLI returns a stable exit code that maps to the category of outcome. Combine this with the `error.code` field in the JSON envelope (see [output-schema.md](./output-schema.md)) for precise programmatic handling.
+
+| Exit | Category | Meaning |
+| ---: | -------- | ------- |
+| `0` | Success | Command completed and produced an `ok: true` envelope. |
+| `1` | User error | Validation, configuration, balance, or user-side rejection. Caller should fix input and retry. |
+| `2` | Timeout | Polling, WalletConnect, signature, or on-chain wait exceeded its limit. The underlying operation may still complete asynchronously (e.g. card may still be provisioning). |
+| `3` | Service / network | Upstream service unavailable, network error, on-chain revert. Generally retryable after backoff. |
+| `4` | Internal | Unexpected internal error in the CLI. Please file an issue if reproducible. |
+
+## Error Code Reference
+
+The full set of `error.code` values, grouped by exit code, is defined in [`src/error-codes.mjs`](../src/error-codes.mjs).
+
+### Exit 1 — User Error
+
+| Code | When |
+| ---- | ---- |
+| `WALLET_NOT_CONFIGURED` | No local wallet. Run `aigateway wallet-init`. |
+| `SERVICE_URL_MISSING` | Service URL not configured. |
+| `AMOUNT_INVALID` | Amount could not be parsed. |
+| `AMOUNT_OUT_OF_RANGE` | Amount outside `amountLimits.min` ~ `amountLimits.max`. |
+| `AMOUNT_EXCEEDS_BALANCE` | `withdraw --amount` exceeds available USDT. |
+| `INSUFFICIENT_USDT` | USDT balance still insufficient after funding. |
+| `INSUFFICIENT_BNB` | No BNB for approve / withdraw gas. |
+| `NO_FUNDS` | Session wallet has zero USDT and zero BNB. |
+| `NO_MAIN_WALLET` | `wallet-withdraw` invoked without `--to` and no `mainWallet` in config. |
+| `MISSING_PROMPT` | `create-image` invoked without `--prompt`. |
+| `TOPUP_REQUIRED` | `wallet-topup` / `create-card` / `create-image` running non-TTY with `usdt < 1` and no amount argument. Choose from `error.presets` (5/10/20/50) and rerun (`topup --amount <n>` or pass `--topup-amount <n>` to `create-*`). |
+| `TOPUP_AMOUNT_TOO_SMALL` | `topup --amount` (or `create-* --topup-amount`) below `MIN_TOPUP_USDT` (5 USDT) or the per-call minimum (`error.minTopup`). |
+| `PAYMENT_REJECTED` | User rejected the transaction in their wallet. |
+
+### Exit 2 — Timeout
+
+| Code | When |
+| ---- | ---- |
+| `PAYMENT_TIMEOUT` | WalletConnect / signature request timed out (5 minutes). |
+| `WC_SESSION_EXPIRED` | WalletConnect session dropped mid-flow. |
+| `POLL_TIMEOUT` | `status --poll` exhausted attempts. Card may still be provisioning. |
+| `TX_TIMEOUT` | On-chain receipt wait exceeded 60 s. |
+
+### Exit 3 — Service / Network
+
+| Code | When |
+| ---- | ---- |
+| `SERVICE_UNAVAILABLE` | Generic upstream / network failure. |
+| `PAYMENT_FETCH_FAILED` | First 402 request to the service failed. |
+| `BALANCE_CHECK_FAILED` | RPC query to BSC failed. |
+| `ALLOWANCE_CHECK_FAILED` | RPC `allowance()` query failed. |
+| `TX_REVERTED` | On-chain transaction reverted. |
+| `WITHDRAW_FAILED` | Withdraw transaction failed (revert / RPC). |
+| `APPROVE_FAILED` | `wallet-init` could not broadcast or confirm the facilitator `approve()` tx. |
+| `FUNDING_FAILED` | WalletConnect funding flow failed (non-timeout / non-reject path). |
+| `IMAGE_DOWNLOAD_FAILED` | Generated image URL returned a non-200 / timed out. |
+| `INVALID_PAYMENT_AMOUNT` | Service returned a 402 with `amount === 0`. |
+| `PAYMENT_FAILED` | Service rejected the signed payment request. |
+
+### Exit 4 — Internal
+
+| Code | When |
+| ---- | ---- |
+| `INTERNAL_ERROR` | Unexpected error inside the CLI. |
+| `WALLET_ERROR` | Generic non-classified WalletConnect failure. (Exit 1 — treated as user-resolvable.) |

package/docs/ide-setup.md

@@ -0,0 +1,60 @@
+# IDE Setup
+
+The fastest path for most IDEs is the [skills CLI](https://agentskills.io), which auto-installs the bundled `skills/aigateway/SKILL.md` into every detected agent:
+
+```bash
+npx skills add AEON-Project/aigateway -g -y
+```
+
+For IDEs the skills CLI doesn't cover natively, copy the matching template from `templates/` into your project.
+
+## Cursor
+
+Cursor reads `.cursor/rules/*.mdc` from the project root.
+
+```bash
+mkdir -p .cursor/rules
+cp node_modules/@aeon-ai-pay/aigateway/templates/cursor/.cursor/rules/aigateway.mdc .cursor/rules/
+```
+
+If you installed `@aeon-ai-pay/aigateway` globally (`npm i -g`), substitute the `npm root -g` path. The `.mdc` file includes a `description:` line so Cursor can decide when to apply it.
+
+## Windsurf
+
+Windsurf reads `.windsurfrules` from the project root.
+
+```bash
+cp node_modules/@aeon-ai-pay/aigateway/templates/windsurf/.windsurfrules ./.windsurfrules
+```
+
+If you already have project-level Windsurf rules, append the contents of the template instead of overwriting.
+
+## Cline / Roo Code
+
+Both Cline and Roo Code read `.clinerules` from the project root.
+
+```bash
+cp node_modules/@aeon-ai-pay/aigateway/templates/cline/.clinerules ./.clinerules
+```
+
+## Codex / OpenAI Codex
+
+Codex reads `AGENTS.md` from the project root (or nested folders).
+
+```bash
+cp node_modules/@aeon-ai-pay/aigateway/templates/codex/AGENTS.md ./AGENTS.md
+```
+
+If your repo already has an `AGENTS.md`, append the `aigateway` section rather than overwriting.
+
+## Claude Code & 40+ Other Agents
+
+For Claude Code, OpenClaw, Gemini CLI, GitHub Copilot, and 30+ others, the [skills CLI](https://agentskills.io) installs the full `SKILL.md` automatically. No manual copying needed.
+
+## Verifying It Works
+
+After installation, in your IDE chat say:
+
+> Create me a $5 virtual card.
+
+The agent should propose running `aigateway wallet-init` (one-time, auto-creates a wallet) followed by `aigateway create-card --amount 5 --poll`. If it doesn't, the rule file isn't being picked up — check that the file path matches what your IDE expects and that the IDE has been restarted.