openreceive 0.4.29 → 0.4.31

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

@@ -17,7 +17,7 @@ curl -fsSL https://openreceive.org/agent-directions/php/full.md
 - 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.29.
+These directions describe OpenReceive 0.4.31.
 
 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
@@ -409,13 +409,12 @@ enough; drop the `.md` for the same page a person would read.
 - https://openreceive.org/guides/api-reference.md — every route, option and error code; the PHP section names every class above
 - https://openreceive.org/guides/custom-checkout-route.md — advanced: replacing the shipped handler's routes with your own
 - https://openreceive.org/guides/react-material-ui-recipe.md — a worked custom UI on a component library
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
 - https://openreceive.org/guides.md — the index, if what you need is not above
 
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
-- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
-
 ---
 
 ## The quickstart, in full

data/skills/integrate-openreceive/references/prestashop.md

@@ -0,0 +1,476 @@
+This is the full file; follow it from Step 0.
+
+# OpenReceive agent directions (PrestaShop)
+
+```sh
+# READ THIS FIRST: this file is 25 KB and a summary drops required steps. Download it whole:
+curl -fsSL https://openreceive.org/agent-directions/prestashop/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.31.
+
+Install and configure the OpenReceive payment module in the PrestaShop store
+you are working in. Preserve its theme, customers, products, orders and
+prices. The module is a ZIP that bundles the PHP engine and the checkout's
+script: do not install Composer or npm packages into PrestaShop, and do not
+clone the OpenReceive repository.
+
+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 `php` command below in PrestaShop's folder (the one that holds
+`bin/console`), as the web server's user, never as root: a root run can leave
+files in PrestaShop's `var/cache` that the web server cannot write. With
+PrestaShop's official Docker image, that is
+`docker compose exec -T -u www-data prestashop php bin/console …` (`-T` passes
+stdin through; use the PrestaShop service's own name; the container starts in
+`/var/www/html`). On a server, it is `sudo -u www-data php bin/console …` with
+the site's own user.
+
+## Step 0 — ask for the two codes, one question at a time
+
+Before anything else, check one thing: whether OpenReceive is already
+installed (`php bin/console openreceive:doctor`). If the command exists, 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 Step 3.
+
+Otherwise your next action is a question to the user. Do not download the
+module, edit Docker files or search anywhere else before asking it. Do not
+read PrestaShop's `app/config/parameters.php`, deploy config, container
+environments or other projects looking for a code: a new install 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 module
+
+The module needs PrestaShop 9 on 64-bit PHP 8.2+ with GMP and sodium. Check
+first: `php -m` must list both `gmp` and `sodium`. PrestaShop's official
+Docker image has sodium but not GMP, so with it, build an image that adds GMP:
+
+1. Put a `Dockerfile` next to the Compose file, with the same tag as the
+   PrestaShop service's `image:` line:
+
+   ```dockerfile
+   FROM prestashop/prestashop:<tag>
+   RUN apt-get update && apt-get install -y --no-install-recommends libgmp-dev \
+    && docker-php-ext-install gmp && rm -rf /var/lib/apt/lists/*
+   ```
+
+2. In the Compose file, replace that service's `image:` line with `build: .`
+   (the folder that holds the Dockerfile). Change nothing else in the file.
+3. Run `docker compose up -d --build`. PrestaShop's files and configuration
+   stay in the service's volume; only PHP changes. Check `php -m` again.
+
+On a server without GMP, say which PHP extension is missing and stop:
+installing PHP extensions on the user's server is theirs to decide. On
+PrestaShop 8, whose PHP stops at 8.1, say the module needs PrestaShop 9 and
+stop.
+
+The module is the ZIP attached to this GitHub release, one `openreceive`
+folder. Unzip it into PrestaShop's `modules` folder; it changes no PrestaShop
+file. Never install the GitHub source-code ZIP or a ZIP from an older release.
+With the Docker image, download and unpack it inside the container, as the
+web user, then install the module with PrestaShop's own console:
+
+```sh
+docker compose exec -T -u www-data prestashop sh -c 'curl -fsSLO https://github.com/OpenReceive/openreceive/releases/download/v0.4.31/openreceive-prestashop-0.4.31.zip && unzip -oq openreceive-prestashop-0.4.31.zip -d modules && rm openreceive-prestashop-0.4.31.zip'
+docker compose exec -T -u www-data prestashop php bin/console prestashop:module install openreceive
+```
+
+On a server, unpack it into `modules` the same way, make `modules/openreceive`
+the web user's, and run the same `prestashop:module install openreceive`.
+Installing creates the module's two tables in PrestaShop's database and its
+order state, "Awaiting Bitcoin payment", adds the payment option to checkout
+and makes the `openreceive:*` console commands appear. The option stays
+hidden until a wallet code is saved.
+
+## Step 2 — store the codes
+
+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 PrestaShop
+   folder, such as `/tmp/openreceive-code`.
+2. Run `php bin/console openreceive:configure --nwc-uri=- < /tmp/openreceive-code`.
+   In Docker: `docker compose exec -T -u www-data prestashop php bin/console 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 asks the wallet first and saves the code, encrypted with the
+shop's own key, only when the wallet answers as receive-only; a failure saves
+nothing. If it reports spend methods such as `pay_invoice`, ask the user for a
+receive-only code again. Saving the wallet code turns the payment option on;
+saving the swap code renames it to "Bitcoin & stablecoins". Never write a code
+into PrestaShop's database, `app/config/parameters.php` or any file in the
+PrestaShop folder yourself.
+
+Then run `php bin/console openreceive:doctor`. It names any failed check and
+exits nonzero; fix it before going on.
+
+## Step 3 — mint a test invoice, then stop
+
+Place a small test order for a hidden test product, bought by a test
+customer the command creates once (`openreceive-test@example.invalid`, so no
+real customer sees it and no email reaches anyone), and mint its Lightning
+invoice:
+
+```sh
+php bin/console openreceive:test-invoice --new
+```
+
+To use an order that already awaits its OpenReceive payment, pass its id
+instead of `--new`. `test-invoice` goes through the same route as the order's
+confirmation page. It prints the amount in sats, the BOLT11 invoice, the
+order's confirmation page and the methods the checkout 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. 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 check.
+
+Give the user the order's confirmation page, which opens the checkout on this
+same invoice in any browser. Tell them to cancel the test order under
+**Orders** when they are done: PrestaShop keeps every order.
+
+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 from the order's page with their own wallet; afterwards the order reads
+"Payment accepted".
+
+Setup ends here. Once doctor is clean and the user has the link, your last
+message starts "Setup is finished" and has at most six short lines: the
+order's page, the methods the checkout offers (Bitcoin, plus USDT, USDC, ETH
+and SOL when the swap code is saved), the cron line below, and one line of
+what to look at. Do not list each coin's availability, mention a minimum, or
+say a coin will not work: a provider minimum depends on the order total, and
+real orders will differ. Do not list what you changed or what doctor checked.
+Send nothing after it.
+
+PrestaShop has no scheduler, so the module's pass for customers who leave the
+page before their payment settles needs one cron line, every five minutes:
+`php bin/console openreceive:reconcile` as the web user. Give the user that
+line in your last message; do not add it yourself, and do not add containers,
+services or workers.
+
+## Non-negotiables
+
+- Never print, log or commit a code, never put one in a shell argument, and
+  never write one into source files, `app/config/parameters.php`, the
+  database 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 PrestaShop. 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
+  routes, database queries and reading the module's source are not part of
+  setup: when doctor or `test-invoice` fails, report its output.
+- Run `php` as the web server's user, never as root.
+- Receive-only NWC is required. Never get past the preflight with a code that
+  can spend.
+- The module owns only its two payment tables in PrestaShop's database.
+  PrestaShop owns customers, orders, prices, carriers and email. Do not add an
+  external payment database or custom fulfillment code, and do not edit
+  PrestaShop's own files or theme. The Dockerfile that adds GMP and the one
+  Compose line that builds it are the only deployment change.
+- IF SWAPS ARE ON, KEEP THE ROUTE BACK. A deposit that arrives short or late
+  becomes refundable, and the customer claims it later from the same order's
+  page. Keep the module installed while swap payments may still need a
+  refund. https://openreceive.org/guides/swap-refunds.md
+- A receive-only wallet cannot send refunds. Refund a settled payment manually
+  from the wallet.
+
+## Further reading
+
+- [PrestaShop Quickstart](https://openreceive.org/guides/quickstart-prestashop.md)
+- [Automated Swaps](https://openreceive.org/guides/automated-swaps.md)
+- [Swap Refunds](https://openreceive.org/guides/swap-refunds.md)
+- [Lightning Swap Connect URI](https://openreceive.org/guides/lightning-swap-connect.md)
+- [Security](https://openreceive.org/guides/security.md)
+- [Price Feeds](https://openreceive.org/guides/price-feeds.md)
+
+---
+
+## The quickstart, in full
+
+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 back-office screens are only for a PrestaShop with no shell.
+The page it comes from is https://openreceive.org/guides/quickstart-prestashop.
+
+## PrestaShop quickstart
+
+[PrestaShop](https://prestashop-project.org) is an open-source e-commerce
+platform. The OpenReceive module adds a payment option to it: the customer
+pays with Bitcoin over Lightning, straight into your own wallet, on
+PrestaShop's own order confirmation page. With a swap provider, the same page
+also takes USDT, USDC, SOL and ETH, which the provider converts to BTC over
+Lightning into the same wallet.
+
+PrestaShop keeps owning customers, orders, prices and carriers. The module
+keeps its payment attempts in two tables of PrestaShop's own database. When a
+payment settles, it records it the way PrestaShop's payment modules do: an
+order payment with the payment hash as its transaction id, in the same
+database transaction that settles the payment. The order then moves to
+PrestaShop's "Payment accepted", so PrestaShop makes the invoice, emails the
+customer and runs its other modules as it does for any other payment.
+
+Requirements: PrestaShop 9, on 64-bit PHP 8.2 or later with GMP and sodium,
+and PrestaShop's MySQL or MariaDB database. PrestaShop 8 runs on PHP 8.1 at
+most, below what the module needs. A cron job runs the module's reconcile
+pass, as [below](#the-cron-job).
+
+Already run BTCPay Server? [PrestaShop via BTCPay Server](https://openreceive.org/guides/prestashop.md) is
+the other way in: BTCPay's own PrestaShop module, with OpenReceive inside
+BTCPay.
+
+### Install the module
+
+Each GitHub release attaches the module as a ZIP with one folder,
+`openreceive`. In the back office, open **Modules → Module Manager**, click
+**Upload a module** and drop the ZIP in: PrestaShop unpacks it into
+`modules/openreceive` and installs it.
+
+From a shell, unzip it into PrestaShop's `modules` folder instead, and
+install it with PrestaShop's own console, in the folder that holds `bin/console`:
+
+```sh
+cd /var/www/html
+curl -fsSLO https://github.com/OpenReceive/openreceive/releases/download/v0.4.31/openreceive-prestashop-0.4.31.zip
+unzip -oq openreceive-prestashop-0.4.31.zip -d modules
+rm openreceive-prestashop-0.4.31.zip
+chown -R www-data:www-data modules/openreceive
+sudo -u www-data php bin/console prestashop:module install openreceive
+```
+
+Use your own PrestaShop folder and web server user. Installing creates the
+module's two tables and its order state, "Awaiting Bitcoin payment", and adds
+the payment option to checkout. The option stays hidden until a wallet code is
+saved.
+
+The ZIP already bundles the module's dependencies and the checkout's script,
+under their own prefixed names, so Composer never runs and nothing in
+PrestaShop's own `vendor/` changes. The GitHub source-code ZIP is not an
+installable module.
+
+#### PrestaShop in Docker
+
+PrestaShop's official image has sodium but not GMP. Build your own image on
+top of it: put this `Dockerfile` next to your `compose.yml`, use the same tag
+as your image,
+
+```dockerfile
+FROM prestashop/prestashop:9.2.0-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/*
+```
+
+and in `compose.yml` replace the PrestaShop service's `image:` line with
+`build: .`, then run `docker compose up -d --build`. PrestaShop's files, its
+configuration and the module stay in the named volume at `/var/www/html`; only
+PHP changes.
+
+Run every command inside the container, in `/var/www/html`, as its web user
+`www-data`. Unpack the release there too:
+
+```sh
+docker compose exec -T -u www-data prestashop sh -c 'curl -fsSLO https://github.com/OpenReceive/openreceive/releases/download/v0.4.31/openreceive-prestashop-0.4.31.zip && unzip -oq openreceive-prestashop-0.4.31.zip -d modules && rm openreceive-prestashop-0.4.31.zip'
+docker compose exec -T -u www-data prestashop php bin/console prestashop:module install openreceive
+```
+
+Always pass `-u www-data`. A command that runs as root can leave files in
+PrestaShop's `var/cache` that the web server cannot write.
+
+### Configure the wallet
+
+You need a receive-only NWC code: a Nostr Wallet Connect code that can create
+invoices and read payments but cannot spend. The module refuses a code that
+can spend.
+
+In the back office, open **Modules → Module Manager** and click **Configure**
+on **OpenReceive**. Paste the code into **Receive-only NWC code** and save. To
+accept stablecoins too, paste a swap provider code into **Swap provider
+code**. PrestaShop stores both encrypted with the shop's own key, and the page
+never shows them again; it says only whether each is set.
+
+From a terminal, pipe each code into `openreceive:configure` from your secret
+manager or a protected file. Never type a code as a command argument:
+
+```sh
+sudo -u www-data php bin/console openreceive:configure --nwc-uri=- < /secure/path/wallet-code
+sudo -u www-data php bin/console openreceive:configure --lsc-uri-primary=- < /secure/path/swap-code
+sudo -u www-data php bin/console openreceive:doctor
+```
+
+The settings page and `configure` both ask the wallet first and save the code
+only when it answers as a receive-only wallet. Saving the wallet code turns
+the payment option on. Saving a swap code renames the default "Bitcoin
+Lightning" to "Bitcoin & stablecoins"; the settings page's **Payment option
+name**, or `--name="…"`, sets your own. Skip the swap code for Bitcoin-only
+checkout. Checkout offers the option in the currencies ticked for OpenReceive
+under **Payment → Preferences**; installing ticks them all.
+
+`doctor` checks the module, PHP and its GMP and sodium, each code as set or
+unset (never its value), the order state, the payment option and its
+currencies, the tables, the checkout's files, the wallet, the price feed for
+every currency the shop sells in, each swap provider, and when the wallet was
+last scanned. It exits nonzero when a check fails.
+
+### The cron job
+
+PrestaShop has no scheduler of its own. While a customer has an order's page
+open, its checkout records the payment the moment it settles. For a customer
+who closes the page first, run the module's reconcile pass every five minutes
+from cron, as the web server's user:
+
+```cron
+*/5 * * * * www-data php /var/www/html/bin/console openreceive:reconcile
+```
+
+That line goes in `/etc/cron.d/`; in the web user's own crontab, leave out
+`www-data`. On hosting with a control panel, add a cron job with the same
+`php …/bin/console openreceive:reconcile` command. With Docker, the host's cron
+runs `docker compose exec -T -u www-data prestashop php bin/console openreceive:reconcile`
+from the Compose project's folder.
+
+Each pass also finishes any order whose payment settled but which did not
+move to "Payment accepted", and every checkout request runs one pass too.
+
+### Check it
+
+Make a Lightning invoice through the same route the order page uses, for a
+new $5 test order, or for any order awaiting its OpenReceive payment by its id:
+
+```sh
+sudo -u www-data php bin/console openreceive:test-invoice --new
+sudo -u www-data php bin/console openreceive:test-invoice <order id>
+```
+
+`--new` places an order for a hidden, downloadable test product, bought by a
+test customer it creates once, `openreceive-test@example.invalid`, so no real
+customer sees the order and its email reaches no one. `--amount=` changes
+what it costs. PrestaShop keeps every order: cancel the test order under
+**Orders** when you are done. Like any new order, it may reach the back
+office's notifications.
+
+It prints the amount in sats, the Lightning invoice and the order's
+confirmation page, then each method the checkout offers: Bitcoin Lightning,
+and each swap asset with its network and whether it is available for this
+amount. A small order is often below a swap provider's minimum; that is the
+amount, not a fault. The order's confirmation page carries the order's secret
+key, so it opens the checkout in any browser.
+
+### How a payment works
+
+1. The customer picks the OpenReceive option at checkout and places the
+   order. PrestaShop creates the order in "Awaiting Bitcoin payment" and opens
+   its order confirmation page with the checkout on it.
+2. The module charges the order's total with tax and shipping, in the order's
+   currency, converted to sats at the current BTC price. Only the customer the
+   order belongs to, signed in, or a browser PrestaShop already showed the
+   order to (its confirmation page, which needs the order's secret key, or
+   guest order tracking) may make or follow its payment, and only from a page
+   with the order's checkout, whose token comes back with each request.
+3. Once the wallet reports the payment, the module records an order payment
+   for it, with the payment hash as its transaction id, in the same database
+   transaction that settles it. Right after, the order moves to "Payment
+   accepted": PrestaShop makes the invoice, emails the customer and runs its
+   other modules' hooks. Should that step fail, the next pass finishes it.
+4. The page loads again and says the payment was received.
+
+A customer who leaves can come back from **Order history** in their account,
+or a guest from **Guest order tracking**: the order's page shows the
+checkout again while the order awaits its payment, with the same Lightning
+invoice while it is still valid.
+
+An unpaid order stays in "Awaiting Bitcoin payment" until you cancel it, as
+with any other payment that never came. If you cancel an order and its
+payment arrives afterwards, the module records the payment on the order,
+leaves the order cancelled, and logs a warning.
+
+Every line the module logs goes to PrestaShop's `var/logs/openreceive.log`.
+Warnings and errors also appear under **Advanced Parameters → Logs** in the
+back office.
+
+### Refunds and removal
+
+The receive-only wallet cannot send refunds. Send a refund from your own
+wallet, then record it in PrestaShop. A customer whose swap deposit never
+converted reclaims it from the same order's page, while the order still
+awaits its payment. If you turn on swaps, you commit to keeping that path
+available. See [swap refunds](https://openreceive.org/guides/swap-refunds.md).
+
+Disabling the module hides the payment option and its checkout. Uninstalling
+it also forgets both codes. It keeps the two tables, which are a record of
+payments received, and the "Awaiting Bitcoin payment" order state, which
+orders refer to.
+
+### Tested, and not tested
+
+Tested on 2026-10-19 with PrestaShop 9.2.0's official Docker image with GMP
+added (PHP 8.5), its Hummingbird theme, MariaDB 11.8, a test wallet and a
+test swap provider: the module uploaded through **Upload a module** in the
+back office, and installed from the unzipped ZIP with `bin/console
+prestashop:module install`; the swap code saved on the Configure page and
+both codes from stdin; the doctor; `test-invoice --new`; and in Chromium, a
+signed-in customer checking out with OpenReceive and paying on the order
+confirmation page by Lightning and by USDT on Solana, after which each order
+reads "Payment accepted" with its invoice. Coming back to the order through
+**Order history** resumed the same Lightning invoice. Another customer, with
+an order of their own, and a visitor were refused. A payment that settled
+with no page open was recorded by `openreceive:reconcile`. Uninstalling kept
+the payment records and the order state and forgot the codes.
+
+Not tested: PrestaShop 9.0 and 9.1, the Classic theme, nginx with PHP-FPM,
+shared hosting, multistore, friendly URLs turned off, guest checkout and guest
+order tracking, carts PrestaShop splits into several orders, and updating
+from an older release of the module.

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

@@ -17,7 +17,7 @@ curl -fsSL https://openreceive.org/agent-directions/rails/full.md
 - 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.29.
+These directions describe OpenReceive 0.4.31.
 
 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
@@ -393,13 +393,12 @@ enough; drop the `.md` for the same page a person would read.
 - https://openreceive.org/guides/api-reference.md — every route, option and error code
 - https://openreceive.org/guides/custom-checkout-route.md — advanced: replacing the mounted engine's routes with your own
 - https://openreceive.org/guides/react-material-ui-recipe.md — a worked custom UI on a component library
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
 - https://openreceive.org/guides.md — the index, if what you need is not above
 
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
-- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
-
 ---
 
 ## The quickstart, in full

data/skills/integrate-openreceive/references/react-router.md

@@ -17,7 +17,7 @@ curl -fsSL https://openreceive.org/agent-directions/react-router/full.md
 - 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.29.
+These directions describe OpenReceive 0.4.31.
 
 Add OpenReceive to a React Router application in framework mode — the app
 you are already working in, on Node. OpenReceive ships no React Router
@@ -421,13 +421,12 @@ enough; drop the `.md` for the same page a person would read.
 - https://openreceive.org/guides/custom-checkout-route.md — advanced: replacing the shipped adapter's routes with your own
 - https://openreceive.org/guides/react-material-ui-recipe.md — a worked custom UI on a component library
 - https://openreceive.org/guides/quickstart-next.md — each hook explained step by step, on Next.js; they are the same here
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
 - https://openreceive.org/guides.md — the index, if what you need is not above
 
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
-- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
-
 ---
 
 ## The quickstart, in full
@@ -467,7 +466,7 @@ npm install @openreceive/http @openreceive/react pg
 On Node, with `react-router-serve` or your own Express server. The wallet
 connection and your database driver need Node, so the route cannot run on an
 edge runtime. On Vercel or Netlify, read
-Bitcoin checkout on serverless hosts first. For
+[Bitcoin checkout on serverless hosts](https://openreceive.org/guides/serverless.md) first. For
 Cloudflare Workers, the [TanStack Start recipe](https://openreceive.org/guides/tanstack-start-recipe.md#where-it-runs)
 explains what a Worker needs. This recipe was not run on those hosts.
 
@@ -550,23 +549,23 @@ export default [
 `authorize` sees the incoming request with its cookies, so check it with the
 session your app already has. With `createCookieSessionStorage`,
 `currentVisitor` is `(await getSession(request.headers.get("cookie"))).get("visitor")`.
-The Next.js quickstart explains each hook.
+The [Next.js quickstart](https://openreceive.org/guides/quickstart-next.md) explains each hook.
 They are the same here.
 
 One stack serves the whole server process. A loader cannot see the
 connection, so the client address comes from a header. Without a proxy that
-sets it, the limit does not apply (Rate limiting).
+sets it, the limit does not apply ([Rate limiting](https://openreceive.org/guides/rate-limiting.md)).
 
 ### Your database
 
 `db` is a `pg` Pool, `node:sqlite` or `better-sqlite3`, or one of the
-adapters in Node ORM recipes. With Drizzle, pass
+adapters in [Node ORM recipes](https://openreceive.org/guides/node-orms.md). With Drizzle, pass
 the `pg` Pool underneath it.
 
 Create OpenReceive's two tables with your migrations
 (`npx openreceive scaffold payments --orm <your orm>`), or run
 `paymentsSchemaSql("postgres")` from `@openreceive/http` once. It is
-idempotent. See Payment storage.
+idempotent. See [Payment storage](https://openreceive.org/guides/storage.md).
 
 ### The checkout page
 
@@ -596,7 +595,7 @@ into your Tailwind entry (`app/app.css`); the checkout styles are compiled
 already. The page renders on the server and starts the checkout in the
 browser. The payer picks Bitcoin and gets the invoice. Keep it at the order's
 own URL: a payer with a swap deposit in flight comes back to it
-(Swap refunds).
+([Swap refunds](https://openreceive.org/guides/swap-refunds.md)).
 
 ### Settings