openreceive 0.4.25 → 0.4.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92de70ca1044470b160698913fc4bcec615f0529de243fc7df86eddcd6d7cf95
-  data.tar.gz: e390588c785aa70eb0641f34e31d6953886592db3c2c24ddd67f8e17e797a1ea
+  metadata.gz: 66faa619377624dd7e90952d52d7ef0210a0d0ce4726647b34534caef7225e11
+  data.tar.gz: 320f45f340b8e2138f7ae6a7ee0fb7c5e9703e3a42bd0c94692622afbd9bee41
 SHA512:
-  metadata.gz: 2a14369f2156c50c446260eafe5d4915406d90e3a075a547770f2e0f6fcbd44c9c73c2b89ea3c11266b9afde8df7732a45ae5225cc0cc32f966d27bd74f23283
-  data.tar.gz: e6aae3ef1fccb7348e8b48a5150cb2e2d1ba437137256e06adde9c4f37c40666be992dae9c4a63de5ef931551f1afca600470b0af18003ff6c52e63608a904ee
+  metadata.gz: a048e3a24ef863bfcc34d2277db739631dd529f701d44d7d310b33eec681649ef6942bb8169ff3e6b820591338027ab4b599d04070708249c1567b280b4dca0d
+  data.tar.gz: 67476c05c9dff09b48f41fed17e26ce81150e26089a81658b2e03023ab505e53fbf444f5487d2721ab0def24e3c91fbc352c56a4abd69e469cf8b7371694ad5e

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.4.26 - 2026-10-14
+
+Release with the complete 0.4.26 package family. The bundled agent skill's
+directions say that a paid order's page shows that it is paid and no
+checkout, and that a Docker Compose app recreates its container after
+writing `.env`. The plain PHP directions describe the engine's new default
+cache. No Ruby runtime changes from 0.4.25.
+
 ## 0.4.25 - 2026-10-13
 
 Release with the complete 0.4.25 package family. The bundled agent skill

data/lib/openreceive/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenReceive
-  VERSION = "0.4.25"
+  VERSION = "0.4.26"
 end

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

@@ -17,7 +17,7 @@ curl -fsSL https://openreceive.org/agent-directions/btcpay/full.md
 - 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.25.
+These directions describe OpenReceive 0.4.26.
 
 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

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

@@ -3,7 +3,7 @@ This is the full file; follow it from Step 0.
 # OpenReceive agent directions (Django)
 
 ```sh
-# READ THIS FIRST: this file is 46 KB and a summary drops required steps. Download it whole:
+# READ THIS FIRST: this file is 47 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.
 ```
@@ -17,7 +17,7 @@ curl -fsSL https://openreceive.org/agent-directions/django/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.25.
+These directions describe OpenReceive 0.4.26.
 
 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
@@ -127,6 +127,8 @@ you store it. Ask one question per message.
    `settings.py` before anything reads the environment. When the app is started
    with Docker Compose, give the service `env_file: .env`. Restart the server
    after writing the file.
+   Under Compose, recreate the container with `docker compose up -d`:
+   `docker compose restart` keeps its old environment.
 
 Do not invent placeholder URIs. Start the quickstart only once `NWC_URI` is
 saved and `LSC_URI_PRIMARY` is saved or explicitly declined. The first boot
@@ -255,7 +257,12 @@ itself, and they hold for every integration.
   such window. On the drop-ins: `resumePaymentHash`, fed from `onState`, on
   `<Checkout>`; the `resume-payment-hash` attribute, fed from the
   `openreceive-state` event (`event.detail.state.payment_hash`), on
-  `<openreceive-checkout>`. https://openreceive.org/guides/swap-refunds.md
+  `<openreceive-checkout>`.
+  That visit can come hours later, and `authorize` must still know the payer:
+  a session that expired in between answers 403 and strands the deposit. On a
+  guest shop, tie the order to a long-lived signed cookie, or put a secret
+  per-order token in its URL that your page trades for that cookie.
+  https://openreceive.org/guides/swap-refunds.md
 - Show the payer WHAT THEY ARE BUYING. Return an optional `description` beside
   the price from `amount_for` and both drop-ins render it above the
   amount. Without it the checkout is a QR and "$1.00" with no sign of what the
@@ -303,6 +310,12 @@ products, and you do not join them.
   expired invoice does not cancel the order; a later checkout may mint another
   attempt. The engine refuses a new checkout under a reference that already
   settled (409).
+- **A paid order's page says it is paid and shows no checkout.** Nothing is left
+  to pay, and a checkout cannot start a new payment for a paid order. Mount the
+  checkout only while the order is unpaid. When it settles on the page, update
+  the page's status line from the `openreceive-settled` event on
+  `<openreceive-checkout>`: `on_paid` has already marked the order paid. Keep
+  that checkout mounted, because it is the payer's receipt.
 - **Do not relate to `OpenReceivePayment`.** No `ForeignKey`, no `OneToOne`, no
   `ManyToMany` either direction, and no admin `inline` on it. `reference` is not
   unique (many attempts per order). Fulfillment is a guarded transition on YOUR

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

