openreceive-rails 0.4.10 → 0.4.13

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Django)
 
-These directions describe OpenReceive 0.4.10.
+These directions describe OpenReceive 0.4.13.
 
 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
@@ -37,78 +37,101 @@ 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 the
 payer send USDT, USDC, ETH or SOL instead, converted into that same
-Lightning payment. You supply those credentials and three hooks — `authorize`,
+Lightning payment. Step 0 collects those credentials from the user; you write three hooks — `authorize`,
 `amount_for`, `on_paid` on a `Host` class named in `settings.OPENRECEIVE`;
 OpenReceive supplies invoices, polling, settlement and the checkout UI. It never
 owns orders, users, prices, or fulfillment.
 
-## Step 0 — check the environment before you write code
-
-Do this before installing the package or editing files.
-
-1. Look for `NWC_URI` in this app's server environment — `.env`, the process
-   env, the deploy config, whatever this app already uses (Django itself loads
-   no `.env`; `django-environ` or the process manager does). If the app runs in
-   a container the value is in none of those: ask the running process
-   (`docker exec <container> printenv NWC_URI`), because finding the NAME in a
-   compose file proves nothing about the value. Never print or echo the value
-   itself; only report whether it is set. Check for `LSC_URI_PRIMARY` in the
-   same pass.
-
-   If OpenReceive is already installed here, `manage.py openreceive_doctor`
-   answers this whole step in one command — every credential as present or
-   missing, the wallet preflight, the two tables, the mount, and whether a hook
-   is still on a placeholder. It never prints a value; `--offline` skips the
-   relay probe.
-2. If BOTH are already set — the common case in an existing app — say so and go
-   straight to the quickstart. Steps 3 and 4 are for an environment that is
-   missing one; do not stop to ask about altcoins that are already configured.
-   If only `NWC_URI` is set, Bitcoin already works: continue, and raise the
-   altcoin question at step 4 rather than blocking on it.
-3. If `NWC_URI` is missing or empty, stop and tell the user exactly what to
-   create:
-
-   > OpenReceive cannot issue an invoice without a receive-only NWC code. Get
-   > one at https://openreceive.org/get_a_nwc_code_to_receive_payments, then
-   > put `NWC_URI=<the code>` in this app's server environment — for most apps
-   > that is a `.env` file the process manager loads, or an exported variable —
-   > and tell me when it's set.
-
-   Wait for the user before wiring OpenReceive; do not invent a placeholder
-   value. Waiting is not idleness: you may write `.env.example` with the
-   variable NAMES only (`NWC_URI=`, `LSC_URI_PRIMARY=`) so the merchant has a
-   file to copy, and keep building the parts of the host that do not touch
-   OpenReceive — the order model, the cart, the views. The stop guards the
-   credential, not the rest of the app.
-4. If `LSC_URI_PRIMARY` was not already set, ask the user: "Do you want to
-   accept altcoins and stablecoins (USDT, USDC, ETH, SOL) as well as
-   Bitcoin?"
-
-   - Yes → send them to https://openreceive.org/set_up_swap_provider for a
-     swap-provider (LSC) code, to set as `LSC_URI_PRIMARY` in the same server
-     environment. Do NOT wait for it: no application code reads the value, so
-     the integration is identical with or without it — the engine picks it up
-     from the environment and swaps switch on. What a yes DOES change is the
-     refund route back (the swap non-negotiable below): build it as part of
-     this integration, not when the code arrives.
-   - No → skip it. Bitcoin over Lightning works with `NWC_URI` alone, and you
-     can add a swap provider later without changing application code.
-5. Check the environment again and confirm `NWC_URI` is present.
-   `LSC_URI_PRIMARY` may land later; swaps stay off until it does, and no code
-   changes when it arrives.
-6. If OpenReceive is ALREADY installed here, check the installed versions of
-   `openreceive` (`pip show openreceive`) and `@openreceive/browser` (or the
-   `MANIFEST.json` beside the packaged static checkout) against the release
-   named at the top of this file. The headless display models below do not
-   exist in older versions, and the first tile click throws with nothing saying
-   why. Upgrade first — and if this app runs in containers, rebuild the images:
-   the package is baked into the image, so an in-place `pip install -U` is
-   undone by the next `compose up`.
-7. Before the deploy that turns this on, run
-   `OPENRECEIVE_PREFLIGHT=1 manage.py check --deploy`: it runs the receive-only
-   wallet preflight as a system check (`openreceive.E002` on a missing, dead or
-   spend-capable code), because the wallet client is built lazily on the first
-   request rather than in `AppConfig.ready()`.
+## Step 0 — ask for the two codes, one question at a time
+
+Before anything else, look at one file: the project's `.env`, if it exists.
+Read it only far enough to see whether `NWC_URI` and `LSC_URI_PRIMARY` are
+there and non-empty, and never print the values. A code that is already
+set is not asked for again; if both are set, skip to step 5
+(making the server load the file), then the quickstart.
+
+Otherwise your next action is a question to the user. Do not install the package,
+edit the app, write `.env.example`, or search anywhere else before asking
+it. Do not read deploy config (compose files, platform secrets), `settings.py` secrets, Docker containers, or process environments, and never run
+`printenv`. A new shop has neither code yet: hunting for one burns the turn and
+can leak other secrets into the transcript.
+
+Two server-only URIs are needed before the quickstart:
+
+- `NWC_URI` — a receive-only Nostr Wallet Connect code,
+  `nostr+walletconnect://…`. Required for Bitcoin.
+- `LSC_URI_PRIMARY` — a Lightning Swap Connect URI,
+  `lightning+swapconnect://…`. Required for USDT, USDC, ETH and SOL. Skip it
+  only when the user says they want Bitcoin alone.
+
+The user never edits an environment file. They paste each code into the chat;
+you store it. Ask one question per message.
+
+1. **First message — the NWC code, and nothing else.** Ask for it and walk them
+   through getting it:
+
+   > 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.
+
+   Do not mention `.env`, exports, or "tell me when it's set".
+2. **When they paste it.** If it does not start with `nostr+walletconnect://`,
+   ask them to copy the receive-only code again. Otherwise write
+   `NWC_URI=<paste>` into the project's `.env`, creating the file if needed.
+   Make sure `.gitignore` covers `.env` (and `.dockerignore`, if the app has
+   one). Never echo the value, commit it, or put it in client code. Reply only
+   that it is saved, then ask the next question.
+3. **Second message — swaps.** If the user already asked for stablecoins or
+   altcoins, skip the yes/no and go straight to the walkthrough. Otherwise ask
+   whether payers should also be able to pay with USDT, USDC, ETH or SOL. 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. Otherwise add
+   `LSC_URI_PRIMARY=<paste>` to the same `.env`, without echoing it. Swaps
+   are now on, so build the refund route back (the swap non-negotiable below) as
+   part of this integration. If they chose Bitcoin only, leave
+   `LSC_URI_PRIMARY` unset and skip that route.
+5. **Make the server load the file — yourself.** Django does not
+   read `.env` on its own. If the app already uses `django-environ`, make sure
+   it reads this file; otherwise add it and call `environ.Env.read_env()` in
+   `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.
+
+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
+runs the receive-only preflight: if it reports spend methods such as
+`pay_invoice`, remove `NWC_URI` from `.env` and ask for a receive-only code
+again. Never set the spend-capable override to get past it.
+
+Before the deploy that turns this on, run
+`OPENRECEIVE_PREFLIGHT=1 manage.py check --deploy`: it runs the receive-only
+wallet preflight as a system check (`openreceive.E002` on a missing, dead or
+spend-capable code), because the wallet client is built lazily on the first
+request rather than in `AppConfig.ready()`.
+
+### Upgrading an existing install
+
+This is not the opening move of a new integration. When OpenReceive is ALREADY
+installed here, `manage.py openreceive_doctor` reports every credential as
+present or missing (never the value), the wallet preflight, the two tables, the
+mount, and any hook still on a placeholder; `--offline` skips the relay probe.
+Check the installed `openreceive` (`pip show openreceive`) and
+`@openreceive/browser` (or the `MANIFEST.json` beside the packaged static
+checkout) against the release named at the top of this file: the headless
+display models below do not exist in older versions, and the first tile click
+throws with nothing saying why. Upgrade first — and if this app runs in
+containers, rebuild the images: the package is baked into the image, so an
+in-place `pip install -U` is undone by the next `compose up`.
 
 Only then start the quickstart.
 
@@ -130,7 +153,7 @@ itself, and they hold for every integration.
   a placeholder that allows everything (`manage.py check` warns
   `openreceive.W002` while it is set) — replace it with this app's real
   ownership check, same as `on_paid`.
-- `on_paid` must be idempotent. It runs once per `reference` — your order
+- `on_paid` must be idempotent. Its database fulfillment commits once per `reference` — your order
   id, one per thing you fulfill, created before checkout, kept across retries,
   never reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -307,6 +330,8 @@ enough; drop the `.md` for the same page a person would read.
 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
@@ -324,11 +349,11 @@ Install the Python package with the Django extra:
 pip install "openreceive[django]"
 ```
 
