openreceive-rails 0.4.10 → 0.4.13

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Next.js)
 
-These directions describe OpenReceive 0.4.10.
+These directions describe OpenReceive 0.4.13.
 
 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
@@ -34,64 +34,90 @@ 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`, `amountFor`,
+Lightning payment. Step 0 collects those credentials from the user; you write three hooks — `authorize`, `amountFor`,
 `onPaid`;
 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 packages or editing files.
-
-1. Look for `NWC_URI` in this app's server environment — `.env.local`, the
-   process env, the deploy config, whatever this app already uses. Next loads
-   `.env.local` itself: do not add `dotenv`, and never give a credential a
-   `NEXT_PUBLIC_` prefix, which inlines it into the browser bundle. 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.
-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 a Next
-   > app that is `.env.local` in the project root — 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 routes. 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 library 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/node` and `@openreceive/browser` 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.
+## Step 0 — ask for the two codes, one question at a time
+
+Before anything else, look at one file: the project's `.env.local`, 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 packages,
+edit the app, write `.env.example`, or search anywhere else before asking
+it. Do not read deploy config (compose files, Vercel or platform 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.local`, creating the file if needed.
+   Make sure `.gitignore` covers `.env.local` (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.local`, 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.** Next loads
+   `.env.local` into `process.env` on its own: do not add `dotenv`, and never
+   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.
+
+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.local` and ask for a receive-only code
+again. Never set the spend-capable override to get past it.
+
+### Upgrading an existing install
+
+This is not the opening move of a new integration. When OpenReceive is ALREADY
+installed here, `npx openreceive doctor` reports every credential as set/unset
+(never the value) and probes the wallet. Check the installed
+`@openreceive/node` and `@openreceive/browser` 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.
 
 Only then start the quickstart.
 
@@ -109,7 +135,7 @@ itself, and they hold for every integration.
   payer-supplied amounts.
 - `authorize` runs on every request, and the `resource` it receives is a CLAIM
   the payer made, not proof. Read a framework session; never trust a body field.
-- `onPaid` must be idempotent. It runs once per `reference` — your order id, one
+- `onPaid` 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
@@ -290,6 +316,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
@@ -307,11 +335,11 @@ Next.js App Router + React. Requires Node ≥ 22 and Next ≥ 15 (App Router).
 npm install @openreceive/next @openreceive/react
 ```
 
-Install the adapter for your server and the UI package for your frontend; the
+Install the adapter for your server and the UI package for your frontend. The
 wallet client, HTTP handler, and contracts come along as dependencies. The
-`openreceive` package is the CLI only — `npx openreceive …` below needs no
-install. Different stack? Swap the two packages; the rest of this guide is
-identical.
+`openreceive` package is only the CLI, and `npx openreceive …` below needs no
+install. On a different stack, swap the two packages; the rest of this guide
+stays the same.
 
 |          | Packages                                                                                                                      |
 | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
@@ -319,18 +347,21 @@ identical.
 | Frontend | `@openreceive/react`, `@openreceive/vue`, `@openreceive/svelte`, `@openreceive/angular`, `@openreceive/elements` (plain HTML) |
 
 Express: [quickstart-node.md](https://openreceive.org/guides/quickstart-node.md) · Fastify:
-[quickstart-fastify.md](https://openreceive.org/guides/quickstart-fastify.md). This page is the Next.js one,
-and it is where an agent handed the Express guide goes wrong: no `dotenv`, no
-`app.use`, a client component for the checkout.
-
-On a fresh project, the App Router is what `create-next-app` scaffolds; no
-env loader is needed (Next loads `.env.local` itself). Install your ORM
-before step 2 (`npm install prisma @prisma/client` on the Prisma path) —
-`openreceive scaffold` emits files for the ORM you name but never installs it.
-
-npm environments that run with `ignore-scripts` (some editor sandboxes) skip
-Prisma's engine download and esbuild's binary postinstall, so a typecheck or
-build that fails only there is environmental, not a code problem.
+[quickstart-fastify.md](https://openreceive.org/guides/quickstart-fastify.md). This page is the Next.js one.
+An agent given the Express guide goes wrong on Next.js in three places: Next
+needs no `dotenv`, no `app.use`, and it needs a client component for the
+checkout.
+
+On a fresh project, `create-next-app` scaffolds the App Router for you. You
+need no env loader, because Next loads `.env.local` itself. Install your ORM
+before step 2 (`npm install prisma @prisma/client` on the Prisma path).
+`openreceive scaffold` emits files for the ORM you name, but it never installs
+that ORM.
+
+Some editor sandboxes run npm with `ignore-scripts`. That setting skips
+Prisma's engine download and esbuild's binary postinstall. If a typecheck or
+build fails only in such an environment, the environment is the cause, not
+your code.
 
 ### 2. Migrate the payment tables
 
@@ -338,25 +369,25 @@ build that fails only there is environmental, not a code problem.
 npx openreceive scaffold payments --orm prisma   # or drizzle | typeorm | sequelize | knex
 ```
 
-`openreceive scaffold payments` emits one schema/migration file for your ORM
-and a wiring guide. It never touches a database.
+`openreceive scaffold payments` writes one schema or migration file for your
+ORM, plus a wiring guide. It never touches a database.
 → [openreceive scaffold payments](https://openreceive.org/guides/api-reference.md#openreceive-scaffold-payments)
 
-Then run the emitted migration through your normal workflow (for example
-`npx prisma migrate dev`). OpenReceive owns the tables' logic at runtime; there
-is nothing else to generate. Details:
+Then run the generated migration the way you normally do (for example
+`npx prisma migrate dev`). OpenReceive runs the tables' logic at runtime, so
+there is nothing else to generate. Details:
 [Payment storage](https://openreceive.org/guides/storage.md), [Node ORM recipes](https://openreceive.org/guides/node-orms.md).
 
-No ORM? A bare driver handle (`pg`, `node:sqlite`, `better-sqlite3`) is a
-supported `db` in step 4, and there is no scaffold flavor for it — execute the
-same DDL once yourself with `paymentsSchemaSql(dialect)` from
-`@openreceive/http` instead of scaffolding.
+No ORM? You can pass a bare driver handle (`pg`, `node:sqlite`,
+`better-sqlite3`) as the `db` in step 4. The scaffold has no flavor for it.
+Instead of scaffolding, run the same DDL once yourself, using
+`paymentsSchemaSql(dialect)` from `@openreceive/http`.
 
 ### 3. Add wallet credentials
 
-Create a server-only `.env.local` (Next loads it into `process.env` on its
-own — do **not** add `dotenv`, and never prefix these with `NEXT_PUBLIC_`,
-which would inline them into the browser bundle):
+Create a server-only `.env.local`. Next loads it into `process.env` on its
+own, so do **not** add `dotenv`. Never prefix these variables with
+`NEXT_PUBLIC_`, because that would inline them into the browser bundle.
 
 ```dotenv
 NWC_URI=
@@ -365,25 +396,28 @@ 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).
+   ([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 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)).
+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)).
 
-In production supply the same variables through your host's secret manager or
-process environment; `.env.local` is for development and is gitignored by
-`create-next-app`. → [Environment variables](https://openreceive.org/guides/environment-variables.md).
+In production, supply the same variables through your host's secret manager
+or process environment. `.env.local` is for development, and `create-next-app`
+gitignores it. → [Environment variables](https://openreceive.org/guides/environment-variables.md).
 
 ### 4. Wire OpenReceive
 
-One catch-all route file: your hooks plus a database handle. The adapter
-builds the wallet client and the host and returns the `GET`/`POST` exports the
-App Router expects; there is no background reconciler — settlement piggybacks
-on requests through the durable gate, which is what makes it serverless-safe.
+One catch-all route file takes your hooks and a database handle. The adapter
+builds the wallet client and the host, and returns the `GET`/`POST` exports
+the App Router expects. There is no background reconciler, meaning no job that
+checks pending payments on a timer. Settlement runs during normal requests
+instead, through the durable reconcile gate. That is what makes it safe on
+serverless hosts.
 
 ```ts
 // app/openreceive/[...openreceive]/route.ts
@@ -451,15 +485,14 @@ export const { GET, POST } = openReceiveNextHandlers({
 });
 ```
 
-The route file is a **server module** — it imports your database handle and
-reads `process.env`, and nothing in it may be imported from a client
-component. The default prefix is `/openreceive`, which is the directory the
-file sits in; put the catch-all under another directory and pass `prefix` to
-match.
+The route file is a **server module**. It imports your database handle and
+reads `process.env`, so no client component may import anything from it. The
+default prefix is `/openreceive`, which is the directory the file sits in. If
+you put the catch-all under another directory, pass a matching `prefix`.
 
-When the options are themselves async (a database opened lazily, a wallet
-client shared with a worker), build the handlers per request instead of at
-module load — the Buy a Button example does exactly this:
+Sometimes the options are themselves async, such as a database opened lazily
+or a wallet client shared with a worker. Then build the handlers per request
+instead of at module load. The Buy a Button example does exactly this:
 
 ```ts
 async function handle(request: Request): Promise<Response> {
@@ -480,35 +513,44 @@ where many payers share one IP. → [Rate limiting](https://openreceive.org/guid
 
 An optional worker, `startNotificationWorker({ service, host })`, listens for
 wallet payment notifications so settlement does not wait for the next page
-load. It is a separate long-lived Node process, not a route — on a serverless
-host, skip it and rely on the request-path settlement above.
+load. It is a separate long-lived Node process, not a route. On a serverless
+host, skip it and rely on the request-path settlement described above.
 → [startNotificationWorker](https://openreceive.org/guides/api-reference.md#startnotificationworker)
 
-Composing the pieces yourself (`createOpenReceive` + `createHost`) is
-supported when you need a shared wallet client or a custom repository.
+You can also compose the pieces yourself (`createOpenReceive` + `createHost`)
+when you need a shared wallet client or a custom repository.
 → [createOpenReceive](https://openreceive.org/guides/api-reference.md#createopenreceive) ·
 [createHost](https://openreceive.org/guides/api-reference.md#createhost)
 
-Your app also needs an ordinary order-creation route that validates the cart,
-prices with exact decimal math, and returns the order id the page will pass as
-the `reference`. OpenReceive never prices from payer input.
+Your app also needs an ordinary route that creates the order. It validates the
+cart, computes the price with exact decimal math, and returns the order id.
+The page passes that id as the `reference`. OpenReceive never takes a price
+from payer input.
+
+The `reference` is a string you choose, and it identifies what gets fulfilled.
+Use your order id. Make it:
 
-The `reference` is a string you choose, and it is 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 `onPaid`
-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.
+- one per thing you fulfill,
+- created before checkout,
+- kept across retries,
+- never reused.
+
+OpenReceive never looks inside the `reference`, but it relies on it:
+
+- `onPaid` commits fulfillment once per reference.
+- A new checkout under a reference that already settled is refused with 409.
+- A fresh id on every page load would let one order be paid twice.
 
 Naming boundary: TypeScript APIs use camelCase fields (`paymentHash`,
-`amountMsats`); everything on the wire — the mounted HTTP routes and the
-browser snapshots — is snake_case (`payment_hash`, `amount_msats`).
+`amountMsats`). Everything on the wire is snake_case (`payment_hash`,
+`amount_msats`). The wire means the mounted HTTP routes and the browser
+snapshots.
 
 ### 5. Render checkout
 
 `<Checkout>` polls and holds state, so it is a **client component**. Put it in
-a file that starts with `"use client"` and import the stylesheet from that
-same module; the page that renders it can stay a server component.
+a file that starts with `"use client"`, and import the stylesheet from that
+same module. The page that renders it can stay a server component.
 
 ```tsx
 // app/checkout/[reference]/order-checkout.tsx
@@ -537,53 +579,58 @@ export default async function CheckoutPage({
 ```
 
 `/checkout/[reference]` is deliberately a page of its own rather than a modal
-on the cart: a payer with a swap deposit in flight has no account and no email
-from you, so this URL is the only thing that brings them back to their payment
-— it has to survive a reload and a bookmark
-([Swap refunds](https://openreceive.org/guides/swap-refunds.md)). Do not render the checkout for a
-reference the current session may not see; the page can read the session and
-404 before it renders, and `authorize` refuses the routes regardless.
+on the cart. A payer with a swap deposit in flight has no account and no email
+from you. This URL is the only thing that brings them back to their payment,
+so it has to survive a reload and a bookmark
+([Swap refunds](https://openreceive.org/guides/swap-refunds.md)).
+
+Do not render the checkout for a reference the current session may not see.
+The page can read the session and return 404 before it renders, and
+`authorize` refuses the routes regardless.
 
 The checkout renders, polls, and settles itself. The compiled `styles.css`
 sheets (`@openreceive/react`, `@openreceive/elements`) are self-contained and
-scoped: every rule applies only inside what OpenReceive renders. No
-`transpilePackages` entry is needed; the packages ship plain ESM.
+scoped: every rule applies only inside what OpenReceive renders. You need no
+`transpilePackages` entry, because the packages ship plain ESM.
 
 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.
 
-`<Checkout>` is complete as rendered: it already shows the `description` from
+`<Checkout>` is complete as rendered. It already shows the `description` from
 `amountFor` and the collapsed transaction-details panel. Do not build a custom
-UI to satisfy those rules — they only become your job if you replace the
-drop-in ([Checkout UX](https://openreceive.org/guides/checkout-ux.md)).
+UI to show them. The display rules for them become your job only if you
+replace the drop-in component ([Checkout UX](https://openreceive.org/guides/checkout-ux.md)).
 
-Match the host page's theme: by default the checkout follows the payer's
-stored choice, then the system scheme. If this page is always one theme, lock
-it — `<Checkout theme="dark" … />` (`theme` attribute on the custom element) —
-so a white card never lands on a dark page. The checkout is styled by CSS
-variables under `data-theme`; [Frontend checkout](https://openreceive.org/guides/frontend-checkout.md) has
-the knobs.
+Match the host page's theme. By default the checkout follows the payer's
+stored choice, then the system color scheme. If this page always uses one
+theme, lock it with `<Checkout theme="dark" … />`. On the custom element, set
+the `theme` attribute. Locking the theme keeps a white card off a dark page.
+CSS variables under `data-theme` style the checkout.
+[Frontend checkout](https://openreceive.org/guides/frontend-checkout.md) lists the settings you can change.
 
 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
+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 wait to load tutorial screenshots until a tutorial first opens.
+Single-file builds, including the standalone checkout, include them from the
+start. If your Content-Security-Policy has a strict `img-src`, allow `data:`
 ([Provider registry](https://openreceive.org/guides/provider-registry.md#assets)).
 
-That is the whole loop: your server owns the price and the order, the payer gets
-an invoice, and `onPaid` runs once inside the settlement transaction.
+That is the whole loop. Your server owns the price and the order. The payer
+gets an invoice. `onPaid` runs inside the settlement transaction. If that
+transaction rolls back, the callback may run again. For delivery to outside
+systems, use an outbox in your app: record the message in the transaction and
+send it after commit.
 
-A runnable illustration of this boundary — not a template to copy models from —
-is Buy a Button
+Buy a Button is a runnable illustration of this boundary
 (`examples/buttons/server/nextjs-fullstack`).
-It has products, visitors, and orders, with the three hooks as the only bridge,
-its shop routes as three-line App Router wrappers, and `/checkout/[reference]`
-as the resumable page. Map that shape onto the models in THIS app.
+It is not a template to copy models from. It has products, visitors, and
+orders, and the three hooks are the only bridge to OpenReceive. Its shop
+routes are three-line App Router wrappers, and `/checkout/[reference]` is the
+resumable page. Map that shape onto the models in THIS app.
 
 ### 6. Verify
 
@@ -591,16 +638,17 @@ as the resumable page. Map that shape onto the models in THIS app.
 npx openreceive doctor
 ```
 
-`openreceive doctor` checks Node, `NWC_URI`, and swap-provider configuration,
-and probes the wallet relay to confirm the code is receive-only. Add
-`--db <file-or-url>` to confirm the migration ran, and
-`--url http://localhost:3000` to confirm the routes are mounted; every failing
+`openreceive doctor` checks Node, `NWC_URI`, and the swap-provider
+configuration. It also probes the wallet relay to confirm the code is
+receive-only. Add `--db <file-or-url>` to confirm the migration ran. Add
+`--url http://localhost:3000` to confirm the routes are mounted. Every failing
 line states its own fix.
 → [openreceive doctor](https://openreceive.org/guides/api-reference.md#openreceive-doctor)
 
-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
-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.
+Then open the checkout in a browser. Confirm the payment-method icons and
+wallet logos render. Open a wallet's pay tutorial to check its screenshots.
+If an image is missing, look in the console for CSP violations and in the
+Network panel for failed JavaScript chunks. To fix it, allow `data:` in
+`img-src` and deploy the complete build output. Do not add image routes or
+copy package source images. Do not use registry `icon_path` or tutorial
+`path` keys as browser URLs.