@@ -3,7 +3,7 @@ This is the full file; follow it from Step 0.
 # OpenReceive agent directions (FastAPI)
 
 ```sh
-# READ THIS FIRST: this file is 41 KB and a summary drops required steps. Download it whole:
+# READ THIS FIRST: this file is 42 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.
 ```
@@ -17,7 +17,7 @@ curl -fsSL https://openreceive.org/agent-directions/fastapi/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.25.
+These directions describe OpenReceive 0.4.26.
 
 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
@@ -126,6 +126,8 @@ you store it. Ask one question per message.
    with `uvicorn --env-file .env` (update the app's run script or Procfile, not
    just your own command). When it is started with Docker Compose, give the
    service `env_file: .env`. Restart the server after writing the file.
+   Under Compose, recreate the container with `docker compose up -d`:
+   `docker compose restart` keeps its old environment.
    Doctor needs the file too: run it as
    `dotenv -f .env run -- openreceive doctor …`. The `dotenv` command comes
    with python-dotenv, which `uvicorn --env-file` already needs; if it is
@@ -248,7 +250,12 @@ itself, and they hold for every integration.
   such window. On the drop-ins: `resumePaymentHash`, fed from `onState`, on
   `<Checkout>`; the `resume-payment-hash` attribute, fed from the
   `openreceive-state` event (`event.detail.state.payment_hash`), on
-  `<openreceive-checkout>`. https://openreceive.org/guides/swap-refunds.md
+  `<openreceive-checkout>`.
+  That visit can come hours later, and `authorize` must still know the payer:
+  a session that expired in between answers 403 and strands the deposit. On a
+  guest shop, tie the order to a long-lived signed cookie, or put a secret
+  per-order token in its URL that your page trades for that cookie.
+  https://openreceive.org/guides/swap-refunds.md
 - Show the payer WHAT THEY ARE BUYING. Return an optional `description` beside
   the price from `amount_for` and both drop-ins render it above the amount.
   Without it the checkout is a QR and "$1.00" with no sign of what the dollar
@@ -308,6 +315,13 @@ orders, users, or products, and you do not join them.
   expired invoice does not cancel the order; a later checkout may mint another
   attempt. The library refuses a new checkout under a reference that already
   settled (409).
+- **A paid order's page says it is paid and shows no checkout.** Nothing is left
+  to pay, and a checkout cannot start a new payment for a paid order. Mount the
+  checkout only while the order is unpaid. When it settles on the page, update
+  the page's status line from `onSettled` on `<Checkout>`, or the
+  `openreceive-settled` event on `<openreceive-checkout>`: `on_paid` has already
+  marked the order paid. Keep that checkout mounted, because it is the payer's
+  receipt.
 - **Pass a sync SQLAlchemy `Engine` for this app's database.** Do not add an
   ORM relationship from Order to `openreceive_payments`, and do not implement
   `PaymentRepository` unless no SQLAlchemy engine can reach this database.

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

@@ -3,7 +3,7 @@ This is the full file; follow it from Step 0.
 # OpenReceive agent directions (Fastify)
 
 ```sh
-# READ THIS FIRST: this file is 39 KB and a summary drops required steps. Download it whole:
+# READ THIS FIRST: this file is 40 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.
 ```
@@ -17,7 +17,7 @@ curl -fsSL https://openreceive.org/agent-directions/fastify/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.25.
+These directions describe OpenReceive 0.4.26.
 
 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
@@ -123,6 +123,8 @@ you store it. Ask one question per message.
    `import "dotenv/config";` at the top of the server entry, as the quickstart
    does. When the app is started with Docker Compose, give the service
    `env_file: .env`. Restart the server after writing the file.
+   Under Compose, recreate the container with `docker compose up -d`:
+   `docker compose restart` keeps its old environment.
 
 Do not invent placeholder URIs. Start the quickstart only once `NWC_URI` is
 saved and `LSC_URI_PRIMARY` is saved or explicitly declined. The first boot
@@ -235,7 +237,12 @@ itself, and they hold for every integration.
   such window. On the drop-ins: `resumePaymentHash`, fed from `onState`, on
   `<Checkout>`; the `resume-payment-hash` attribute, fed from the
   `openreceive-state` event (`event.detail.state.payment_hash`), on
