QuipNetwork · kleczkowski · Jun 30, 2026 · Jun 30, 2026 · Jun 30, 2026 · Jun 30, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -6,53 +6,20 @@ Guidance for coding agents working in this repository.
 
 ### Bitrefill
 
-Vendored at [`skills/bitrefill/`](skills/bitrefill/SKILL.md) (upstream: <https://github.com/bitrefill/agents/blob/main/skills/bitrefill/SKILL.md>). Read the full `SKILL.md` and follow its link-outs before acting.
+qupick's purchase layer is the **Bitrefill MCP** (`https://api.bitrefill.com/mcp`) — the `mcp__bitrefill__*` tools (`search-products`, `product-details`, `buy-products`, `get-invoice-by-id`). That MCP is the only hard dependency, and nothing from Bitrefill is vendored here. Connect it separately:
 
-**Bitrefill** sells digital goods (gift cards, mobile top-ups, eSIMs) across 180+ countries and 1,500+ brands. Pay with crypto, Lightning, USDC via x402, or pre-funded account balance. Codes deliver instantly after payment confirms.
-
-This skill **routes by capability, not by use case**. The same intent ("buy a Steam card") plays out differently across hosts — pick a path based on what the runtime can do.
-
-**Triggers:** the user mentions Bitrefill, gift cards, mobile top-up, eSIM data plan, refilling a phone, or asks to pay or check out with crypto, Lightning, USDC, or x402.
-
-#### Pick a path (first match wins)
-
-1. **Inside OpenClaw?** Check for `~/.openclaw/openclaw.json`, `~/.openclaw/skills/`, or `openclaw` on PATH. Default purchase path: guest CLI via `exec` (no auth). Sign in for `balance`/cashback.
-2. **Browse-only intent (no purchase)?** Residential-IP browser → browse path. Datacenter egress only → `www.bitrefill.com` returns 403 Cloudflare; use MCP `search-products` / `product-details` instead.
-3. **MCP supported?** Remote HTTP/SSE MCP at `https://api.bitrefill.com/mcp`. Highest-fidelity purchase channel — typed tool calls, OAuth or API key, no shell needed.
-4. **Shell + `npm install` available?** CLI ≥ 0.3.0: guest checkout first (`buy-products --email` + crypto). Sign in for `balance`, cashback, order history.
-5. **Outbound HTTP from agent loop?** REST API as last resort — verbose, no typed validation.
-6. **None of the above?** Give the user a `bitrefill.com` link and stop.
-
-#### Spending safeguards (read before any purchase)
-
-This skill enables **real-money transactions**. Codes deliver instantly and digital goods are non-refundable.
-
-- **Confirm before buying.** Present product, denomination, price, and payment method. Wait for explicit user approval. Autonomous purchasing only when the user opts in for the current session.
-- **Treat codes as cash.** Never paste them in group chats or public channels. Prefer in-memory storage over plain-text logs. Advise the user to redeem ASAP.
-- **Use a dedicated, low-balance account.** Never give the agent access to high-balance accounts or crypto wallet seeds. This skill is **not a wallet**.
-- **Log every purchase.** `invoice_id`, product, amount, payment method.
-
-#### Reference files
-
-| File | Use when |
-|------|----------|
-| [browse.md](skills/bitrefill/references/browse.md) | Agent has residential-IP browser; user wants to explore |
-| [mcp.md](skills/bitrefill/references/mcp.md) | MCP-capable host; preferred purchase path |
-| [cli.md](skills/bitrefill/references/cli.md) | Shell + npm; guest checkout or signed-in CLI ≥ 0.3.0 |
-| [cli-headless-auth.md](skills/bitrefill/references/cli-headless-auth.md) | Inbox + magic-link auth for headless agents |
-| [api.md](skills/bitrefill/references/api.md) | HTTP-only runtime; Personal / Business / Affiliate REST tiers |
-| [host-openclaw.md](skills/bitrefill/references/host-openclaw.md) | OpenClaw Gateway — guest CLI via `exec` preferred |
-| [capability-matrix.md](skills/bitrefill/references/capability-matrix.md) | Per-client viable paths cheat sheet |
-| [safeguards.md](skills/bitrefill/references/safeguards.md) | Spending policy + per-host hardening |
-| [troubleshooting.md](skills/bitrefill/references/troubleshooting.md) | Common errors across all paths |
+```bash
+claude mcp add --transport http bitrefill https://api.bitrefill.com/mcp --scope user
+```
 
-#### Source of truth
+Optionally, the upstream **bitrefill plugin** bundles the same MCP plus the bitrefill *skill* (capability routing, CLI/browse/REST fallbacks, safeguards prose) — `/plugin install bitrefill@bitrefill-skills`, run inside Claude Code (<https://github.com/bitrefill/agents>). qupick uses only the MCP tools, not the skill's mechanics.
 
-For exhaustive enums (countries, payment methods, full endpoint list), see <https://docs.bitrefill.com>.
+- **Enum/endpoint source of truth:** <https://docs.bitrefill.com>
+- **Real money:** codes deliver instantly and are non-refundable. Confirm product, price, and payment method before buying; use a dedicated low-balance account; never expose high-balance accounts or wallet seeds.
 
 ### Qupick
 
-Vendored at [`skills/qupick/SKILL.md`](skills/qupick/SKILL.md). Delegates purchase mechanics to the bitrefill skill above and adds portfolio selection on top.
+Vendored at [`skills/qupick/SKILL.md`](skills/qupick/SKILL.md). Delegates purchase mechanics to the Bitrefill MCP above and adds portfolio selection on top.
 
 **Triggers:** "pay with my worst performer", "use my worst crypto to buy X".
 

diff --git a/README.md b/README.md
@@ -4,15 +4,16 @@ Pay for a Bitrefill product (gift card, top-up, eSIM) with the **worst-performin
 portfolio — the asset with the lowest expected return μ — then retune the portfolio without it.
 
 The agent logic lives in [`SKILL.md`](skills/qupick/SKILL.md); this README is the operator's quick-start.
-Purchase mechanics are delegated to the sibling [`bitrefill`](skills/bitrefill/SKILL.md) skill.
+Purchase mechanics run on the **Bitrefill MCP** (the `mcp__bitrefill__*` tools), connected separately
+(see [Install the skill](#install-the-skill)).
 
 ## Register & set up (hosted)
 
 The fastest path uses the **live hosted server** at `https://qupick.quip.network` — you don't run any
 backend yourself. Five steps from clone to first run:
 
-1. **Install the skill.** Install `qupick` and its sibling `bitrefill` together (see
-   [Install the skill](#install-the-skill)).
+1. **Install the skills.** Install `qupick` (this repo) and the `bitrefill` plugin (from upstream) —
+   see [Install the skill](#install-the-skill).
 
 2. **Configure your defaults.** Copy the example and fill it in (see [Configure](#configure)):
 
@@ -63,8 +64,10 @@ server, see [Development](#development).
 - The **qupick MCP server** — the portfolio backend, registered via `.mcp.json` and exposing
   `mcp__qupick__*` tools. Use the hosted server at `https://qupick.quip.network/mcp` (above) or run
   it locally at `http://127.0.0.1:8000/mcp` (see [Development](#development)).
-- The **Bitrefill MCP** connected (`https://api.bitrefill.com/mcp`, OAuth or API key), or the
-  Bitrefill REST API key — used for product search, balance reads, and invoice creation.
+- The **Bitrefill MCP** connected (`https://api.bitrefill.com/mcp`, OAuth or API key) — qupick's
+  purchase layer. The `mcp__bitrefill__*` tools drive product search, balance reads, `buy-products`,
+  and invoice polling. Add it with `claude mcp add` (see [Install the skill](#install-the-skill)); the
+  Bitrefill REST API key is an alternative for the balance probe.
 - A funding source the waterfall can draw on: a pre-funded **Bitrefill account balance** (USD, EUR,
   and/or the worst-performing asset) and/or a funded on-chain wallet for that asset. The funding order is
   configurable (see [Configure](#configure)).
@@ -74,14 +77,27 @@ server, see [Development](#development).
 
 ## Install the skill
 
-Claude Code discovers skills under `.claude/skills/`. Because `qupick` links the bitrefill
-skill via the relative path `../bitrefill/SKILL.md`, install **both** as siblings:
+This repo ships the **qupick** skill. Its purchase layer is the **Bitrefill MCP** — connect that
+separately; the `mcp__bitrefill__*` tools are what qupick actually calls. Nothing from Bitrefill is
+vendored here.
 
-```bash
-mkdir -p .claude/skills
-cp -R skills/qupick .claude/skills/
-cp -R skills/bitrefill     .claude/skills/
-```
+1. **Bitrefill MCP (required).** Connect the hosted MCP; authenticate via OAuth (`/mcp`) or API key:
+
+   ```bash
+   claude mcp add --transport http bitrefill https://api.bitrefill.com/mcp --scope user
+   ```
+
+   Optional: the upstream **bitrefill plugin** bundles the same MCP plus the bitrefill *skill*
+   (multi-channel purchase guidance). Run these as slash-commands **inside Claude Code** (not a
+   shell): `/plugin marketplace add bitrefill/agents` → `/plugin install bitrefill@bitrefill-skills`
+   → `/reload-plugins` (<https://github.com/bitrefill/agents>). qupick needs only the MCP, not the skill.
+
+2. **qupick (this repo).** Claude Code discovers skills under `.claude/skills/`:
+
+   ```bash
+   mkdir -p .claude/skills
+   cp -R skills/qupick .claude/skills/
+   ```
 
 `.claude/` is gitignored — the skill install is local, not committed. The one tracked exception is
 `backend/.claude/settings.json`, the shared permission allowlist (see
@@ -230,7 +246,8 @@ Retune:   drop BTC, re-optimize over the remaining 10 currencies
 
 - The agent **never buys without explicit approval** — it always pauses at step 6.
 - Codes deliver instantly and are **non-refundable**; treat redemption codes as cash and redeem ASAP.
-- Use a dedicated, low-balance wallet. Full policy: [`safeguards.md`](skills/bitrefill/references/safeguards.md).
+- Use a dedicated, low-balance wallet. Never expose high-balance accounts or wallet seeds. (If you
+  install the optional bitrefill plugin, its `safeguards.md` covers per-host hardening too.)
 - The step-7 retune is irreversible — the spent asset leaves the basket until you re-add it.
 
 ## Development

diff --git a/skills/bitrefill/SKILL.md b/skills/bitrefill/SKILL.md
diff --git a/skills/bitrefill/references/api.md b/skills/bitrefill/references/api.md