-That is the whole install: `openreceive[django]` brings Django; the wallet
-client (websockets, coincurve, cryptography), the HTTP engine and the
-`openreceive` CLI come with the base package. Use `uv` or a virtualenv on
-Python 3.10 or newer; a system Python 3.9 cannot install it. Hosts that bring
-their own NWC client set `OPENRECEIVE["SERVICE"]` instead (below).
+That is the whole install. `openreceive[django]` brings Django. The base
+package brings the wallet client (websockets, coincurve, cryptography), the
+HTTP engine and the `openreceive` CLI. Use `uv` or a virtualenv on Python 3.10
+or newer. A system Python 3.9 cannot install it. If your app brings its own NWC
+client, set `OPENRECEIVE["SERVICE"]` instead (see below).
 
 Then add the app, point it at a host class, and mount the routes:
 
@@ -351,41 +376,43 @@ from django.urls import include, path
 urlpatterns += [path("openreceive/", include("openreceive.django.urls"))]
 ```
 
-`HOST` is a dotted path, not a callable — cache-safe, `manage.py check`
-friendly, the `AUTH_USER_MODEL` idiom. Then run:
+`HOST` is a dotted path, not a callable. That keeps it cache-safe and friendly
+to `manage.py check`, like the `AUTH_USER_MODEL` setting. Then run:
 
 ```sh
 manage.py openreceive_install shop      # writes shop/openreceive_host.py, prints the lines above
 manage.py migrate                        # creates openreceive_payments and openreceive_meta
 ```
 
-`openreceive_install` writes one file — `<app>/openreceive_host.py`, the
-three hooks with the generated placeholders wired and the exactly-once
-fulfillment note as comments — and prints the settings and urls lines to add.
-It never edits `settings.py` or `urls.py`. The migration ships inside the
-`openreceive.django` app, so `manage.py migrate` applies it alongside your
-own; it adapts to the configured database backend.
-
-The `OpenReceivePayment` model is engine-owned — no model file is generated,
-and the migration adds only the engine's two tables to your database. The
-engine owns the table's commit locking, write-once settlement, and
-reconciliation state machine. `reference` is indexed but not unique (a
-reference may have many historical attempts); `payment_hash` is globally
-unique. On SQLite give the database
-`OPTIONS = {"transaction_mode": "IMMEDIATE"}` (Django ≥ 5.1) so two
-concurrent commits for one order queue on the busy timeout instead of failing
-with "database is locked" ([Payment storage](https://openreceive.org/guides/storage.md)).
+`openreceive_install` writes one file, `<app>/openreceive_host.py`. It holds
+the three hooks with the generated placeholders wired in, and the exactly-once
+fulfillment note as comments. The command then prints the settings and urls
+lines to add. It never edits `settings.py` or `urls.py`. The migration ships
+inside the `openreceive.django` app, so `manage.py migrate` applies it
+alongside your own. It adapts to the configured database backend.
+
+The engine owns the `OpenReceivePayment` model, so no model file is generated.
+The migration adds only the engine's two tables to your database. The engine
+owns the table's commit locking, write-once settlement, and reconciliation
+state machine. `reference` is indexed but not unique, because one reference may
+have many historical attempts. `payment_hash` is globally unique.
+
+On SQLite, give the database `OPTIONS = {"transaction_mode": "IMMEDIATE"}`
+(Django ≥ 5.1). Then two concurrent commits for one order wait on the busy
+timeout instead of failing with "database is locked"
+([Payment storage](https://openreceive.org/guides/storage.md)).
 
 #### Fulfill exactly once
 
 Within OpenReceive's own settlement paths, `on_paid` runs at most once per
-reference: a second payment to a second invoice is recorded with
-`status_reason = "duplicate_settlement"` and never fulfills again.
+reference. If a second invoice for the same reference is paid, OpenReceive
+records that payment with `status_reason = "duplicate_settlement"` and does
+not fulfill again.
 
-The one thing you own: **if anything other than OpenReceive can also fulfill
-an order** — an admin action, a second payment processor, a replayed job —
-those paths race each other, and `on_paid` must be idempotent. The generated
-host module spells this out and shows the guarded transition:
+One case is yours to handle. **If anything other than OpenReceive can also
+fulfill an order**, such as an admin action, a second payment processor, or a
+replayed job, those paths race each other. Then `on_paid` must be idempotent.
+The generated host module explains this and shows the guarded transition:
 
 ```python
 def on_paid(self, settlement: PaymentSettlement) -> None:
@@ -400,19 +427,20 @@ def on_paid(self, settlement: PaymentSettlement) -> None:
     FulfillOrder.run(settlement.reference, payment_hash=settlement.payment_hash)
 ```
 
-Delivery is at-least-once: `on_paid` runs inside the settlement transaction
-(the engine wraps it in `transaction.atomic()`), and an exception rolls it back
-for the next pass to retry. Keep it to database writes on the order — an email
-or webhook sent from here would survive the rollback and go out again. The
-`state="paid"` transition above is the flag; drain it after commit from
-`after_paid`, the optional fourth method, which runs once after the settlement
-transaction committed, or from your own job.
-
-**`QuerySet.update()` fires no signals and calls no `save()`.** That is the
-point — it is one conditional `UPDATE`, so the claim is atomic and there is no
-model code between the check and the write. It also means no `post_save`
-handler runs, which is fine for a job draining the flag and useless for a
-model whose transition lives in `save()`. If your model owns the transition
+Delivery is at-least-once. `on_paid` runs inside the settlement transaction,
+which the engine wraps in `transaction.atomic()`. If it raises, the transaction
+rolls back and the next pass retries. So keep `on_paid` to database writes on
+the order. An email or webhook sent from here would survive the rollback and go
+out again. The `state="paid"` transition above is the flag. Drain it after
+commit, either from your own job or from `after_paid`. `after_paid` is the
+optional fourth method. It runs once, after the settlement transaction
+commits.
+
+**`QuerySet.update()` fires no signals and calls no `save()`.** That is
+intended. It runs one conditional `UPDATE`, so the claim is atomic and no model
+code runs between the check and the write. It also means no `post_save`
+handler runs. That is fine for a job that drains the flag. It does not work for
+a model whose transition lives in `save()`. If your model owns the transition
 through signals or an overridden `save()`, take a row lock for the duration
 instead:
 
@@ -426,27 +454,30 @@ def on_paid(self, settlement: PaymentSettlement) -> None:
     order.save()  # signals fire
 ```
 