-  `<openreceive-checkout>`. https://openreceive.org/guides/swap-refunds.md
+  `<openreceive-checkout>`.
+  That visit can come hours later, and `authorize` must still know the payer:
+  a session that expired in between answers 403 and strands the deposit. On a
+  guest shop, tie the order to a long-lived signed cookie, or put a secret
+  per-order token in its URL that your page trades for that cookie.
+  https://openreceive.org/guides/swap-refunds.md
 - Show the payer WHAT THEY ARE BUYING. Return an optional `description` beside
   the price from `amountFor` and both drop-ins render it above the amount.
   Without it the checkout is a QR and "$1.00" with no sign of what the dollar
@@ -290,6 +297,13 @@ products, and you do not join them.
   expired invoice does not cancel the order; a later checkout may mint another
   attempt. The library refuses a new checkout under a reference that already
   settled (409).
+- **A paid order's page says it is paid and shows no checkout.** Nothing is left
+  to pay, and a checkout cannot start a new payment for a paid order. Mount the
+  checkout only while the order is unpaid. When it settles on the page, update
+  the page's status line from `onSettled` on `<Checkout>`, or the
+  `openreceive-settled` event on `<openreceive-checkout>`: `onPaid` has already
+  marked the order paid. Keep that checkout mounted, because it is the payer's
+  receipt.
 - **Pass this app's `db` handle.** Do not add a Prisma/Drizzle relation from
   Order to `openreceive_payments`, and do not implement `PaymentRepository`
   unless no supported handle can reach this database. `reference` is not unique

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

@@ -3,7 +3,7 @@ This is the full file; follow it from Step 0.
 # OpenReceive agent directions (Flask)
 
 ```sh
-# READ THIS FIRST: this file is 43 KB and a summary drops required steps. Download it whole:
+# READ THIS FIRST: this file is 44 KB and a summary drops required steps. Download it whole:
 curl -fsSL https://openreceive.org/agent-directions/flask/full.md
 # Skip the download only if you already have all of it: pasted, read from disk or fetched raw.
 ```
@@ -17,7 +17,7 @@ curl -fsSL https://openreceive.org/agent-directions/flask/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.25.
+These directions describe OpenReceive 0.4.26.
 
 Add OpenReceive to a Flask application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the engine is on PyPI
@@ -131,6 +131,8 @@ you store it. Ask one question per message.
    `dotenv -f .env run -- gunicorn …` (python-dotenv's CLI,
    `pip install "python-dotenv[cli]"`), in the app's run script or Procfile,
    not just your own command. Restart the server after writing the file.
+   Under Compose, recreate the container with `docker compose up -d`:
+   `docker compose restart` keeps its old environment.
    Doctor reads `.env` from its working directory by itself. Never `source`,
    `export` or `cat` the file: the codes contain `&`, and the shell prints the
    pieces.
@@ -252,7 +254,12 @@ itself, and they hold for every integration.
   such window. On the drop-ins: `resumePaymentHash`, fed from `onState`, on
   `<Checkout>`; the `resume-payment-hash` attribute, fed from the
   `openreceive-state` event (`event.detail.state.payment_hash`), on
-  `<openreceive-checkout>`. https://openreceive.org/guides/swap-refunds.md
+  `<openreceive-checkout>`.
+  That visit can come hours later, and `authorize` must still know the payer:
+  a session that expired in between answers 403 and strands the deposit. On a
+  guest shop, tie the order to a long-lived signed cookie, or put a secret
+  per-order token in its URL that your page trades for that cookie.
+  https://openreceive.org/guides/swap-refunds.md
 - Show the payer WHAT THEY ARE BUYING. Return an optional `description` beside
   the price from `amount_for` and both drop-ins render it above the amount.
   Without it the checkout is a QR and "$1.00" with no sign of what the dollar
@@ -315,6 +322,12 @@ orders, users, or products, and you do not join them.
   expired invoice does not cancel the order; a later checkout may mint another
   attempt. The library refuses a new checkout under a reference that already
   settled (409).
+- **A paid order's page says it is paid and shows no checkout.** Nothing is left
+  to pay, and a checkout cannot start a new payment for a paid order. Mount the
+  checkout only while the order is unpaid. When it settles on the page, update
+  the page's status line from the `openreceive-settled` event on
+  `<openreceive-checkout>`: `on_paid` has already marked the order paid. Keep
+  that checkout mounted, because it is the payer's receipt.
 - **Pass a sync SQLAlchemy `Engine` for this app's database.** Do not add an
   ORM relationship from Order to `openreceive_payments`, and do not implement
   `PaymentRepository` unless no SQLAlchemy engine can reach this database.

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

@@ -3,7 +3,7 @@ This is the full file; follow it from Step 0.
 # OpenReceive agent directions (Laravel)
 
 ```sh
-# READ THIS FIRST: this file is 45 KB and a summary drops required steps. Download it whole:
+# READ THIS FIRST: this file is 46 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.
 ```
