@openreceive/node 0.4.17 → 0.4.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openreceive/node",
-  "version": "0.4.17",
+  "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.17"
+    "@openreceive/core": "0.4.18"
   },
   "bin": {
     "openreceive": "./bin/openreceive.mjs"

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.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/btcpay.md`), not through a summarizing tool: a summary drops steps.
+```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.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/django.md`), not through a summarizing tool: a summary drops steps.
+```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.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/fastapi.md`), not through a summarizing tool: a summary drops steps.
+```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.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/fastify.md`), not through a summarizing tool: a summary drops steps.
+```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.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/laravel.md`), not through a summarizing tool: a summary drops steps.
+```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.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/next.md`), not through a summarizing tool: a summary drops steps.
+```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.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/node.md`), not through a summarizing tool: a summary drops steps.
+```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.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/php.md`), not through a summarizing tool: a summary drops steps.
+```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.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/rails.md`), not through a summarizing tool: a summary drops steps.
+```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,6 +1,23 @@
+This is the full file; follow it from Step 0.
+
 # OpenReceive agent directions (WordPress + WooCommerce)
 
-These directions describe OpenReceive 0.4.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/woocommerce.md`), not through a summarizing tool: a summary drops steps.
+```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
@@ -32,8 +49,9 @@ 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. Do not
-read wp-config.php, deploy config, container environments or other projects
+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
@@ -78,14 +96,16 @@ 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.17/openreceive-wordpress-0.4.17.zip --activate
+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 URL answers 404, build the same
+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
@@ -113,7 +133,7 @@ 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
+## 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:
@@ -125,16 +145,44 @@ 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 and the order-pay link. Give the
-user that link: it opens the checkout with the configured methods and resumes
-this same invoice. Ask them to pay only if they want a real settlement test,
-and tell them the test order is theirs to delete.
+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.
@@ -147,9 +195,11 @@ and tell them the test order is theirs to delete.
   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. On a
-  low-traffic store, run WordPress scheduled work from a system cron;
-  `wp openreceive notifications` is an optional long-running worker.
+- 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
 
@@ -165,8 +215,8 @@ and tell them the test order is theirs to delete.
 
 ## 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
 
@@ -186,7 +236,7 @@ database or application.
 
 ### Get the installable archive
 
-Download [openreceive-wordpress-0.4.17.zip](https://github.com/OpenReceive/openreceive/releases/download/v0.4.17/openreceive-wordpress-0.4.17.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
@@ -195,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.17
+git checkout v0.4.18
 npm ci
 npm run build:packages
 composer install --working-dir=packages/php/wordpress
@@ -241,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.
@@ -277,7 +372,8 @@ 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
@@ -291,7 +387,11 @@ 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. Delete the test order when you are done.
+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
 
@@ -317,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