-**Unlocking a download works the same way.** If what the payer bought is a
-file, do not unlock it in the browser: gate the download view on the paid
-order row —
-`get_object_or_404(Order, pk=reference, user=request.user, state="paid")` —
-and serve the file only then. The `state="paid"` written above is the unlock;
-the client never decides an order was fulfilled, it re-reads the row. Buy a
-Button's `download` view is this in twenty lines.
-
-Both shapes are idempotent, and both are correct. They differ only in whether
-your model layer gets to run: `update()` skips it and is the right default; the
-row lock (a no-op on SQLite, where the transaction itself serializes writers)
-holds the row for the duration of the method and is what you want when the
-transition has to go through your model. The generated fulfillment note says
-the same thing — if your fulfillment is a read-modify-write that cannot be
-expressed as one conditional `UPDATE`, take the lock.
-
-A runnable illustration of this boundary — not a template to copy models from —
-is Buy a Button
-(`examples/buttons/server/django`).
-It has products, visitors, and orders, with the three hooks as the only bridge.
-Map that shape onto the models in THIS app.
+**Unlocking a download works the same way.** If the payer bought a file, do not
+unlock it in the browser. Gate the download view on the paid order row, and
+serve the file only if that row exists:
+`get_object_or_404(Order, pk=reference, user=request.user, state="paid")`. The
+`state="paid"` written above is the unlock. The client never decides that an
+order was fulfilled. It re-reads the row. Buy a Button's `download` view does
+this in twenty lines.
+
+Both shapes are idempotent and correct. They differ only in whether your model
+layer runs:
+
+- `update()` skips the model layer. It is the right default.
+- The row lock holds the row for the duration of the method. Use it when the
+  transition has to go through your model. On SQLite the lock does nothing,
+  because the transaction itself already lets only one writer run at a time.
+
+The generated fulfillment note says the same thing. If your fulfillment is a
+read-modify-write that one conditional `UPDATE` cannot express, take the lock.
+
+Buy a Button
+(`examples/buttons/server/django`)
+is a runnable illustration of this boundary. It is not a template to copy
+models from. It has products, visitors, and orders, and the three hooks are the
+only bridge. Map that shape onto the models in THIS app.
 
 ### Add wallet credentials
 