@@ -17,7 +17,7 @@ curl -fsSL https://openreceive.org/agent-directions/laravel/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.25.
+These directions describe OpenReceive 0.4.26.
 
 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
@@ -130,6 +130,8 @@ you store it. Ask one question per message.
    `.env` the server reads (an image that copies `.env.example` over it
    drops them), start `php artisan serve` with `--no-reload`, or set
    `clear_env = no` for php-fpm. Restart the server after writing the file.
+   Under Compose, recreate the container with `docker compose up -d`:
+   `docker compose restart` keeps its old environment.
 
 Do not invent placeholder URIs. Start the quickstart only once `NWC_URI` is
 saved and `LSC_URI_PRIMARY` is saved or explicitly declined. The first boot
@@ -248,7 +250,12 @@ itself, and they hold for every integration.
   such window. On the drop-ins: `resumePaymentHash`, fed from `onState`, on
   `<Checkout>`; the `resume-payment-hash` attribute, fed from the
   `openreceive-state` event (`event.detail.state.payment_hash`), on
-  `<openreceive-checkout>`. https://openreceive.org/guides/swap-refunds.md
+  `<openreceive-checkout>`.
+  That visit can come hours later, and `authorize` must still know the payer:
+  a session that expired in between answers 403 and strands the deposit. On a
+  guest shop, tie the order to a long-lived signed cookie, or put a secret
+  per-order token in its URL that your page trades for that cookie.
+  https://openreceive.org/guides/swap-refunds.md
 - Show the payer WHAT THEY ARE BUYING. Return an optional `description` beside
   the price from `amountFor` and both drop-ins render it above the
   amount. Without it the checkout is a QR and "$1.00" with no sign of what the
@@ -293,6 +300,12 @@ not replace your orders, users, or products, and you do not join them.
   expired invoice does not cancel the order; a later checkout may mint another
   attempt. The engine refuses a new checkout under a reference that already
   settled (409).
+- **A paid order's page says it is paid and shows no checkout.** Nothing is left
+  to pay, and a checkout cannot start a new payment for a paid order. Mount the
+  checkout only while the order is unpaid. When it settles on the page, update
+  the page's status line from the `openreceive-settled` event on
+  `<openreceive-checkout>`: `onPaid` has already marked the order paid. Keep
+  that checkout mounted, because it is the payer's receipt.
 - **Do not model `openreceive_payments`.** No Eloquent model, no `hasMany`, no
   `belongsTo`, no foreign key either direction. `reference` is not unique (many
   attempts per order). Fulfillment is a guarded transition on YOUR order row

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

@@ -17,7 +17,7 @@ If your fetch tool gave you a summary, fetch that URL again for the full text.
 - Do not suggest rotating or revoking a code because it was pasted here.
 - Start Step 1 only once NWC_URI is saved, and LSC_URI_PRIMARY is saved or the user said "Bitcoin only".
 
-These directions describe OpenReceive 0.4.25.
+These directions describe OpenReceive 0.4.26.
 
 Add OpenReceive to this Lovable app: a TanStack Start app on Cloudflare
 Workers, with Lovable Cloud or a connected Supabase project as its database.
@@ -117,7 +117,7 @@ saved or explicitly declined.
 
 ## Step 1 — the packages
 
-Add `@openreceive/http` and `@openreceive/react` at 0.4.25 or newer.
+Add `@openreceive/http` and `@openreceive/react` at 0.4.26 or newer.
 Nothing else: no `pg`, no Postgres driver, no OpenReceive scaffold. Do not
 change the Vite or Wrangler configuration.
 
@@ -157,6 +157,12 @@ every settlement.
 - **The order is unpaid or paid.** Do not copy attempt statuses (`pending`,
   `expired`, `failed`, `attention`) onto it, and do not add a relation to
   `openreceive_payments`.
+- **A paid order's page says it is paid and shows no checkout.** Nothing is left
+  to pay, and a checkout cannot start a new payment for a paid order. Mount the
+  checkout only while the order is unpaid. When it settles on the page, update
+  the page's status line from `onSettled` on `<Checkout>`: `openreceive_on_paid`
+  has already marked the order paid. Keep that checkout mounted, because it is
+  the payer's receipt.
 
 ## Step 4 — `openreceive_on_paid`
 

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

@@ -3,7 +3,7 @@ This is the full file; follow it from Step 0.
 # OpenReceive agent directions (NestJS)
 
 ```sh
-# READ THIS FIRST: this file is 41 KB and a summary drops required steps. Download it whole:
+# READ THIS FIRST: this file is 42 KB and a summary drops required steps. Download it whole:
 curl -fsSL https://openreceive.org/agent-directions/nestjs/full.md
 # Skip the download only if you already have all of it: pasted, read from disk or fetched raw.
 ```
