@kaleidorg/mind 0.0.1 → 0.2.0

package/skills/bitrefill/references/capability-matrix.md

@@ -0,0 +1,115 @@
+# Capability Matrix
+
+Per-host cheat sheet. Each entry = viable paths in priority order + one-line reason. Pick the first that fits, fall back as needed.
+
+Legend:
+
+- **MCP** → [mcp.md](mcp.md)
+- **CLI** → [cli.md](cli.md) (≥ 0.3.0: `login`/`verify`, not API key)
+- **API** → [api.md](api.md)
+- **Browse** → [browse.md](browse.md) (residential IP required)
+- **OpenClaw** → [host-openclaw.md](host-openclaw.md)
+
+## Anthropic
+
+### Claude.ai web — Free
+
+- No MCP custom URLs (Pro+ only). No shell. No residential browser.
+- **Path**: none viable for purchases. For browse: only if user installs Claude-for-Chrome extension → Browse.
+- **Fallback**: send user `bitrefill.com` link.
+
+### Claude.ai web — Pro / Max / Team / Enterprise / Cowork
+
+- MCP custom URLs allowed. Cowork adds desktop shell.
+- **Paths**: MCP first → Browse via Claude-for-Chrome ext.
+- Cowork only: + CLI via desktop shell.
+
+### Claude Desktop
+
+- MCP first-class (stdio + remote). No native shell, no native FS, no native HTTP — wire via MCP servers.
+- **Paths**: MCP first → CLI via stdio MCP wrapping `npx @bitrefill/cli` → Browse via Chrome ext or Computer Use.
+
+### Claude Code (CLI)
+
+- Most flexible. Full host shell, MCP, WebFetch, Chrome ext.
+- **Paths**: MCP first → CLI second → API via WebFetch / curl → Browse via Chrome ext or browser-use skill.
+- Tighten: sandbox allowlist `api.bitrefill.com`, `registry.npmjs.org`. Deny `~/.ssh`, `.env`.
+
+## OpenAI
+
+### ChatGPT web — Free
+
+- No custom MCP, no shell, datacenter browser → Cloudflare 403.
+- **Path**: none. Send user `bitrefill.com` link.
+
+### ChatGPT web — Plus / Pro / Business / Enterprise / Edu
+
+- Custom MCP via Apps & Connectors (Developer Mode for write tools). Code Interpreter has no network.
+- **Path**: MCP only. Browser is OpenAI datacenter — **do NOT route to Browse** (Cloudflare).
+
+### ChatGPT Desktop
+
+- Same as ChatGPT web. "Work with Apps" can read IDE/terminal panes but not execute.
+- **Path**: MCP only.
+
+### ChatGPT Atlas
+
+- Built-in Chromium with **residential IP** (user's network). Inherits account connectors. No shell.
+- **Paths**: Browse first (its superpower) → MCP via account connectors.
+
+### ChatGPT Agent (formerly Operator)
+
+- Sandboxed Linux + code interpreter. Hosted browser uses **OpenAI datacenter IP**.
+- **Paths**: MCP via account connectors → CLI inside sandbox shell → API via curl. **Do NOT route to Browse** (Cloudflare).
+
+### OpenAI Codex CLI
+
+- Full host shell (Seatbelt/Landlock sandboxable). MCP stdio + HTTP. Profiles in `config.toml`.
+- **Paths**: MCP first → CLI second → API via curl. Browser via MCP only.
+- Tighten: `--sandbox workspace-write --ask-for-approval on-request`. API key in profile, not committed config.
+
+## Google
+
+### Gemini consumer — Free
+
+- No MCP. No shell. No residential browser.
+- **Path**: none. Send user `bitrefill.com` link.
+
+### Gemini consumer — AI Pro / Ultra (US)
+
+- "Auto Browse" runs from Google IPs → likely Cloudflare-blocked on bitrefill.com.
+- **Path**: try Auto Browse + bitrefill.com URL; if blocked, send user the link.
+
+### Gemini CLI
+
+- Full host shell (sandboxable: Seatbelt / Docker / gVisor). MCP stdio + SSE + streamable-http.
+- **Paths**: MCP first → CLI second → API via `web_fetch` or curl. Browser via MCP (Chrome DevTools / Playwright).
+
+### Jules (async coding agent)
+
+- Ephemeral Ubuntu VM, Google IPs, no MCP exposed to user, no residential browser.
+- **Paths**: CLI inside VM → API via curl. **Not interactive** — best for batch tasks. No purchases recommended.
+
+## Other
+
+### Cursor IDE
+
+- Built-in browser tool, terminal tool, MCP (40-tool cap across servers). Cloud Agents in isolated VM.
+- **Paths**: MCP first → CLI in terminal → API via shell or built-in browser → Browse via built-in browser.
+- Tighten: keep `buy-products` out of `autoApprove` in `.cursor/mcp.json`.
+
+### OpenCode (sst/opencode)
+
+- Full host shell. MCP stdio + HTTP. Permission model per agent (`allow`/`ask`/`deny`).
+- **Paths**: MCP first → CLI second → API via `webfetch` or shell. Browser via MCP.
+
+### OpenClaw — superset host
+
+- Agentskills.io loader. MCP via `openclaw mcp set`. Full host shell + FS. `browser` tool uses host IP. Mobile nodes (camera, canvas, voice). Cron. Multi-channel chat (Telegram, WhatsApp, Slack, Discord, iMessage, Signal, Matrix, Teams, etc.).
+- **Paths**: read [host-openclaw.md](host-openclaw.md) **first**. **Guest CLI via `exec`** (preferred) → signed-in CLI (`balance`, cashback) → MCP → API → Browse.
+- Default agent: **Pi** (Anthropic / OpenAI / Google compatible via API key).
+- Unique scenarios: chat-channel purchase from phone, cron auto-renew top-ups, mobile camera OCR of receipts, multi-channel handoff.
+
+## Quick decision
+
+If user says "what host am I in?": run `command -v openclaw` and check `~/.openclaw/`. OpenClaw → guest CLI first. Else: MCP first (most hosts), fall back to CLI, then API.

package/skills/bitrefill/references/cli-headless-auth.md

@@ -0,0 +1,133 @@
+# Headless CLI auth (agents)
+
+Use when: agent must **sign up / sign in** without human at keyboard — unlock `balance`, cashback, order history.
+
+**Guest checkout needs no inbox** — pass `--email` on `buy-products` and pay crypto. Fastest first try; see [cli.md](cli.md) § Guest checkout.
+
+Use this doc when graduating guest → signed-in account with AgentMail or equivalent inbox.
+
+Requires `@bitrefill/cli` ≥ 0.3.0. Agent-owned inbox via **AgentMail or equivalent** — any provider with programmatic receive (list messages, parse body).
+
+## Why AgentMail or equivalent
+
+Bitrefill `login` sends magic-link code to email. Agent needs inbox API or MCP to poll/read messages without human. [AgentMail](https://www.agentmail.to/) is the reference implementation below; equivalent = Gmail API, IMAP, Mailgun inbound, etc. if your runtime already has access.
+
+## One-time inbox setup (AgentMail example)
+
+Human verifies provider account once. Agent handles Bitrefill after. Substitute your equivalent provider's sign-up + list/receive commands.
+
+```bash
+npm install -g agentmail-cli
+
+agentmail agent sign-up \
+  --human-email you@example.com \
+  --username bitrefill-agent
+# → api_key, inbox_id (e.g. bitrefill-agent@agentmail.to)
+
+export AGENTMAIL_API_KEY="am_..."   # from sign-up response
+
+agentmail agent verify --otp-code 123456   # human reads OTP from you@example.com
+```
+
+Official refs: [quickstart](https://docs.agentmail.to/quickstart.md), [agent onboarding](https://docs.agentmail.to/agent-onboarding.md).
+
+Optional (AgentMail): [AgentMail MCP](https://docs.agentmail.to/agent-onboarding.md) (`npx -y agentmail-mcp`) with `AGENTMAIL_API_KEY` — tools `list_threads`, `get_thread`, `get_message`. Equivalent providers: use their MCP/API instead.
+
+## Bitrefill auth flow
+
+Use agent inbox address as Bitrefill email (`inbox_id` from AgentMail or equivalent). Signup = login (same command).
+
+```bash
+npm install -g @bitrefill/cli
+
+bitrefill init --openclaw    # optional
+
+bitrefill login --email bitrefill-agent@agentmail.to
+```
+
+Poll inbox for Bitrefill verification email. AgentMail ([official list command](https://docs.agentmail.to/messages)):
+
+```bash
+agentmail inboxes:messages list --inbox-id bitrefill-agent@agentmail.to
+```
+
+Parse `extracted_text` or `text` from latest message for numeric code. Then:
+
+```bash
+bitrefill verify --code 123456
+```
+
+If Bitrefill account has TOTP, add `--otp` ([1Password](#totp-via-1password) below).
+
+Confirm:
+
+```bash
+bitrefill whoami --json
+# → { "identity": "registered", "email": "bitrefill-agent@agentmail.to", ... }
+```
+
+Then run catalog/purchase commands per [cli.md](cli.md).
+
+## End-to-end script sketch
+
+```bash
+INBOX="bitrefill-agent@agentmail.to"
+
+bitrefill login --email "$INBOX"
+sleep 5   # allow delivery
+
+CODE=$(agentmail inboxes:messages list --inbox-id "$INBOX" \
+  | jq -r '.messages[0].extracted_text // .messages[0].text' \
+  | grep -oE '[0-9]{6,8}' | head -1)
+
+bitrefill verify --code "$CODE"
+bitrefill whoami --json
+```
+
+Adjust regex/poll loop for your environment. Codes expire (~12–20 min server-side); on expiry re-run `login`.
+
+## TOTP via 1Password
+
+When Bitrefill account has authenticator enrolled, pass TOTP on verify.
+
+Secret reference ([official `op read`](https://www.1password.dev/cli/reference/commands/read)):
+
+```bash
+bitrefill verify --code "$CODE" \
+  --otp "$(op read 'op://Vault/Bitrefill/one-time password?attribute=otp')"
+```
+
+Item flag ([official `op item get --otp`](https://developer.1password.com/llms-cli.txt)):
+
+```bash
+bitrefill verify --code "$CODE" --otp "$(op item get Bitrefill --otp)"
+```
+
+Requires 1Password desktop app integration or service account. See [Get started with 1Password CLI](https://www.1password.dev/cli/get-started).
+
+## Safeguards
+
+- Dedicated low-balance Bitrefill account tied to agent inbox — not human primary email.
+- Agent inbox (AgentMail or equivalent) = auth surface; restrict who can read it.
+- `bitrefill reset` + re-login to rotate after compromise.
+- Never log magic-link codes or redemption codes to shared transcripts.
+
+Spending policy → [safeguards.md](safeguards.md).
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `Access token is required for login/verify` | Run any CLI command first (MCP connect mints token), or `bitrefill reset` then retry |
+| `No pending login` | Re-run `login --email` before `verify` |
+| Code invalid / expired | Re-run `login --email`; poll inbox again |
+| `browser_url` in login response | Passkey/WebAuthn — human opens URL, then retry |
+| Inbox empty after login | Wait + re-list; check spam; confirm inbox address matches provider setup |
+
+More CLI errors → [troubleshooting.md](troubleshooting.md).
+
+## Source of truth
+
+- AgentMail (reference): <https://docs.agentmail.to/quickstart.md>, <https://docs.agentmail.to/messages>
+- Bitrefill CLI: <https://github.com/bitrefill/cli> (≥ 0.3.0)
+- 1Password CLI: <https://www.1password.dev/cli/reference/commands/read>

package/skills/bitrefill/references/cli.md

@@ -0,0 +1,237 @@
+# Path: CLI
+
+Use when: shell + `npm install` available, **host has no MCP client** (CLI talks to Bitrefill MCP under the hood). Runtimes: Claude Code, Codex CLI, Cursor terminal, Gemini CLI, OpenCode, OpenClaw, Jules (ephemeral VM), ChatGPT Agent (sandbox).
+
+Requires **`@bitrefill/cli` ≥ 0.3.0**. Sandboxed shells must allowlist `registry.npmjs.org` and `api.bitrefill.com`.
+
+## Install
+
+```bash
+npm install -g @bitrefill/cli
+```
+
+From source: `git clone https://github.com/bitrefill/cli.git && cd cli && pnpm install && pnpm build && npm link`.
+
+## Guest checkout (fastest first try)
+
+**No `login` / `verify`.** Works while `whoami` shows `identity: unregistered`. Fastest path for autonomous agents to try Bitrefill — search, quote, create invoice, pay crypto or open payment link.
+
+```bash
+bitrefill search-products --query "Amazon" --country IT
+bitrefill get-product-details --product_id "amazon_it-italy"
+
+bitrefill buy-products \
+  --cart_items '[{"product_id":"amazon_it-italy","package_id":"10"}]' \
+  --payment_method lightning \
+  --return_payment_link true \
+  --email "agent@example.com"
+```
+
+Response: `invoice_id`, `payment_link`, optional `x402_payment_url` / Lightning invoice. Poll `get-invoice-by-id --invoice_id <uuid>`. Receipt goes to `--email`. Invoice expires in ~30 minutes.
+
+Guest payment methods: crypto (`lightning`, `usdc_base`, `bitcoin`, …) or `--return_payment_link true` (human/browser checkout, x402). **`balance` and `cashback` require a signed-in account** (below).
+
+## Sign up / sign in (balance, cashback, order history)
+
+After guest try, sign in when human wants **managed agent spending** or **rewards**:
+
+| Signed-in benefit | Why |
+|-------------------|-----|
+| **`--payment_method balance`** | Instant pay from store credit human pre-funds — natural spending cap, no on-chain wait |
+| **`--payment_method cashback`** | Pay from accumulated rewards balance (BTC) |
+| **Cashback on purchases** | Eligible products earn rewards back to account |
+| **`list-orders` / `list-invoices`** | Full order history + redemption codes in one place |
+
+Same `login` for new + existing accounts. Headless inbox → [cli-headless-auth.md](cli-headless-auth.md).
+
+```bash
+bitrefill login --email you@example.com
+bitrefill verify --code GGWK87DR              # email magic-link code
+bitrefill verify --code GGWK87DR --otp 122407   # + TOTP when account has 2FA
+bitrefill whoami --json
+
+# signed-in buy — instant from balance
+bitrefill buy-products \
+  --cart_items '[{"product_id":"amazon_it-italy","package_id":"10"}]' \
+  --payment_method balance \
+  --email "you@example.com"
+```
+
+**Verify gotchas** (from real agent sessions):
+
+- Email code → `verify --code <value>`, **not** `login --code` (unknown option).
+- `--otp` = **authenticator TOTP only** when account has 2FA — not the email code. Need both `--code` and `--otp` when enrolled.
+- After sign-in, `login` disappears from `--help`; run `logout` first to switch accounts or sign up another email.
+
+## Bootstrap (optional)
+
+```bash
+bitrefill init                    # optional OpenClaw wiring only
+```
+
+`init` no longer stores API keys. OpenClaw only: merges MCP config + generates `~/.openclaw/skills/bitrefill/SKILL.md`.
+
+## Auth
+
+CLI 0.3.0: **guest checkout needs no sign-in.** Account auth = OAuth client_credentials (automatic on first MCP connect) + email magic-link. No `--api-key`, no `credentials.json`.
+
+| Step | Command | Notes |
+|------|---------|-------|
+| Register client | any command (or `login`) | MCP connect mints `access_token`; stored in `~/.config/bitrefill-cli/<host>.v1.json` |
+| Sign up or sign in | `login --email <addr>` | same command for new + existing accounts |
+| Complete auth | `verify --code <code> [--otp <totp>]` | code from email; `--otp` when account has TOTP |
+| Check session | `whoami [--json]` | `identity: registered` + `email` when signed in |
+| Sign out | `logout` | revokes session; keeps `client_id` |
+| Full reset | `reset` | clears all local state + revokes session |
+
+**TOTP via 1Password** ([official `op read`](https://www.1password.dev/cli/reference/commands/read)):
+
+```bash
+bitrefill verify --code "$CODE" --otp "$(op read 'op://Vault/Bitrefill/one-time password?attribute=otp')"
+```
+
+Shorthand ([official `op item get --otp`](https://developer.1password.com/llms-cli.txt)):
+
+```bash
+bitrefill verify --code "$CODE" --otp "$(op item get Bitrefill --otp)"
+```
+
+Server may return `browser_url` for passkey/WebAuthn — open in browser, then retry.
+
+**Developer API keys** (Personal REST / key-in-path MCP) are separate from CLI auth. See [mcp.md](mcp.md) and [api.md](api.md).
+
+## Global flags
+
+Place **before** the subcommand:
+
+- **`--json`** — stdout is a single JSON value per run (TOON decoded to JSON); status/errors on **stderr**. Use with `jq`.
+
+```bash
+bitrefill --json search-products --query "Amazon" --per_page 1 | jq '.products[0].name'
+```
+
+## Agent discovery
+
+`manifest` emits JSON schema for every built-in + MCP command:
+
+```bash
+bitrefill manifest --json | jq '.commands[].name'
+bitrefill manifest -o bitrefill-manifest.json
+```
+
+`llm-context` embeds the same manifest in a fenced JSON block.
+
+## `llm-context`
+
+Regenerates Markdown from live MCP `tools/list` (params, JSON Schema, example invocations). Use for **CLAUDE.md**, Cursor rules, or **`.github/copilot-instructions.md`**. Connection line shows redacted MCP URL — safe to commit.
+
+```bash
+bitrefill llm-context -o BITREFILL-MCP.md
+```
+
+## OpenClaw quick-bootstrap
+
+Optional `bitrefill init --openclaw`: merges MCP stub into `~/.openclaw/openclaw.json` + emits skill SKILL.md. **Not required for guest CLI** — install CLI and run guest checkout directly via `exec`. OpenClaw prefers guest CLI first; see [host-openclaw.md](host-openclaw.md). Hardening → exec-approvals for `bitrefill buy-products`.
+
+## Workflow
+
+Subcommands discovered from remote MCP (`bitrefill --help` after connect). Core flow:
+
+```
+search-products  →  get-product-details  →  buy-products  →  get-invoice-by-id
+```
+
+### 1. Search
+
+```bash
+bitrefill search-products --query "Netflix" --country US
+bitrefill --json search-products --query "Netflix" --country US --per_page 5 | jq '.products'
+bitrefill search-products --query "eSIM" --product_type esim --country IT
+bitrefill search-products --query "*" --category games --country US
+```
+
+`--country` = uppercase Alpha-2. `--product_type` = `giftcard` or `esim` (singular). Discover categories: `--query "*"` returns a `categories` array with slugs.
+
+### 2. Details
+
+```bash
+bitrefill get-product-details --product_id "steam-usa" --currency USDC
+```
+
+Returns `packages` array. Each entry has `package_value` — that's the `package_id` for `buy-products`. Ignore the `<&>` compound key.
+
+Three denomination types:
+
+- **Numeric**: `5`, `50`, `200` (pass as number).
+- **Duration**: `"1 Month"`, `"12 Months"` (exact, case-sensitive).
+- **Named**: `"1GB, 7 Days"`, `"PUBG New State 300 NC"` (exact, case-sensitive).
+
+Only values from `get-product-details` accepted. Arbitrary amounts rejected.
+
+### 3. Buy
+
+`--cart_items` = JSON **array**, even single item. Max 15 items. **`--email`** = receipt address (required for guest; optional when signed in).
+
+```bash
+# Guest — crypto + payment link (no login)
+bitrefill buy-products \
+  --cart_items '[{"product_id":"amazon_it-italy","package_id":"10"}]' \
+  --payment_method lightning \
+  --return_payment_link true \
+  --email "agent@example.com"
+
+# Signed-in — instant from store credit
+bitrefill buy-products \
+  --cart_items '[{"product_id": "steam-usa", "package_id": 5}]' \
+  --payment_method balance \
+  --email "you@example.com"
+
+# Signed-in — crypto via x402
+bitrefill buy-products \
+  --cart_items '[{"product_id": "steam-usa", "package_id": 5}]' \
+  --payment_method usdc_base
+
+# Duration package
+bitrefill buy-products \
+  --cart_items '[{"product_id": "spotify-usa", "package_id": "1 Month"}]' \
+  --payment_method balance
+
+# Named eSIM
+bitrefill buy-products \
+  --cart_items '[{"product_id": "bitrefill-esim-europe", "package_id": "1GB, 7 Days"}]' \
+  --payment_method usdc_base
+```
+
+Response: `invoice_id`, `payment_link`, `x402_payment_url`, `payment_info` (`address`, `paymentUri`, `altcoinPrice`).
+
+### 4. Track / Redeem
+
+```bash
+bitrefill get-invoice-by-id --invoice_id "UUID"   # works guest (save invoice_id from buy response)
+bitrefill list-orders --include_redemption_info true   # signed-in only
+bitrefill get-order-by-id --order_id "ID"              # signed-in only
+```
+
+Invoices expire after 180 minutes. Expired = create new one.
+
+## Critical gotchas
+
+- `--cart_items` must be **array** `[...]`, not object `{...}`. Shell quoting matters: single quotes outside, double inside.
+- Use `package_value` after `<&>`, not the compound key. WRONG `"steam-usa<&>5"`. RIGHT `5`.
+- Named/duration `package_id` exact and case-sensitive. WRONG `"1GB"`. RIGHT `"1GB, 7 Days"`.
+- Country code uppercase Alpha-2. WRONG `us`, `USA`, `"United States"`. RIGHT `US`.
+- `login` / `verify` only when not signed in. After verify, `logout` before switching accounts.
+- Guest: `--payment_method balance` / `cashback` fail — use crypto or sign in first.
+- Signed-in + 2FA: `verify` needs **both** `--code` (email) and `--otp` (authenticator).
+
+## Recommended payment methods (for agents)
+
+**Guest (try first):** `lightning` or `usdc_base` + `x402_payment_url` → `--return_payment_link true` for human/browser pay.
+
+**Signed-in (production):** `balance` (instant, human caps spend via store credit) → `cashback` (rewards balance) → `usdc_base` x402 → `lightning`. Full list: `bitrefill buy-products --help`.
+
+## Source of truth
+
+- <https://github.com/bitrefill/cli> — full command reference, options, flags
+- <https://docs.bitrefill.com/docs/crypto-payments> — payment methods
+- `bitrefill manifest --json` / `bitrefill llm-context` — live tool list + schemas

package/skills/bitrefill/references/host-openclaw.md

@@ -0,0 +1,167 @@
+# Host: OpenClaw
+
+[OpenClaw](https://docs.openclaw.ai/) is a self-hosted Gateway that bridges chat apps (Telegram, WhatsApp, Slack, Discord, iMessage, Signal, Matrix, Teams, etc.) to coding agents like **Pi**. It is a **superset host**: full host shell, agentskills.io-compatible skill loader, first-class MCP, mobile-node camera/canvas, cron, and multi-channel routing.
+
+This file explains how to install + harden the Bitrefill skill inside OpenClaw and lists scenarios no other host can do. After setup, use the regular path files for the actual workflow.
+
+**OpenClaw path priority:** **guest CLI via `exec`** (no auth, fastest try) → signed-in CLI (`login`/`verify`, `balance`, cashback) → MCP → API → Browse. OpenClaw has shell + MCP — prefer guest CLI for purchases unless you need typed MCP tool calls or are already signed in for `balance`.
+
+## 1. Detect OpenClaw
+
+Check **any** of:
+
+- File: `~/.openclaw/openclaw.json` exists.
+- Dir: `~/.openclaw/skills/` exists.
+- Binary: `command -v openclaw` succeeds.
+- Tools in agent loop: `gateway`, `cron`, `nodes`, `canvas`, `sessions_*` (OpenClaw-only).
+
+If yes → continue here. Otherwise → return to [SKILL.md](../SKILL.md) and pick a path.
+
+## 2. Install this skill
+
+Loader paths (increasing precedence): `skills.load.extraDirs` → bundled → `~/.openclaw/skills/` → `~/.agents/skills/` → `<workspace>/.agents/skills/` → `<workspace>/skills/`.
+
+Manual:
+
+```bash
+cp -r path/to/bitrefill ~/.openclaw/skills/bitrefill
+openclaw skills list   # verify
+openclaw gateway restart   # or /new in chat
+```
+
+ClawHub (if/when published):
+
+```bash
+openclaw skills install bitrefill
+openclaw skills update --all
+```
+
+Skill is **agentskills.io-compatible** — no rewriting needed. Source: <https://docs.openclaw.ai/tools/skills.md>.
+
+## 3. Install Bitrefill CLI (preferred — guest checkout)
+
+Pi has first-class `exec` tool on Gateway host (sandboxing **off** by default). **Start here:** no login, no MCP config — search, buy, pay crypto or send payment link.
+
+```bash
+exec: npm install -g @bitrefill/cli
+exec: bitrefill search-products --query "Netflix" --country US
+exec: bitrefill buy-products \
+  --cart_items '[{"product_id":"steam-usa","package_id":10}]' \
+  --payment_method lightning \
+  --return_payment_link true \
+  --email "user@example.com"
+```
+
+Guest flow → [cli.md](cli.md) § Guest checkout. Optional: `bitrefill init --openclaw` (skill + MCP stub only — not required for guest).
+
+**Upgrade to signed-in** when human wants store-credit cap (`balance`), cashback, or order history:
+
+```bash
+exec: bitrefill login --email you@example.com
+exec: bitrefill verify --code <email-code> [--otp <totp>]
+```
+
+Headless sign-in inbox → [cli-headless-auth.md](cli-headless-auth.md) (AgentMail or equivalent).
+
+Docker sandbox: `setupCommand: "npm install -g @bitrefill/cli"`, `network` not `none`. Source: <https://docs.openclaw.ai/gateway/sandboxing.md>.
+
+## 4. Install Bitrefill MCP (optional)
+
+Use when: typed MCP tool calls in Pi loop without shell, or MCP-native integrations. **Not required for guest try** — guest CLI is faster (zero config).
+
+```bash
+openclaw mcp set bitrefill --url "https://api.bitrefill.com/mcp"
+```
+
+Or hand-edit `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "bitrefill": {
+        "url": "https://api.bitrefill.com/mcp"
+      }
+    }
+  }
+}
+```
+
+Developer API key (optional): see [mcp.md](mcp.md). Guest MCP checkout may still need OAuth; **guest CLI avoids this.**
+
+Transport: SSE/HTTP or `transport: "streamable-http"`. Restrict per-agent via `agents.list[].tools.allow`/`deny`. Source: <https://docs.openclaw.ai/cli/mcp.md>.
+
+Then: see [mcp.md](mcp.md).
+
+## 5. Raw API path
+
+`exec` + `curl`, or built-in `web_fetch` tool. No special config. See [api.md](api.md).
+
+## 6. Browser
+
+Pi has `browser` tool. **It uses the Gateway host's IP** — usually residential when Gateway runs on user's machine, but a VPS will hit Cloudflare 403. For richer DOM control attach a Playwright/Chrome MCP. The Mac menubar app drives user's actual Chrome and is fully residential. See [browse.md](browse.md).
+
+## 7. OpenClaw-only scenarios
+
+These are the differentiators. None of the other hosts can do them.
+
+### Buy a gift card from Telegram (away from desk)
+
+User DMs the bot: "buy a $50 Steam US card for me". Pi runs guest CLI via `exec` (or signed-in CLI with `balance` if human pre-funded account), prompts confirmation in chat, returns payment link or redemption code after poll.
+
+**Risk**: redemption codes are cash-like. Never deliver to group chats or via `MEDIA:` URLs. Lock down channel:
+
+```jsonc
+{
+  "channels": {
+    "telegram": {
+      "botToken": "${TELEGRAM_BOT_TOKEN}",
+      "dmPolicy": "pairing",
+      "allowFrom": ["123456789"],
+      "groups": { "*": { "requireMention": true } }
+    }
+  }
+}
+```
+
+Source: <https://docs.openclaw.ai/channels/telegram>.
+
+### Auto-renew mobile top-up monthly
+
+Use `cron` + `exec: bitrefill buy-products ...` for fixed SKU. Guest: crypto + poll `get-invoice-by-id`. Signed-in: `--payment_method balance` for instant pay without on-chain wait.
+
+### Multi-channel handoff
+
+Trigger purchase from Slack, deliver redemption code only to user's private Signal DM. Same Gateway, isolated session per channel/sender.
+
+### Mobile camera context
+
+Paired iOS/Android node exposes `camera.snap` and `canvas.*`. User photographs a request ("100 EUR Decathlon France"), Pi OCRs/parses, runs `exec: bitrefill search-products` + `exec: bitrefill buy-products` (guest or signed-in). Source: <https://docs.openclaw.ai/nodes/index.md>.
+
+### Heartbeat-driven invoice polling
+
+Default 30-min heartbeat or custom `cron` runs `exec: bitrefill get-invoice-by-id` until `status: complete`, then pushes redemption code to originating channel.
+
+## 8. OpenClaw-specific safeguards
+
+OpenClaw defaults are permissive: sandboxing off, `security: full`, `ask: off`. **Tighten before letting an agent buy on your behalf.**
+
+- **Restrict who triggers purchases**: `channels.<ch>.allowFrom: ["<your_id>"]` + `dmPolicy: "pairing"`. Same for WhatsApp, Signal, Slack, Discord.
+- **Require approval for buys**: `~/.openclaw/exec-approvals.json` with `security: allowlist` + `ask: on-miss`. Allowlist read-only CLI (`bitrefill search-products`, `bitrefill get-product-details`, `bitrefill get-invoice-by-id`); force `/approve` for `bitrefill buy-products`. Same pattern if using MCP `buy-products`.
+- **Isolate Bitrefill agent**: under `agents.list[]` declare a Bitrefill-scoped persona with `tools.deny: ["gateway"]` so the agent **cannot rewrite Gateway config** to bypass approvals. Source: <https://docs.openclaw.ai/tools/exec-approvals.md>.
+- **Guest first, balance when ready**: guest CLI + payment link = lowest friction; human pre-funds account + `login`/`verify` when agent needs capped `balance` spend. **Never** give the agent crypto wallet seeds. Skill is not a wallet.
+- **No voice readback of codes**: disable `audio_as_voice` / TTS for the Bitrefill agent. Pi's media pipeline could otherwise speak a cash-like code aloud over Telegram voice notes.
+- **No `MEDIA:<url>` for redemption codes**: enforce text-only delivery for the redemption tool output.
+
+## Source of truth
+
+- OpenClaw docs: <https://docs.openclaw.ai/>
+- Skills loader: <https://docs.openclaw.ai/tools/skills.md>
+- Creating skills: <https://docs.openclaw.ai/tools/creating-skills.md>
+- MCP CLI: <https://docs.openclaw.ai/cli/mcp.md>
+- Exec tool: <https://docs.openclaw.ai/tools/exec.md>
+- Sandboxing: <https://docs.openclaw.ai/gateway/sandboxing.md>
+- Exec approvals: <https://docs.openclaw.ai/tools/exec-approvals.md>
+- Nodes: <https://docs.openclaw.ai/nodes/index.md>
+- Channels: <https://docs.openclaw.ai/channels/telegram>
+- Bitrefill skill paths: [mcp.md](mcp.md), [cli.md](cli.md), [api.md](api.md), [browse.md](browse.md), [safeguards.md](safeguards.md)