@@ -459,30 +490,36 @@ LSC_URI_BACKUP=
 ```
 
 1. Get a receive-only NWC code from a compatible wallet
-   ([get one here](https://openreceive.org/get_a_nwc_code_to_receive_payments))
-   → `NWC_URI`.
-2. Optionally set up a [swap provider](https://openreceive.org/set_up_swap_provider)
-   → `LSC_URI_PRIMARY` (and `LSC_URI_BACKUP` if you have one).
-
-Never put these values in browser code. Your application refuses to start if
-the NWC code also advertises spend methods such as `pay_invoice`; mint a
-receive-only code ([Security](https://openreceive.org/guides/security.md)).
-
-OpenReceive reads `os.environ`; Django does not load a `.env` file on its own.
-`django-environ`, an exported shell environment, or your production secret
-manager has to put the values there first. The explicit override for a
-spend-capable code is `OPENRECEIVE_ALLOW_SPEND_CAPABLE_NWC=true`.
+   ([get one here](https://openreceive.org/get_a_nwc_code_to_receive_payments)).
+   Put it in `NWC_URI`.
+2. Optional: set up a [swap provider](https://openreceive.org/set_up_swap_provider).
+   Put its connection string in `LSC_URI_PRIMARY`, and a second one in
+   `LSC_URI_BACKUP` if you have one.
+
+Never put these values in browser code. Your app refuses to start if the NWC
+code also advertises spend methods such as `pay_invoice`. Create a
+receive-only code instead ([Security](https://openreceive.org/guides/security.md)).
+
+OpenReceive reads `os.environ`. Django does not load a `.env` file on its own,
+so something has to put the values there first: `django-environ`, an exported
+shell environment, or your production secret manager. To allow a
+spend-capable code explicitly, set `OPENRECEIVE_ALLOW_SPEND_CAPABLE_NWC=true`.
 → [Environment variables](https://openreceive.org/guides/environment-variables.md).
 
 ### Configure the host hooks
 
 The host class needs three things: authorization, the trusted price, and
-fulfillment. All three receive the `reference` — a string you choose, and the
-fulfillment identity: your order id, one per thing you fulfill, created before
-checkout, kept across retries, never reused. OpenReceive never looks inside
-it, but `on_paid` runs once per reference, a new checkout under a reference
-that already settled is refused with 409, and a fresh id per page load lets
-one order be paid twice.
+fulfillment. All three receive the `reference`. This is a string you choose,
+and it is the fulfillment identity. Use your order id:
+
+- one per thing you fulfill,
+- created before checkout,
+- kept across retries,
+- never reused.
+
+OpenReceive never looks inside it. But `on_paid` commits fulfillment once per
+reference, and a new checkout under a reference that already settled is
+refused with 409. A fresh id per page load would let one order be paid twice.
 
 ```python
 # shop/openreceive_host.py — generated by `manage.py openreceive_install shop`, then filled in.
@@ -495,7 +532,6 @@ from shop.models import Order  # YOUR model — it could be named anything. Open
                                # never sees it or touches its table; these hooks are the
                                # only bridge between the engine and your data.
 
-
 class Host:
     # Your policy, called before every checkout/payment/swap request. `context`
     # has three attributes:
@@ -539,52 +575,59 @@ class Host:
         )
 ```
 
-`authorize` receives the Django request that carried the payer's call, so
-`request.user`, `request.session` and cookies are all there — keep the
-project's authentication and its `User`; OpenReceive mints no tokens of its
-own. The engine reads nothing else from the request: whatever your middleware
-stack put on it is what your policy sees.
-
-CSRF stays on. `CsrfViewMiddleware` is the host's, and the mounted routes run
-its check like any other view — a failed check answers with the shared
-`403 FORBIDDEN` JSON error instead of the HTML failure page. Render
-`<meta name="csrf-token" content="{{ csrf_token }}">` in the template that
-shows the checkout, and give the element `csrf-header="X-CSRFToken"` (the
-header Django reads; the default is Rails' `X-CSRF-Token`) — the checkout
-client sends the token from that tag on every request. A view that renders a
-page with no form still needs `{% csrf_token %}` or `ensure_csrf_cookie` for
-the cookie to exist; `{{ csrf_token }}` in the meta tag does that on its own.
-
-The generated host module ships `on_paid = staticmethod(LOGGING_ON_PAID)` — a
-placeholder that only logs the settlement and fulfills nothing. Replace it
-with your real fulfillment (as above); `manage.py check` warns
-(`openreceive.W001`) at every boot while the placeholder is still configured,
-because orders would otherwise be recorded as settled without ever being
-fulfilled. The same applies to `authorize = staticmethod(ALLOW_ALL_AUTHORIZE)`,
-the generated allow-all placeholder: it treats possession of the reference as
-authorization, which is safe only while references are unguessable, and the
-check warns (`openreceive.W002`) until you replace it with your own ownership
-check (as above). Replace both, not just `on_paid`. A `HOST` that is missing
-or does not import is `openreceive.E001`.
-
-The amount always comes from your own order record; payer-supplied amounts are
-rejected. Hosts that bring their own NWC client, price feed or swap providers
+`authorize` receives the Django request that carried the payer's call. So
+`request.user`, `request.session` and cookies are all available. Keep your
+project's authentication and its `User`. OpenReceive mints no tokens of its
+own. The engine reads nothing else from the request. Your policy sees whatever
+your middleware stack put on it.
+
+CSRF stays on. `CsrfViewMiddleware` is yours, and the mounted routes run its
+check like any other view. A failed check returns the shared `403 FORBIDDEN`
+JSON error instead of the HTML failure page. To make the check pass:
+
+- Render `<meta name="csrf-token" content="{{ csrf_token }}">` in the template
+  that shows the checkout.
+- Give the element `csrf-header="X-CSRFToken"`. That is the header Django
+  reads. The default is Rails' `X-CSRF-Token`.
+
+The checkout client then sends the token from that tag on every request. A view
+that renders a page with no form normally needs `{% csrf_token %}` or
+`ensure_csrf_cookie` for the cookie to exist. `{{ csrf_token }}` in the meta
+tag does that on its own.
+
+The generated host module ships two placeholders. Replace both, not just
+`on_paid`:
+
+- `on_paid = staticmethod(LOGGING_ON_PAID)` only logs the settlement and
+  fulfills nothing. Replace it with your real fulfillment (as above). Until you
+  do, orders would be recorded as settled without ever being fulfilled, so
+  `manage.py check` warns (`openreceive.W001`) at every boot.
+- `authorize = staticmethod(ALLOW_ALL_AUTHORIZE)` allows everything. It treats
+  possession of the reference as authorization, which is safe only while
+  references are unguessable. The check warns (`openreceive.W002`) until you
+  replace it with your own ownership check (as above).
+
+A `HOST` that is missing or does not import is `openreceive.E001`.
+
+The amount always comes from your own order record. Payer-supplied amounts are
+rejected. If your app brings its own NWC client, price feed or swap providers,
 set `OPENRECEIVE["SERVICE"]` to the dotted path of a callable
-`(env) -> openreceive.server.Service`; everyone else leaves it out.
-
-For public web shops, opt into the per-IP invoice cap with
-`"RATE_LIMITING": True` (or `{"limit_per_hour": …, "limit_per_day": …}`);
-leave it off (the default) when many payers share one IP. It counts
-`REMOTE_ADDR` after your own proxy handling, so behind a reverse proxy put a
-trusted-proxy middleware first or the cap counts the proxy.
+`(env) -> openreceive.server.Service`. Everyone else leaves it out.
+
+For public web shops, turn on the per-IP invoice cap with
+`"RATE_LIMITING": True` (or `{"limit_per_hour": …, "limit_per_day": …}`).
+Leave it off (the default) when many payers share one IP. The cap counts
+`REMOTE_ADDR` after your own proxy handling. Behind a reverse proxy, put a
+trusted-proxy middleware first, or the cap counts the proxy instead of the
+payer.
 → [Rate limiting](https://openreceive.org/guides/rate-limiting.md)
 
-The wallet client — and its receive-only preflight — is built lazily on the
-first request, never in `AppConfig.ready()`: that method runs for `migrate`,
-`collectstatic` and shells too, and a relay probe there would break them on a
-box with no relay access. To fail a deploy on a bad `NWC_URI` instead of
-surfacing customer-facing 500s, run the preflight as a system check in your
-deploy pipeline:
+The wallet client, and its receive-only preflight, is built lazily on the first
+request. It is never built in `AppConfig.ready()`. That method also runs for
+`migrate`, `collectstatic` and shells, and a relay probe there would break them
+on a machine with no relay access. To make a bad `NWC_URI` fail the deploy
+instead of causing 500 errors for customers, run the preflight as a system check
+in your deploy pipeline:
 
 ```sh
 OPENRECEIVE_PREFLIGHT=1 manage.py check --deploy    # openreceive.E002 on a missing, dead or spend-capable code