@@ -17,7 +17,7 @@ curl -fsSL https://openreceive.org/agent-directions/nestjs/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.25.
+These directions describe OpenReceive 0.4.26.
 
 Add OpenReceive to a NestJS application — the app you are already working in,
 on Nest's default Express platform. You do not need a copy of the OpenReceive
@@ -129,6 +129,8 @@ you store it. Ask one question per message.
    it. Otherwise put `import "dotenv/config";` first in `src/main.ts`, as the
    quickstart does. When the app is started with Docker Compose, give the
    service `env_file: .env`. Restart the server after writing the file.
+   Under Compose, recreate the container with `docker compose up -d`:
+   `docker compose restart` keeps its old environment.
 
 Do not invent placeholder URIs. Start the quickstart only once `NWC_URI` is
 saved and `LSC_URI_PRIMARY` is saved or explicitly declined. The first boot
@@ -253,7 +255,12 @@ itself, and they hold for every integration.
   such window. On the drop-ins: `resumePaymentHash`, fed from `onState`, on
   `<Checkout>`; the `resume-payment-hash` attribute, fed from the
   `openreceive-state` event (`event.detail.state.payment_hash`), on
-  `<openreceive-checkout>`. https://openreceive.org/guides/swap-refunds.md
+  `<openreceive-checkout>`.
+  That visit can come hours later, and `authorize` must still know the payer:
+  a session that expired in between answers 403 and strands the deposit. On a
+  guest shop, tie the order to a long-lived signed cookie, or put a secret
+  per-order token in its URL that your page trades for that cookie.
+  https://openreceive.org/guides/swap-refunds.md
 - Show the payer WHAT THEY ARE BUYING. Return an optional `description` beside
   the price from `amountFor` and both drop-ins render it above the amount.
   Without it the checkout is a QR and "$1.00" with no sign of what the dollar
@@ -305,6 +312,13 @@ products, and you do not join them.
   expired invoice does not cancel the order; a later checkout may mint another
   attempt. The library refuses a new checkout under a reference that already
   settled (409).
+- **A paid order's page says it is paid and shows no checkout.** Nothing is left
+  to pay, and a checkout cannot start a new payment for a paid order. Mount the
+  checkout only while the order is unpaid. When it settles on the page, update
+  the page's status line from `onSettled` on `<Checkout>`, or the
+  `openreceive-settled` event on `<openreceive-checkout>`: `onPaid` has already
+  marked the order paid. Keep that checkout mounted, because it is the payer's
+  receipt.
 - **Pass this app's `db` handle.** Do not add a Prisma/Drizzle relation from
   Order to `openreceive_payments`, and do not implement `PaymentRepository`
   unless no supported handle can reach this database. `reference` is not unique

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

@@ -3,7 +3,7 @@ This is the full file; follow it from Step 0.
 # OpenReceive agent directions (Next.js)
 
 ```sh
-# READ THIS FIRST: this file is 41 KB and a summary drops required steps. Download it whole:
+# READ THIS FIRST: this file is 42 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.
 ```
@@ -17,7 +17,7 @@ curl -fsSL https://openreceive.org/agent-directions/next/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.25.
+These directions describe OpenReceive 0.4.26.
 
 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
@@ -128,6 +128,8 @@ you store it. Ask one question per message.
    give a credential a `NEXT_PUBLIC_` prefix, which inlines it into the browser
    bundle. When the app is started with Docker Compose, give the service
    `env_file: .env.local`. Restart the dev server after writing the file.
+   Under Compose, recreate the container with `docker compose up -d`:
+   `docker compose restart` keeps its old environment.
 
 Do not invent placeholder URIs. Start the quickstart only once `NWC_URI` is
 saved and `LSC_URI_PRIMARY` is saved or explicitly declined. The first boot
@@ -240,7 +242,12 @@ itself, and they hold for every integration.
   such window. On the drop-ins: `resumePaymentHash`, fed from `onState`, on
   `<Checkout>`; the `resume-payment-hash` attribute, fed from the
   `openreceive-state` event (`event.detail.state.payment_hash`), on
-  `<openreceive-checkout>`. https://openreceive.org/guides/swap-refunds.md
+  `<openreceive-checkout>`.
+  That visit can come hours later, and `authorize` must still know the payer:
+  a session that expired in between answers 403 and strands the deposit. On a
+  guest shop, tie the order to a long-lived signed cookie, or put a secret
+  per-order token in its URL that your page trades for that cookie.
+  https://openreceive.org/guides/swap-refunds.md
 - Show the payer WHAT THEY ARE BUYING. Return an optional `description` beside
   the price from `amountFor` and both drop-ins render it above the amount.
   Without it the checkout is a QR and "$1.00" with no sign of what the dollar
