@openreceive/node 0.4.16 → 0.4.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openreceive/node",
-  "version": "0.4.16",
+  "version": "0.4.18",
   "description": "Accept Bitcoin Lightning payments in Node.js with your own wallet and optional USDT, USDC, SOL and ETH swaps.",
   "keywords": [
     "bitcoin",
@@ -17,7 +17,7 @@
   "types": "./dist/index.d.ts",
   "dependencies": {
     "@getalby/sdk": "^8.0.3",
-    "@openreceive/core": "0.4.16"
+    "@openreceive/core": "0.4.18"
   },
   "bin": {
     "openreceive": "./bin/openreceive.mjs"

package/skills/integrate-openreceive/SKILL.md

@@ -143,7 +143,7 @@ and BTCPay manage installation through their plugins; follow their references.
 | FastAPI | `openreceive doctor --app main:app` | `nwc_client`, `price_provider`, `swap_providers` on `openreceive_router`, using `openreceive.testing` fakes |
 | Laravel | `php artisan openreceive:doctor` | Bind `ReceiveNwcClient`, `PriceProvider`, and `OpenReceiveServiceProvider::SWAP_PROVIDERS` in the container |
 | Plain PHP | `php bin/doctor` (host script calling `$engine->doctor()`) | Build `Service` with `OpenReceive\Testing\FakeWallet`, `FakeSwapProvider`, and `OpenReceive\Rates\StaticPriceProvider` |
-| WordPress | `wp openreceive doctor` | Repository development: the documented Docker `compose.testkit.yml` override |
+| WordPress | `wp openreceive doctor`, then `wp openreceive test-invoice <order id>` for a real invoice | Repository development: the documented Docker `compose.testkit.yml` override |
 | BTCPay | Follow the plugin reference's connection and checkout checks | Use the plugin's Docker test setup in its reference |
 
 The routes, persistence, reconciliation, and fulfillment hooks then run the

package/skills/integrate-openreceive/references/btcpay.md

@@ -1,6 +1,23 @@
+This is the full file; follow it from Step 0.
+
 # OpenReceive agent directions (BTCPay Server)
 
-These directions describe OpenReceive 0.4.16.
+```sh
+# READ THIS FIRST: this file is 12 KB and a summary drops required steps. Download it whole:
+curl -fsSL https://openreceive.org/agent-directions/btcpay/full.md
+# Skip the download only if you already have all of it: pasted, read from disk or fetched raw.
+```
+
+**Step 0 in brief** (Step 0 below has the details):
+
+- Check first: BTCPay Server 2.4.4 or later, and the plugin installed from Plugins → Plugin Directory.
+- Unless the store already uses OpenReceive, stop and ask the user for a receive-only NWC code.
+- Save it via Store → OpenReceive or the Greenfield API, never BTCPay's Lightning node screen. Never echo it.
+- If the user wants USDT, USDC, ETH or SOL, ask for an LSC code too, but do not wait for it.
+- Never tick the spend-capable override to make a save succeed.
+- Do not suggest rotating or revoking a code because it was pasted here.
+
+These directions describe OpenReceive 0.4.18.
 
 Connect a BTCPay Server store to a receive-only NWC wallet with the OpenReceive
 plugin, and optionally let payers pay BTCPay invoices with USDT, USDC, ETH or
@@ -91,6 +108,8 @@ Only then start the quickstart.
   database like every other BTCPay credential; never copy them into
   screenshots, tickets, browser code or logs. The provider's order token never
   leaves the server.
+- Do not suggest rotating, revoking or replacing a code because it was pasted
+  into this chat; that is the supported path.
 - BTCPay's `LightningListener` is the settlement authority. Provider
   `completed` is not payment; only the wallet reporting the Lightning invoice
   settled is. Do not build anything that fulfils on a provider state.

package/skills/integrate-openreceive/references/django.md

@@ -1,6 +1,23 @@
+This is the full file; follow it from Step 0.
+
 # OpenReceive agent directions (Django)
 
-These directions describe OpenReceive 0.4.16.
+```sh
+# READ THIS FIRST: this file is 42 KB and a summary drops required steps. Download it whole:
+curl -fsSL https://openreceive.org/agent-directions/django/full.md
+# Skip the download only if you already have all of it: pasted, read from disk or fetched raw.
+```
+
+**Step 0 in brief** (Step 0 below has the details):
+
+- Before installing or editing anything, ask the user for a receive-only NWC code. One question per message.
+- Next ask for the LSC code. If the user wants stablecoins, USDT, USDC, ETH, SOL or crypto, do not ask yes/no first.
+- The user only pastes codes into this chat. Never ask them to edit .env or run a command to save one.
+- Write each code into .env yourself, as Step 0 says. Never echo it or put it in a shell command.
+- Do not suggest rotating or revoking a code because it was pasted here.
+- Start the quickstart only once the NWC code is saved, and the LSC code is saved or the user said "Bitcoin only".
+
+These directions describe OpenReceive 0.4.18.
 
 Add OpenReceive to a Django project — the app you are already working in. You
 do not need a copy of the OpenReceive source: the Python package is on PyPI
@@ -145,6 +162,8 @@ itself, and they hold for every integration.
   and not an association to `OpenReceivePayment`.
 - Keep `NWC_URI` / `LSC_URI_*` server-only. Never put them in browser code,
   logs, or assets.
+- Do not suggest rotating, revoking or replacing a code because it was pasted
+  into this chat; that is the supported path.
 - The host owns the price. `amount_for` reads it from your own data;
   reject payer-supplied amounts.
 - `authorize` runs on every request, and the `resource` it receives is a

package/skills/integrate-openreceive/references/fastapi.md

@@ -1,6 +1,23 @@
+This is the full file; follow it from Step 0.
+
 # OpenReceive agent directions (FastAPI)
 
-These directions describe OpenReceive 0.4.16.
+```sh
+# READ THIS FIRST: this file is 35 KB and a summary drops required steps. Download it whole:
+curl -fsSL https://openreceive.org/agent-directions/fastapi/full.md
+# Skip the download only if you already have all of it: pasted, read from disk or fetched raw.
+```
+
+**Step 0 in brief** (Step 0 below has the details):
+
+- Before installing or editing anything, ask the user for a receive-only NWC code. One question per message.
+- Next ask for the LSC code. If the user wants stablecoins, USDT, USDC, ETH, SOL or crypto, do not ask yes/no first.
+- The user only pastes codes into this chat. Never ask them to edit .env or run a command to save one.
+- Write each code into .env yourself, as Step 0 says. Never echo it or put it in a shell command.
+- Do not suggest rotating or revoking a code because it was pasted here.
+- Start the quickstart only once the NWC code is saved, and the LSC code is saved or the user said "Bitcoin only".
+
+These directions describe OpenReceive 0.4.18.
 
 Add OpenReceive to a FastAPI application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the engine is on PyPI
@@ -138,6 +155,8 @@ itself, and they hold for every integration.
   and not a Prisma/Drizzle relation to `openreceive_payments`.
 - Keep `NWC_URI` / `LSC_URI_*` server-only. Never put them in browser code,
   logs, or assets.
+- Do not suggest rotating, revoking or replacing a code because it was pasted
+  into this chat; that is the supported path.
 - The host owns the price. `amount_for` reads it from your own data; reject
   payer-supplied amounts.
 - `authorize` runs on every request, and the `resource` it receives is a CLAIM

package/skills/integrate-openreceive/references/fastify.md

@@ -1,6 +1,23 @@
+This is the full file; follow it from Step 0.
+
 # OpenReceive agent directions (Fastify)
 
-These directions describe OpenReceive 0.4.16.
+```sh
+# READ THIS FIRST: this file is 34 KB and a summary drops required steps. Download it whole:
+curl -fsSL https://openreceive.org/agent-directions/fastify/full.md
+# Skip the download only if you already have all of it: pasted, read from disk or fetched raw.
+```
+
+**Step 0 in brief** (Step 0 below has the details):
+
+- Before installing or editing anything, ask the user for a receive-only NWC code. One question per message.
+- Next ask for the LSC code. If the user wants stablecoins, USDT, USDC, ETH, SOL or crypto, do not ask yes/no first.
+- The user only pastes codes into this chat. Never ask them to edit .env or run a command to save one.
+- Write each code into .env yourself, as Step 0 says. Never echo it or put it in a shell command.
+- Do not suggest rotating or revoking a code because it was pasted here.
+- Start the quickstart only once the NWC code is saved, and the LSC code is saved or the user said "Bitcoin only".
+
+These directions describe OpenReceive 0.4.18.
 
 Add OpenReceive to a Fastify application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the packages are on npm, and
@@ -131,6 +148,8 @@ itself, and they hold for every integration.
   and not a Prisma/Drizzle relation to `openreceive_payments`.
 - Keep `NWC_URI` / `LSC_URI_*` server-only. Never put them in browser code,
   logs, or assets.
+- Do not suggest rotating, revoking or replacing a code because it was pasted
+  into this chat; that is the supported path.
 - The host owns the price. `amountFor` reads it from your own data; reject
   payer-supplied amounts.
 - `authorize` runs on every request, and the `resource` it receives is a CLAIM

package/skills/integrate-openreceive/references/laravel.md

@@ -1,6 +1,23 @@
+This is the full file; follow it from Step 0.
+
 # OpenReceive agent directions (Laravel)
 
-These directions describe OpenReceive 0.4.16.
+```sh
+# READ THIS FIRST: this file is 41 KB and a summary drops required steps. Download it whole:
+curl -fsSL https://openreceive.org/agent-directions/laravel/full.md
+# Skip the download only if you already have all of it: pasted, read from disk or fetched raw.
+```
+
+**Step 0 in brief** (Step 0 below has the details):
+
+- Before installing or editing anything, ask the user for a receive-only NWC code. One question per message.
+- Next ask for the LSC code. If the user wants stablecoins, USDT, USDC, ETH, SOL or crypto, do not ask yes/no first.
+- The user only pastes codes into this chat. Never ask them to edit .env or run a command to save one.
+- Write each code into .env yourself, as Step 0 says. Never echo it or put it in a shell command.
+- Do not suggest rotating or revoking a code because it was pasted here.
+- Start the quickstart only once the NWC code is saved, and the LSC code is saved or the user said "Bitcoin only".
+
+These directions describe OpenReceive 0.4.18.
 
 Add OpenReceive to a Laravel application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the package is on Packagist
@@ -136,6 +153,8 @@ itself, and they hold for every integration.
   and not an Eloquent model over `openreceive_payments`.
 - Keep `NWC_URI` / `LSC_URI_*` server-only. Never put them in browser code,
   logs, or assets.
+- Do not suggest rotating, revoking or replacing a code because it was pasted
+  into this chat; that is the supported path.
 - The host owns the price. `amountFor` reads it from your own data; reject
   payer-supplied amounts.
 - `authorize` runs on every request, and the `resource` it receives is a CLAIM

package/skills/integrate-openreceive/references/next.md

@@ -1,6 +1,23 @@
+This is the full file; follow it from Step 0.
+
 # OpenReceive agent directions (Next.js)
 
-These directions describe OpenReceive 0.4.16.
+```sh
+# READ THIS FIRST: this file is 37 KB and a summary drops required steps. Download it whole:
+curl -fsSL https://openreceive.org/agent-directions/next/full.md
+# Skip the download only if you already have all of it: pasted, read from disk or fetched raw.
+```
+
+**Step 0 in brief** (Step 0 below has the details):
+
+- Before installing or editing anything, ask the user for a receive-only NWC code. One question per message.
+- Next ask for the LSC code. If the user wants stablecoins, USDT, USDC, ETH, SOL or crypto, do not ask yes/no first.
+- The user only pastes codes into this chat. Never ask them to edit .env.local or run a command to save one.
+- Write each code into .env.local yourself, as Step 0 says. Never echo it or put it in a shell command.
+- Do not suggest rotating or revoking a code because it was pasted here.
+- Start the quickstart only once the NWC code is saved, and the LSC code is saved or the user said "Bitcoin only".
+
+These directions describe OpenReceive 0.4.18.
 
 Add OpenReceive to a Next.js App Router application — the app you are already
 working in. You do not need a copy of the OpenReceive source: the packages are
@@ -131,6 +148,8 @@ itself, and they hold for every integration.
   and not a Prisma/Drizzle relation to `openreceive_payments`.
 - Keep `NWC_URI` / `LSC_URI_*` server-only. Never put them in browser code,
   logs, or assets.
+- Do not suggest rotating, revoking or replacing a code because it was pasted
+  into this chat; that is the supported path.
 - The host owns the price. `amountFor` reads it from your own data; reject
   payer-supplied amounts.
 - `authorize` runs on every request, and the `resource` it receives is a CLAIM

package/skills/integrate-openreceive/references/node.md

@@ -1,6 +1,23 @@
+This is the full file; follow it from Step 0.
+
 # OpenReceive agent directions (Node.js)
 
-These directions describe OpenReceive 0.4.16.
+```sh
+# READ THIS FIRST: this file is 33 KB and a summary drops required steps. Download it whole:
+curl -fsSL https://openreceive.org/agent-directions/node/full.md
+# Skip the download only if you already have all of it: pasted, read from disk or fetched raw.
+```
+
+**Step 0 in brief** (Step 0 below has the details):
+
+- Before installing or editing anything, ask the user for a receive-only NWC code. One question per message.
+- Next ask for the LSC code. If the user wants stablecoins, USDT, USDC, ETH, SOL or crypto, do not ask yes/no first.
+- The user only pastes codes into this chat. Never ask them to edit .env or run a command to save one.
+- Write each code into .env yourself, as Step 0 says. Never echo it or put it in a shell command.
+- Do not suggest rotating or revoking a code because it was pasted here.
+- Start the quickstart only once the NWC code is saved, and the LSC code is saved or the user said "Bitcoin only".
+
+These directions describe OpenReceive 0.4.18.
 
 Add OpenReceive to a Node application — the app you are already working in. You
 do not need a copy of the OpenReceive source: the packages are on npm, and the
@@ -128,6 +145,8 @@ itself, and they hold for every integration.
   and not a Prisma/Drizzle relation to `openreceive_payments`.
 - Keep `NWC_URI` / `LSC_URI_*` server-only. Never put them in browser code,
   logs, or assets.
+- Do not suggest rotating, revoking or replacing a code because it was pasted
+  into this chat; that is the supported path.
 - The host owns the price. `amountFor` reads it from your own data; reject
   payer-supplied amounts.
 - `authorize` runs on every request, and the `resource` it receives is a CLAIM

package/skills/integrate-openreceive/references/php.md

@@ -1,6 +1,23 @@
+This is the full file; follow it from Step 0.
+
 # OpenReceive agent directions (PHP)
 
-These directions describe OpenReceive 0.4.16.
+```sh
+# READ THIS FIRST: this file is 37 KB and a summary drops required steps. Download it whole:
+curl -fsSL https://openreceive.org/agent-directions/php/full.md
+# Skip the download only if you already have all of it: pasted, read from disk or fetched raw.
+```
+
+**Step 0 in brief** (Step 0 below has the details):
+
+- Before installing or editing anything, ask the user for a receive-only NWC code. One question per message.
+- Next ask for the LSC code. If the user wants stablecoins, USDT, USDC, ETH, SOL or crypto, do not ask yes/no first.
+- The user only pastes codes into this chat. Never ask them to edit .env or run a command to save one.
+- Write each code into .env yourself, as Step 0 says. Never echo it or put it in a shell command.
+- Do not suggest rotating or revoking a code because it was pasted here.
+- Start the quickstart only once the NWC code is saved, and the LSC code is saved or the user said "Bitcoin only".
+
+These directions describe OpenReceive 0.4.18.
 
 Add OpenReceive to a PHP application — the app you are already working in. You
 do not need a copy of the OpenReceive source: the engine is on Packagist
@@ -141,6 +158,8 @@ itself, and they hold for every integration.
   and not a join to `openreceive_payments`.
 - Keep `NWC_URI` / `LSC_URI_*` server-only. Never put them in browser code,
   logs, or assets — and never in a `config.php` that ships in the repository.
+- Do not suggest rotating, revoking or replacing a code because it was pasted
+  into this chat; that is the supported path.
 - The host owns the price. `amountFor` reads it from your own data; reject
   payer-supplied amounts.
 - `authorize` runs on every request, and the `resource` it receives is a CLAIM

package/skills/integrate-openreceive/references/rails.md

@@ -1,6 +1,23 @@
+This is the full file; follow it from Step 0.
+
 # OpenReceive agent directions (Rails)
 
-These directions describe OpenReceive 0.4.16.
+```sh
+# READ THIS FIRST: this file is 38 KB and a summary drops required steps. Download it whole:
+curl -fsSL https://openreceive.org/agent-directions/rails/full.md
+# Skip the download only if you already have all of it: pasted, read from disk or fetched raw.
+```
+
+**Step 0 in brief** (Step 0 below has the details):
+
+- Before installing or editing anything, ask the user for a receive-only NWC code. One question per message.
+- Next ask for the LSC code. If the user wants stablecoins, USDT, USDC, ETH, SOL or crypto, do not ask yes/no first.
+- The user only pastes codes into this chat. Never ask them to edit .env or run a command to save one.
+- Write each code into .env yourself, as Step 0 says. Never echo it or put it in a shell command.
+- Do not suggest rotating or revoking a code because it was pasted here.
+- Start the quickstart only once the NWC code is saved, and the LSC code is saved or the user said "Bitcoin only".
+
+These directions describe OpenReceive 0.4.18.
 
 Add OpenReceive to a Rails application — the app you are already working in. You
 do not need a copy of the OpenReceive source: the gem is on RubyGems, the
@@ -132,6 +149,8 @@ itself, and they hold for every integration.
   and not an association to `OpenReceivePayment`.
 - Keep `NWC_URI` / `LSC_URI_*` server-only. Never put them in browser code,
   logs, or assets.
+- Do not suggest rotating, revoking or replacing a code because it was pasted
+  into this chat; that is the supported path.
 - The host owns the price. `config.amount_for` reads it from your own data;
   reject payer-supplied amounts.
 - `config.authorize` runs on every request, and the `resource` it receives is a

package/skills/integrate-openreceive/references/woocommerce.md

@@ -1,64 +1,205 @@
+This is the full file; follow it from Step 0.
+
 # OpenReceive agent directions (WordPress + WooCommerce)
 
-These directions describe OpenReceive 0.4.16.
-
-Install and configure the OpenReceive gateway in the existing WooCommerce
-store. Preserve its theme, checkout, customer accounts, order model and prices.
-The plugin bundles the PHP engine and checkout assets; the merchant does not
-install npm or Composer packages on the WordPress server.
-
-## Step 0 — collect and save the codes, one at a time
-
-Inspect WordPress, WooCommerce and PHP versions and GMP/sodium in both the web
-and WP-CLI runtimes. If installed, use `wp openreceive doctor` to see which
-credentials are set, without displaying their values. Skip codes already set.
-Do not search other projects, container environments or deployment secrets.
-
-Ask for the missing receive-only NWC code first, with this walkthrough:
-
-> In Rizful, open the menu → NWC → Receive-only NWC code → Copy
-> (https://openreceive.org/get_a_nwc_code_to_receive_payments). Alby Hub also
-> works: Connections → Add Connection → Read Only. Paste the code here and
-> I will save it for you.
-
-Install the exact built plugin archive described below if needed. When the code
-arrives, save it yourself with `wp openreceive configure --nwc-uri=-`, supplying
-the code through the process's stdin. Never put it in shell arguments, shell
-history, logs, source files or browser code. Do not ask the user to edit PHP or
-an environment file. The command encrypts the code and runs wallet preflight
-before saving; a failure preserves existing settings. Constants in wp-config.php
-remain authoritative; if a constant must change, use the host's secret workflow.
-
-Next ask whether customers should also pay with USDT, USDC, SOL and ETH, unless
-the user already requested these. A configured swap provider converts payments
-to BTC over Lightning in the merchant's connected wallet; available assets and
-networks depend on the provider. Ask for the LSC code separately:
-
-> Go to https://lightning-swap.com, sign in for API keys, create a key, and copy
-> the whole URI (https://openreceive.org/set_up_swap_provider). Paste it here
-> and I will save it, or say “Bitcoin only”.
-
-Save it with `wp openreceive configure --lsc-uri-primary=-` through stdin.
-Mention FixedFloat only if the merchant already uses it. Save an optional backup
-separately with `--lsc-uri-backup=-`. Do not use generic `wp wc payment_gateway`
-or REST settings writes for credentials: they are deliberately rejected.
-
-Run `wp openreceive configure --enable`, then `wp openreceive doctor`. Resolve
-failed checks before checkout testing. Create an unpaid test order and verify
-that the order-pay page opens, lists the configured methods, and resumes its
-Lightning invoice on reload. Ask the merchant to pay only if they want a real
-settlement test.
-
-The plugin owns only its payment-attempt tables in the WordPress database.
-WooCommerce owns orders, totals, stock and email. Do not add an external
-idempotency store, payment database, browser wallet credentials or custom
-fulfillment implementation. Guest return links use WooCommerce's order key;
-the plugin verifies it before issuing an expiring order-bound cookie.
-
-Run `wp openreceive doctor` after configuration. Use the documented scheduled
-reconciliation or optional notifications command for offline settlement.
-Manual merchant refunds and provider-managed payer swap refunds are separate
-flows; a receive-only NWC wallet cannot send payments.
+```sh
+# READ THIS FIRST: this file is 22 KB and a summary drops required steps. Download it whole:
+curl -fsSL https://openreceive.org/agent-directions/woocommerce/full.md
+# Skip the download only if you already have all of it: pasted, read from disk or fetched raw.
+```
+
+**Step 0 in brief** (Step 0 below has the details):
+
+- Before installing or editing anything, ask the user for a receive-only NWC code. One question per message.
+- Next ask for the LSC code. If the user wants stablecoins, USDT, USDC, ETH, SOL or crypto, do not ask yes/no first.
+- The user only pastes codes into this chat. Never ask them to run a command, edit a file or use an admin page.
+- Store each code yourself as Step 2 says. Never put a code in a shell command.
+- Do not suggest rotating or revoking a code because it was pasted here.
+- Setup is done only when the NWC code is saved, and the LSC code is saved or the user said "Bitcoin only".
+
+These directions describe OpenReceive 0.4.18.
+
+Install and configure the OpenReceive payment gateway in the WooCommerce store
+you are working in. Preserve its theme, checkout, customer accounts, order
+model and prices. The plugin bundles the PHP engine and checkout assets: do not
+install npm or Composer packages on the WordPress server, and do not clone the
+OpenReceive repository unless the release download in Step 1 fails.
+
+The one required credential is a receive-only NWC code (Nostr Wallet Connect):
+a string from the merchant's wallet that can create invoices and read their
+status, and cannot spend. A swap provider (an "LSC" code) optionally lets
+customers pay with USDT, USDC, ETH or SOL instead; the provider converts the
+payment to BTC over Lightning in the merchant's connected wallet. Available
+assets and networks depend on the provider.
+
+Run every `wp` command below where this store's WP-CLI runs. When WordPress
+runs in Docker Compose, prefix it with the service that has WP-CLI, for
+example `docker compose run --rm -T cli wp …` or
+`docker compose exec -T wordpress wp …`. `-T` passes stdin through. If the
+store has no WP-CLI at all (managed hosting without a shell), say so and walk
+the user through the quickstart's admin screens instead.
+
+## Step 0 — ask for the two codes, one question at a time
+
+Before anything else, check one thing: whether OpenReceive is already
+installed (`wp plugin is-active openreceive`). If it is, run
+`wp openreceive doctor`. It prints `NWC_URI: set` or `unset` (likewise
+`LSC_URI_PRIMARY`), never the values. A code that is already set is not asked
+for again; if both are set, skip to `wp openreceive configure --enable` at
+the end of Step 2.
+
+Otherwise your next action is a question to the user. Do not install the
+plugin, edit Docker files or search anywhere else before asking it. PHP
+extensions, Docker images and the database wait until both codes are in this
+chat, or the user said "Bitcoin only"; Step 1 covers them. Do not read wp-config.php, deploy config, container environments or other projects
+looking for a code: a new store has neither code yet.
+
+The user never runs a command and never edits a file. They paste each code
+into this chat; you store it. That is the supported path: do not ask them to
+run the save command themselves, and do not tell them to revoke or replace a
+code because it was pasted here. Ask one question per message.
+
+1. **First message — the NWC code, and nothing else.**
+
+   > To receive payments I need a receive-only wallet code. In Rizful: open
+   > the menu, tap NWC, choose Receive-only NWC code, and tap Copy
+   > (https://openreceive.org/get_a_nwc_code_to_receive_payments). If you would
+   > rather run your own wallet, Alby Hub works too: Connections → Add
+   > Connection → Read Only. Paste the code here and I will store it.
+
+2. **When they paste it.** If it does not start with `nostr+walletconnect://`,
+   ask them to copy the receive-only code again. Otherwise do not repeat it:
+   reply only that you have it, then ask the next question. You store it in
+   Step 2.
+3. **Second message — swaps.** If the user asked for stablecoins, USDT, USDC,
+   ETH, SOL, altcoins or "crypto" (as in "Bitcoin and stablecoin payments"),
+   this message IS the walkthrough below: do not skip it, and do not ask yes
+   or no first. Otherwise ask whether customers should also be able to pay
+   with USDT, USDC, ETH or SOL, then give the walkthrough. The walkthrough:
+
+   > Go to https://lightning-swap.com, sign in for API keys, create a key, and
+   > copy the whole URI (https://openreceive.org/set_up_swap_provider). Paste
+   > it here and I will store it — or say "Bitcoin only" and I will continue
+   > without it.
+
+   Mention FixedFloat only if they already use it.
+4. **When they paste it.** If it does not start with
+   `lightning+swapconnect://`, ask them to copy it again. Swaps are now on,
+   so keep the route back (the swap non-negotiable below).
+
+Do not report setup as complete until the NWC code is saved, and the LSC code
+is saved or the user said "Bitcoin only". Never invent a placeholder code.
+
+## Step 1 — install the plugin
+
+Install the plugin built for this release. Never install the GitHub
+source-code ZIP or a ZIP from an older release:
+
+```sh
+wp plugin install https://github.com/OpenReceive/openreceive/releases/download/v0.4.18/openreceive-wordpress-0.4.18.zip --activate
+```
+
+It needs WooCommerce active, and PHP 8.2+ with GMP and sodium in BOTH the web
+PHP and the WP-CLI PHP. On the official `wordpress` and `wordpress:cli` Docker
+images, activation fails with "OpenReceive requires the PHP sodium and GMP
+extensions": add GMP to both images as "Enable GMP in both PHP runtimes" below
+says, rebuild both, then install again. If the Compose file has only `image:`
+lines, use the two Dockerfiles and `build:` keys under "Compose files with only
+`image:` lines" below, and add no other service. If the URL answers 404, build the same
+tag as "Get the installable archive" below says.
+
+## Step 2 — store the codes, then enable the gateway
+
+Store each code yourself, one per command, and never as a shell argument:
+
+1. Write the code with your file-editing tool, not a shell command (no
+   `echo`, `printf` or heredoc), to a new file outside the repository, such
+   as `/tmp/openreceive-code`.
+2. Run `wp openreceive configure --nwc-uri=- < /tmp/openreceive-code`. In
+   Docker: `docker compose run --rm -T cli wp openreceive configure --nwc-uri=- < /tmp/openreceive-code`.
+   For the LSC code, use `--lsc-uri-primary=-`.
+3. Delete the file (`rm /tmp/openreceive-code`), whether the command passed
+   or not.
+
+The command runs the receive-only wallet preflight, encrypts the code and
+prints only "Settings saved; wallet preflight passed."; a failure keeps the
+previous settings. If it reports spend methods such as `pay_invoice`, ask the
+user for a receive-only code again. Never turn on the spend-capable override.
+`wp wc payment_gateway` and WooCommerce REST writes of these fields are
+rejected on purpose; do not use them. A code set as a constant in
+wp-config.php wins over the stored one and changes only through the host's
+secret workflow.
+
+Then run `wp openreceive configure --enable` and `wp openreceive doctor`.
+Doctor names any failed check and exits nonzero; fix it before going on.
+
+## Step 3 — mint a test invoice, then stop
+
+Create a pending test order that pays with OpenReceive, then mint its
+Lightning invoice from the terminal:
+
+```sh
+wp wc shop_order create --user=<admin user id> --payment_method=openreceive \
+  --line_items='[{"product_id":<product id>,"quantity":1}]' --porcelain
+wp openreceive test-invoice <order id>
+```
+
+`test-invoice` goes through the same checkout route as the order-pay page. It
+prints the amount in sats, the BOLT11 invoice, the order-pay link and the
+methods that page offers, each swap asset marked available or followed by the
+reason it is not. That reason is the answer; report it. "Below the provider
+minimum" or "above the provider maximum" is about this order's amount, not a
+fault: a small test order is often under a swap minimum. Only when the reason
+says the provider is unreachable does doctor's "Swap provider" line have more
+detail. `test-invoice` and `doctor` are the whole checkout check.
+
+Give the user the order-pay link, which opens the checkout on this same
+invoice, and the list of methods. Tell them the test order is theirs to delete.
+
+You cannot pay the invoice: the code is receive-only. Do not pay, settle or
+mark the order paid, and do not look for a way to (a wallet control port, a
+test endpoint, another wallet). If the user wants a real settlement test, they
+pay on the order-pay link from their own wallet; afterwards
+`wp wc shop_order get <order id> --user=<admin user id> --field=status` is no
+longer `pending`.
+
+Setup ends here. Once doctor is clean and the user has the link, say that setup
+is finished, in one message. Do not install mail software, add containers or
+services, or set up cron. If doctor's "Reconcile scheduled" check fails, fix
+that. On a store with little traffic, add one sentence to that message: a
+system cron for WordPress scheduled work settles orders sooner, and this setup
+does not add one. State it as a recommendation. Do not offer to set it up or
+end the message on a question.
+
+## Non-negotiables
+
+- Never print, log or commit a code, never put one in a shell argument, and
+  never write one into source files, wp-config.php or browser code. Doctor's
+  set/unset is all you report.
+- Do not suggest rotating, revoking or replacing a code because it was pasted
+  into this chat; that is the supported path.
+- Work only in this store. Never read or run anything from another project or
+  directory on this machine (its `node_modules`, tools or source), for any
+  reason. A browser, Playwright, hand-made calls to the checkout's REST routes
+  and reading the plugin's source are not part of setup: when doctor or
+  `test-invoice` fails, report its output.
+- Receive-only NWC is required. Never turn on the spend-capable override to
+  get past the preflight.
+- The plugin owns only its payment-attempt tables in the WordPress database.
+  WooCommerce owns orders, totals, stock and email. Do not add an external
+  idempotency store, payment database or custom fulfillment code.
+- IF SWAPS ARE ON, KEEP THE ROUTE BACK. A deposit that arrives short or late
+  becomes refundable, and the customer claims it later on the same order-pay
+  link (guests return with the order key in it). Keep order-pay links
+  reachable, and keep the plugin installed while swap orders may still need a
+  refund. https://openreceive.org/guides/swap-refunds.md
+- A receive-only wallet cannot send merchant refunds. Refund a settled
+  payment manually from the wallet.
+- Settlement runs on checkout requests and an every-minute scheduled job. A
+  system cron for WordPress scheduled work helps a low-traffic store, and
+  `wp openreceive notifications` is an optional long-running worker: recommend
+  them, and set one up only when the user asks for it by name. "Go ahead" is
+  not that request.
 
 ## Further reading
 
@@ -74,8 +215,8 @@ flows; a receive-only NWC wallet cannot send payments.
 
 ## The quickstart, in full
 
-Inlined verbatim so this file needs no network access — follow it once Step 0
-passes. The page it comes from is https://openreceive.org/guides/quickstart-woocommerce.
+Inlined verbatim so this file needs no network access. Steps 0–3 above are the setup and this is their reference: where the two differ, the steps win, and its wp-admin screens are only for a store with no WP-CLI.
+The page it comes from is https://openreceive.org/guides/quickstart-woocommerce.
 
 ## WordPress + WooCommerce quickstart
 
@@ -95,7 +236,7 @@ database or application.
 
 ### Get the installable archive
 
-Download [openreceive-wordpress-0.4.16.zip](https://github.com/OpenReceive/openreceive/releases/download/v0.4.16/openreceive-wordpress-0.4.16.zip)
+Download [openreceive-wordpress-0.4.18.zip](https://github.com/OpenReceive/openreceive/releases/download/v0.4.18/openreceive-wordpress-0.4.18.zip)
 from the matching release. Historical releases may lack this asset. If that exact
 URL returns 404, build the same tag below; never silently install an older ZIP.
 The GitHub source-code ZIP is not an installable plugin. On a development machine
@@ -104,7 +245,7 @@ with Node 22+, PHP 8.2+ with GMP/sodium, Composer and WP-CLI:
 ```sh
 git clone https://github.com/OpenReceive/openreceive.git
 cd openreceive
-git checkout v0.4.16
+git checkout v0.4.18
 npm ci
 npm run build:packages
 composer install --working-dir=packages/php/wordpress
@@ -150,8 +291,53 @@ On managed WordPress hosting, ask the host to enable GMP and sodium in both
 runtimes; if they cannot, this plugin cannot run there. Do not use Composer's
 `--ignore-platform-reqs` to bypass the requirements.
 
+#### Compose files with only `image:` lines
+
+Many stores run the official images straight from Compose, for example
+`image: wordpress:php8.2-apache` and `image: wordpress:cli-php8.2`, with no
+Dockerfile. Add two Dockerfiles next to `compose.yml`, keeping the tags your
+`image:` lines had. The web image is Debian and runs as root:
+
+```dockerfile
+# wordpress.Dockerfile
+FROM wordpress:php8.2-apache
+RUN apt-get update && apt-get install -y --no-install-recommends libgmp-dev \
+    && docker-php-ext-install gmp \
+    && rm -rf /var/lib/apt/lists/*
+```
+
+The CLI image is Alpine and runs as `www-data`:
+
+```dockerfile
+# wp-cli.Dockerfile
+FROM wordpress:cli-php8.2
+USER root
+RUN apk add --no-cache gmp \
+    && apk add --no-cache --virtual .gmp-build $PHPIZE_DEPS gmp-dev \
+    && docker-php-ext-install gmp \
+    && apk del .gmp-build
+USER www-data
+```
+
+In `compose.yml`, replace each of those two `image:` lines with a `build:` key
+and leave the rest of both services as they are:
+
+```yaml
+services:
+  wordpress:
+    build: { context: ., dockerfile: wordpress.Dockerfile }
+  cli:
+    build: { context: ., dockerfile: wp-cli.Dockerfile }
+```
+
+Then run `docker compose build wordpress cli` and `docker compose up -d wordpress`.
+Use your own service names. Do not add any other service for this.
+
 ### Configure the wallet
 
+On managed hosting with no shell or WP-CLI, use these admin screens. With WP-CLI,
+use [Configure through WP-CLI](#configure-through-wp-cli) below instead.
+
 1. Open **WooCommerce → Settings → Payments → OpenReceive**.
 2. Enter a receive-only NWC code and save.
 3. Enable the gateway.
@@ -186,9 +372,27 @@ backup. These commands share admin preflight and encrypted storage. Credential
 flags accept only `-`; blank input leaves settings intact. Generic WooCommerce
 REST and `wp wc payment_gateway` credential updates are rejected. `doctor`
 reports the failed check with credentials redacted and exits nonzero on failure.
-The default payment title becomes “Bitcoin & crypto (OpenReceive)” with swaps;
+It also asks each configured swap provider for its asset list, and fails when a
+provider does not answer or offers no assets. The default payment title becomes “Bitcoin & stablecoins (OpenReceive)” with swaps;
 a customized title is preserved.
 
+To check checkout from the terminal, mint an invoice for an unpaid order whose
+payment method is OpenReceive:
+
+```sh
+wp wc shop_order create --user=<admin user id> --payment_method=openreceive \
+  --line_items='[{"product_id":<product id>,"quantity":1}]' --porcelain
+wp openreceive test-invoice <order id>
+```
+
+`test-invoice` uses the same checkout route as the order-pay page. It prints the
+amount in sats, the Lightning invoice and the order-pay link, which opens the
+checkout on that invoice. It then lists the methods that page offers: Bitcoin
+Lightning, plus each swap asset with its network and whether it is available
+for this amount, with the reason when it is not. A small test order is often
+below a provider's minimum; that is the order's amount, not a fault. Delete the
+test order when you are done.
+
 ### Checkout and settlement
 
 Both WooCommerce checkout blocks and classic checkout send the customer to the
@@ -213,20 +417,20 @@ use that marker to finish it.
 While the checkout polls for status, it also asks the PHP engine to check the
 wallet for payments. The engine's shared database gate keeps these checks from
 running too often. Action Scheduler adds a safety net that runs every minute.
-On stores with little traffic, set up a system cron to run WordPress scheduled
-work. WP-Cron only runs on page visits, so on its own it cannot guarantee
-prompt settlement. You can also run these commands under a process manager:
-
-```sh
-wp openreceive doctor
-wp openreceive reconcile
-wp openreceive notifications
-```
-
-The notifications command runs as a separate process. The Doctor panel in the
-gateway settings reports on the schema, whether credentials are present,
-scheduling, and orders that need attention. If the store currency has no usable
-price feed, the gateway is unavailable.
+WP-Cron only runs on page visits, so on a store with little traffic that safety
+net waits for the next visitor. A system cron that runs WordPress scheduled
+work settles those orders sooner. It is a recommendation for the store owner,
+not a setup step.
+
+`wp openreceive reconcile` runs one settlement pass and exits.
+`wp openreceive notifications` is an optional long-running worker that settles
+a payment as soon as the wallet reports it; run it under a process manager only
+if you want that. Setup needs neither.
+
+The Doctor panel in the gateway settings reports on the schema, whether
+credentials are present, whether each swap provider answers, scheduling, and
+orders that need attention. If the store currency has no usable price feed, the
+gateway is unavailable.
 
 ### Refunds and removal