@@ -593,16 +636,16 @@ manage.py openreceive_doctor                        # the same, for humans; neve
 
 ### Render the checkout
 
-Serve the compiled `styles.css` without Tailwind processing: import it from
-JavaScript (with a CSS-capable bundler) or use a plain `<link rel="stylesheet">`.
-Do not `@import` it into the host Tailwind entry. Its zero-specificity rules
-allow host styles to override checkout styles; scoping does not prevent that.
+Serve the compiled `styles.css` without Tailwind processing. Either import it
+from JavaScript (with a CSS-capable bundler) or use a plain
+`<link rel="stylesheet">`. Do not `@import` it into your Tailwind entry. Its
+rules have zero specificity, so your own styles can override checkout styles.
+Scoping does not prevent that.
 
-The app serves JSON checkout routes only — rendering is your template. Any
-OpenReceive frontend package works against the `/openreceive` mount; the
-smallest is the custom element, and the Python package carries its
-standalone build as static files, so a Django template needs no JavaScript
-bundler at all:
+The app serves JSON checkout routes only. Your template does the rendering. Any
+OpenReceive frontend package works against the `/openreceive` mount. The
+smallest is the custom element. The Python package carries its standalone
+build as static files, so a Django template needs no JavaScript bundler at all:
 
 ```django
 {# templates/orders/pay.html #}
@@ -617,34 +660,35 @@ bundler at all:
 ```
 
 `openreceive-checkout.js` registers the `<openreceive-checkout>` tag when it
-loads (one self-contained ES module, un-minified identifiers), and the
-stylesheet is scoped to what OpenReceive renders. `collectstatic` ships both with the rest of your
-static files; the package's `MANIFEST.json` names every file and its hash. The
-element creates the checkout for `reference`, then renders and polls itself
-(its default `prefix` is already `/openreceive`).
+loads. It is one self-contained ES module with un-minified identifiers. The
+stylesheet is scoped to what OpenReceive renders. `collectstatic` ships both
+with the rest of your static files. The package's `MANIFEST.json` names every
+file and its hash. The element creates the checkout for `reference`, then
+renders and polls itself. Its default `prefix` is already `/openreceive`.
 
 Everything the checkout draws ships inside the JavaScript: the payment-method
 icons, the wallet logos and the pay tutorials. There is no image file to copy
 or serve and no asset option to set. Deploy your normal JavaScript and CSS
 build output, including any generated JavaScript chunks. Bundlers with code