@@ -296,6 +303,12 @@ products, and you do not join them.
   expired invoice does not cancel the order; a later checkout may mint another
   attempt. The library refuses a new checkout under a reference that already
   settled (409).
+- **A paid order's page says it is paid and shows no checkout.** Nothing is left
+  to pay, and a checkout cannot start a new payment for a paid order. Mount the
+  checkout only while the order is unpaid. When it settles on the page, update
+  the page's status line from `onSettled` on `<Checkout>`: `onPaid` has already
+  marked the order paid. Keep that checkout mounted, because it is the payer's
+  receipt.
 - **Pass this app's `db` handle.** Do not add a Prisma/Drizzle relation from
   Order to `openreceive_payments`, and do not implement `PaymentRepository`
   unless no supported handle can reach this database. `reference` is not unique
@@ -398,6 +411,7 @@ 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/tanstack-start-recipe.md — the same handler as a TanStack Start server route, if this app is TanStack Start after all
+- https://openreceive.org/guides/sveltekit-recipe.md, https://openreceive.org/guides/nuxt-recipe.md, https://openreceive.org/guides/astro-recipe.md and https://openreceive.org/guides/react-router-recipe.md — the same handler as a SvelteKit, Nuxt, Astro or React Router route, if this app is one of those
 - https://openreceive.org/guides.md — the index, if what you need is not above
 
 Questions, or a problem with the library itself:

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

@@ -3,7 +3,7 @@ This is the full file; follow it from Step 0.
 # OpenReceive agent directions (Node.js)
 
 ```sh
-# READ THIS FIRST: this file is 38 KB and a summary drops required steps. Download it whole:
+# READ THIS FIRST: this file is 39 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.
 ```
@@ -17,7 +17,7 @@ curl -fsSL https://openreceive.org/agent-directions/node/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.25.
+These directions describe OpenReceive 0.4.26.
 
 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
@@ -125,6 +125,8 @@ you store it. Ask one question per message.
    `import "dotenv/config";` at the top of the server entry, as the quickstart
    does. When the app is started with Docker Compose, give the service
    `env_file: .env`. Restart the server after writing the file.
+   Under Compose, recreate the container with `docker compose up -d`:
+   `docker compose restart` keeps its old environment.
 
 Do not invent placeholder URIs. Start the quickstart only once `NWC_URI` is
 saved and `LSC_URI_PRIMARY` is saved or explicitly declined. The first boot
@@ -236,7 +238,12 @@ itself, and they hold for every integration.
   such window. On the drop-ins: `resumePaymentHash`, fed from `onState`, on
   `<Checkout>`; the `resume-payment-hash` attribute, fed from the
   `openreceive-state` event (`event.detail.state.payment_hash`), on
-  `<openreceive-checkout>`. https://openreceive.org/guides/swap-refunds.md
+  `<openreceive-checkout>`.
+  That visit can come hours later, and `authorize` must still know the payer:
+  a session that expired in between answers 403 and strands the deposit. On a
+  guest shop, tie the order to a long-lived signed cookie, or put a secret
+  per-order token in its URL that your page trades for that cookie.
+  https://openreceive.org/guides/swap-refunds.md
 - Show the payer WHAT THEY ARE BUYING. Return an optional `description` beside
   the price from `amountFor` and both drop-ins render it above the amount.
   Without it the checkout is a QR and "$1.00" with no sign of what the dollar
@@ -286,6 +293,13 @@ products, and you do not join them.
   expired invoice does not cancel the order; a later checkout may mint another
   attempt. The library refuses a new checkout under a reference that already
   settled (409).
+- **A paid order's page says it is paid and shows no checkout.** Nothing is left
+  to pay, and a checkout cannot start a new payment for a paid order. Mount the
+  checkout only while the order is unpaid. When it settles on the page, update
+  the page's status line from `onSettled` on `<Checkout>`, or the
+  `openreceive-settled` event on `<openreceive-checkout>`: `onPaid` has already
+  marked the order paid. Keep that checkout mounted, because it is the payer's
+  receipt.
 - **Pass this app's `db` handle.** Do not add a Prisma/Drizzle relation from
   Order to `openreceive_payments`, and do not implement `PaymentRepository`
   unless no supported handle can reach this database. `reference` is not unique
@@ -387,6 +401,7 @@ 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 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/sveltekit-recipe.md, https://openreceive.org/guides/nuxt-recipe.md, https://openreceive.org/guides/astro-recipe.md and https://openreceive.org/guides/react-router-recipe.md — the same handler as a SvelteKit, Nuxt, Astro or React Router route, if this app is one of those
 - https://openreceive.org/guides.md — the index, if what you need is not above
 
 Questions, or a problem with the library itself:

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

@@ -3,7 +3,7 @@ This is the full file; follow it from Step 0.
 # OpenReceive agent directions (PHP)
 
 ```sh
-# READ THIS FIRST: this file is 41 KB and a summary drops required steps. Download it whole:
+# READ THIS FIRST: this file is 42 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.
 ```
@@ -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.25.
+These directions describe OpenReceive 0.4.26.
 
 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
@@ -124,6 +124,8 @@ you store it. Ask one question per message.
    front controller before `Service::fromEnvironment()`. When the app is started
    with Docker Compose, give the service `env_file: .env`. Restart PHP-FPM or
    the server after writing the file.
+   Under Compose, recreate the container with `docker compose up -d`:
+   `docker compose restart` keeps its old environment.
 
 Do not invent placeholder URIs. Start the quickstart only once `NWC_URI` is
 saved and `LSC_URI_PRIMARY` is saved or explicitly declined. The first boot
@@ -246,6 +248,10 @@ itself, and they hold for every integration.
   `payment_hash` and reopen the attempt with `POST /swaps/status`, which has no
   such window. On the element: the `resume-payment-hash` attribute, fed from
   the `openreceive-state` event (`event.detail.state.payment_hash`).
+  That visit can come hours later, and `authorize` must still know the payer:
+  a session that expired in between answers 403 and strands the deposit. On a
+  guest shop, tie the order to a long-lived signed cookie, or put a secret
+  per-order token in its URL that your page trades for that cookie.
   https://openreceive.org/guides/swap-refunds.md
 - Show the payer WHAT THEY ARE BUYING. Return an optional `description` beside
   the price from `amountFor` and the drop-in renders it above the amount.
@@ -263,10 +269,11 @@ itself, and they hold for every integration.
   array keys, and the browser packages' TypeScript APIs are camelCase.
 - Money is integers or decimal strings — never binary floats. `amountFor`
   returns `'value' => '12.00'`, a string; never `12.00`.
-- PHP starts every request from nothing. The engine is built for that — the
-  settlement gate is a row in `openreceive_meta`, not process memory — so do
-  not add a cache, a static, or an APCu entry to "remember" the wallet or a
-  reconcile timer between requests.
+- PHP starts every request from nothing. The engine is built for that: the
+  settlement gate is a row in `openreceive_meta`, and under a web server
+  `Service::fromEnvironment()` keeps the wallet's info and the market data in
+  a private temp directory. So do not add a cache, a static, or an APCu entry
+  to "remember" the wallet or a reconcile timer between requests.
 
 ## Your tables, not ours
 
@@ -298,6 +305,12 @@ not replace your orders, users, or products, and you do not join them.
   expired invoice does not cancel the order; a later checkout may mint another
   attempt. The engine refuses a new checkout under a reference that already
   settled (409).
+- **A paid order's page says it is paid and shows no checkout.** Nothing is left
+  to pay, and a checkout cannot start a new payment for a paid order. Mount the
+  checkout only while the order is unpaid. When it settles on the page, update
+  the page's status line from the `openreceive-settled` event on
+  `<openreceive-checkout>`: `onPaid` has already marked the order paid. Keep
+  that checkout mounted, because it is the payer's receipt.
 - **Pass this app's PDO.** `new SqlPaymentRepository(new PdoConnection($pdo))`
   over the connection the app already opens; do not implement
   `PaymentRepository` unless no PDO can reach this database. `reference` is not