-splitting can defer tutorial screenshots until first open; single-file builds
-(including the standalone checkout) include them upfront. If your
-Content-Security-Policy has a strict `img-src`, allow `data:`
+splitting can load tutorial screenshots only when a tutorial is first opened.
+Single-file builds, including the standalone checkout, include them upfront. If
+your Content-Security-Policy has a strict `img-src`, allow `data:`
 ([Provider registry](https://openreceive.org/guides/provider-registry.md#assets)).
 
-Then open the checkout in a browser, confirm the payment-method icons and
+Then open the checkout in a browser. Confirm the payment-method icons and
 wallet logos render, and open a wallet's pay tutorial to check its screenshots.
-If an image is missing, inspect the console for CSP violations and the Network
+If an image is missing, check the console for CSP violations and the Network
 panel for failed JavaScript chunks. Allow `data:` in `img-src` and deploy the
 complete build output. Do not add image routes, copy package source images, or
 use registry `icon_path` / tutorial `path` keys as browser URLs.
 
-Hosts with a JavaScript bundler use the npm packages instead — the same
-element from `@openreceive/elements` (`defineElements()` once per page, then
-the tag above), or the matching React/Vue/Svelte/Angular wrapper with the
-`csrfHeader="X-CSRFToken"` prop, same defaults ([Frontend
-checkout](https://openreceive.org/guides/frontend-checkout.md)). Build a custom checkout only if this app
-cannot use a drop-in; then `@openreceive/browser/headless` is the API
+If your app has a JavaScript bundler, use the npm packages instead. Either use
+the same element from `@openreceive/elements` (call `defineElements()` once per
+page, then use the tag above), or use the matching React, Vue, Svelte, or
+Angular wrapper with the `csrfHeader="X-CSRFToken"` prop. Both have the same
+defaults ([Frontend checkout](https://openreceive.org/guides/frontend-checkout.md)). Build a custom checkout
+only if this app cannot use a drop-in. In that case
+`@openreceive/browser/headless` is the API
 ([Headless checkout](https://openreceive.org/guides/headless-checkout.md)).
 
 ### Reconciliation
@@ -660,35 +704,38 @@ load:
 manage.py openreceive_notifications
 ```
 
-It listens for NWC-02 `payment_received` notifications AND runs a periodic
-reconcile pass (`OPENRECEIVE_NOTIFICATIONS_RECONCILE_INTERVAL_SECONDS`, default
-15) in the same process — the safety net for notifications missed while it was
-down. One process total, not one per web instance.
+The worker listens for NWC-02 `payment_received` notifications. The same
+process also runs a periodic reconcile pass, every
+`OPENRECEIVE_NOTIFICATIONS_RECONCILE_INTERVAL_SECONDS` (default 15). That pass
+catches notifications missed while the worker was down. Run one process in
+total, not one per web instance.
 
-`manage.py openreceive_reconcile` is the one-shot primitive if you want to
-drive a pass yourself.
+To run a pass yourself, use the one-shot `manage.py openreceive_reconcile`.
 
 ### Swap secrets
 
-The Python engine recognizes `LSC_URI_PRIMARY` and `LSC_URI_BACKUP` using the
-shared [Lightning Swap Connect](https://openreceive.org/guides/lightning-swap-connect.md) vectors: setting
-either one auto-builds the matching provider, so an app that wants swaps only
+The Python engine recognizes `LSC_URI_PRIMARY` and `LSC_URI_BACKUP`, using the
+shared [Lightning Swap Connect](https://openreceive.org/guides/lightning-swap-connect.md) vectors. Setting
+either one auto-builds the matching provider. So an app that wants swaps only
 supplies the connection strings ([Environment
-variables](https://openreceive.org/guides/environment-variables.md)). `OPENRECEIVE["SERVICE"]` is the
-override knob — build the `Service` with your own providers, or an empty list
-to disable swaps.
+variables](https://openreceive.org/guides/environment-variables.md)). To override this, use
+`OPENRECEIVE["SERVICE"]`. Build the `Service` with your own providers, or with
+an empty list to disable swaps.
 
-One `openreceive_payments` row holds at most one provider order in its
-server-only `swap_data` column. The engine excludes `swap_data` from the
-model's `repr`, from the read-only admin it registers, and from every public
-dict. Do not serialize it, log it, or return it from your own API; it may
-contain a provider credential.
+One `openreceive_payments` row holds at most one provider order, in its
+server-only `swap_data` column. The engine leaves `swap_data` out of the
+model's `repr`, out of the read-only admin it registers, and out of every
+public dict. Do not serialize it, log it, or return it from your own API. It
+may contain a provider credential.
 
 **Setting either connection string commits you to refunds.** A swap deposit can
-arrive short or late, which leaves it `refund_required` at the provider with
-only your UI able to claim it — and the payer claims it on a second visit,
-after leaving your page for an address in another wallet. That needs a
-per-order URL your app serves, a route that restores the order behind it, and
-something that restores the ATTEMPT, since `/checkouts/prepare` returns none.
-[Swap refunds](https://openreceive.org/guides/swap-refunds.md) is the whole of it; read it before you set
+arrive short or late. The provider then marks it `refund_required`, and only
+your UI can claim it. The payer claims it on a second visit, after leaving your
+page to get an address in another wallet. That needs three things:
+
+- a per-order URL your app serves,
+- a route that restores the order behind it,
+- something that restores the ATTEMPT, since `/checkouts/prepare` returns none.
+
+[Swap refunds](https://openreceive.org/guides/swap-refunds.md) covers all of it. Read it before you set
 `LSC_URI_PRIMARY`.