@@ -587,8 +600,20 @@ if (str_starts_with($path, '/openreceive')) {
 
 `Service::fromEnvironment()` builds the wallet client from `NWC_URI` and runs
 the receive-only preflight. A missing, invalid or spend-capable code throws
-before any route is served. PHP starts every request from nothing, so that
-check runs on every request that reaches the engine.
+before any route is served.
+
+PHP starts every request from nothing. Without a cache, every checkout route
+would ask the wallet for its info event again and fetch the BTC price and the
+swap provider's currencies and rates again, which costs seconds per click.
+Under a web server, `fromEnvironment()` keeps them in a directory under the
+system temp dir that only the PHP user can open
+(`OpenReceive\Support\FileSharedCache`). The wallet's info is kept for 10
+minutes. A new code gets a new directory, so it is always checked live.
+Command-line runs, such as `bin/doctor` and the notifications worker, always
+ask the wallet. No secret goes in the cache: codes, payments and swap data
+stay out of it. If your app already runs a cache, pass it as `sharedCache:`
+([Service](https://openreceive.org/guides/api-reference.md#openreceiveserverservice)); `sharedCache: false`
+turns caching off.
 
 The settlement gate the engine relies on lives in `openreceive_meta`, not in
 memory. That is why a fleet of PHP-FPM workers shares one wallet-scan budget,

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

@@ -3,7 +3,7 @@ This is the full file; follow it from Step 0.
 # OpenReceive agent directions (Rails)
 
 ```sh
-# READ THIS FIRST: this file is 42 KB and a summary drops required steps. Download it whole:
+# READ THIS FIRST: this file is 43 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.
 ```
@@ -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.25.
+These directions describe OpenReceive 0.4.26.
 
 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
@@ -122,6 +122,8 @@ you store it. Ask one question per message.
    add `dotenv-rails` to the Gemfile. When it is started with Docker Compose,
    give the service `env_file: .env`. Restart the server after writing the
    file; the values are read at boot.
+   Under Compose, recreate the container with `docker compose up -d`:
+   `docker compose restart` keeps its old environment.
 
 Do not invent placeholder URIs. Start the quickstart only once `NWC_URI` is
 saved and `LSC_URI_PRIMARY` is saved or explicitly declined. The first boot
@@ -237,7 +239,12 @@ itself, and they hold for every integration.
   such window. On the drop-ins: `resumePaymentHash`, fed from `onState`, on
   `<Checkout>`; the `resume-payment-hash` attribute, fed from the
   `openreceive-state` event (`event.detail.state.payment_hash`), on
-  `<openreceive-checkout>`. https://openreceive.org/guides/swap-refunds.md
+  `<openreceive-checkout>`.
+  That visit can come hours later, and `authorize` must still know the payer:
+  a session that expired in between answers 403 and strands the deposit. On a
+  guest shop, tie the order to a long-lived signed cookie, or put a secret
+  per-order token in its URL that your page trades for that cookie.
+  https://openreceive.org/guides/swap-refunds.md
 - Show the payer WHAT THEY ARE BUYING. Return an optional `description` beside
   the price from `config.amount_for` and both drop-ins render it above the
   amount. Without it the checkout is a QR and "$1.00" with no sign of what the
@@ -282,6 +289,12 @@ not replace your orders, users, or products, and you do not join them.
   expired invoice does not cancel the order; a later checkout may mint another
   attempt. The engine refuses a new checkout under a reference that already
   settled (409).
+- **A paid order's page says it is paid and shows no checkout.** Nothing is left
+  to pay, and a checkout cannot start a new payment for a paid order. Mount the
+  checkout only while the order is unpaid. When it settles on the page, update
+  the page's status line from the `openreceive-settled` event on
+  `<openreceive-checkout>`: `on_paid` has already marked the order paid. Keep
+  that checkout mounted, because it is the payer's receipt.
 - **Do not associate `OpenReceivePayment`.** No `has_many`, no `belongs_to`, no
   foreign key either direction. `reference` is not unique (many attempts per
   order). Fulfillment is a guarded transition on YOUR order row inside

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

@@ -17,7 +17,7 @@ curl -fsSL https://openreceive.org/agent-directions/woocommerce/full.md
 - 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.25.
+These directions describe OpenReceive 0.4.26.
 
 Install and configure the OpenReceive payment gateway in the WooCommerce store
 you are working in. Preserve its theme, checkout, customer accounts, order
@@ -95,7 +95,7 @@ is saved or the user said "Bitcoin only". Never invent a placeholder code.
 Install this release from the WordPress.org plugin directory:
 
 ```sh
-wp plugin install openreceive --version=0.4.25 --activate
+wp plugin install openreceive --version=0.4.26 --activate
 ```
 
 If that fails because WordPress.org does not have this version yet, install
@@ -103,7 +103,7 @@ the ZIP attached to the same GitHub 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.25/openreceive-wordpress-0.4.25.zip --activate
+wp plugin install https://github.com/OpenReceive/openreceive/releases/download/v0.4.26/openreceive-wordpress-0.4.26.zip --activate
 ```
 
 It needs WooCommerce active, and PHP 8.2+ with GMP and sodium in BOTH the web
@@ -252,7 +252,7 @@ database or application.
 
 Each GitHub release also attaches the same plugin as a ZIP, for a site that
 cannot reach WordPress.org or when WordPress.org does not list a release yet.
-Download [openreceive-wordpress-0.4.25.zip](https://github.com/OpenReceive/openreceive/releases/download/v0.4.25/openreceive-wordpress-0.4.25.zip)
+Download [openreceive-wordpress-0.4.26.zip](https://github.com/OpenReceive/openreceive/releases/download/v0.4.26/openreceive-wordpress-0.4.26.zip)
 and install it through **Plugins → Add New → Upload Plugin**. 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
@@ -262,7 +262,7 @@ GMP/sodium, Composer and WP-CLI:
 ```sh
 git clone https://github.com/OpenReceive/openreceive.git
 cd openreceive
-git checkout v0.4.25
+git checkout v0.4.26
 npm ci
 npm run build:packages
 composer install --working-dir=packages/php/wordpress

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openreceive
 version: !ruby/object:Gem::Version
-  version: 0.4.25
+  version: 0.4.26
 platform: ruby
 authors:
 - OpenReceive