openreceive 0.4.11 → 0.4.14

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (FastAPI)
 
-These directions describe OpenReceive 0.4.11.
+These directions describe OpenReceive 0.4.14.
 
 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
@@ -37,67 +37,94 @@ 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`, the process
-   env, the deploy config, whatever this app already uses. 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 most apps
-   > that is a `.env` file 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` (`pip show openreceive`) 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.
-7. Run `openreceive doctor --app <module>:app` (or `--offline` before the
-   router exists). It reports `NWC_URI` presence without printing it, probes
-   the wallet, and once the router is wired names any hook still on a
-   placeholder and whether the migration ran. Exit code 1 is a finding to
-   fix, not a reason to skip the check.
+## 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 packages,
+edit the app, write `.env.example`, or search anywhere else before asking
+it. Do not read deploy config (compose files, 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`, 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.** OpenReceive reads
+   `os.environ`, and a `.env` file on disk is not in it. Start the dev server
+   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.
+
+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.
+
+After the router is wired, run `openreceive doctor --app <module>:app`. It
+reports `NWC_URI` presence without printing it, probes the wallet, and names
+any hook still on a placeholder and whether the migration ran. Exit code 1 is a
+finding to fix, not a reason to skip the check.
+
+### Upgrading an existing install
+
+This is not the opening move of a new integration. When OpenReceive is ALREADY
+installed here, the doctor above is the first check. Compare the installed
+`openreceive` (`pip show openreceive`) 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.
 
@@ -130,15 +157,19 @@ itself, and they hold for every integration.
   late becomes `refund_required`, and the payer claims it on a SECOND VISIT,
   after leaving your page to fetch an address from another wallet. Three things
   must exist or that money is unreachable through your UI: a per-order URL your
-  server serves (`/checkout/:reference` — `syncUrl` on the drop-ins), your own
-  order-summary route to restore the order from, and the ATTEMPT.
+  server serves (`/checkout/:reference` — `syncUrl` on `<Checkout>`, `sync-url`
+  or `resumable` on `<openreceive-checkout>`), your own order-summary route to
+  restore the order from, and the ATTEMPT.
   `/checkouts/prepare` returns no attempts, so a checkout rebuilt from the
   reference alone opens on the method grid. Re-picking the same coin
   (`POST /swaps`) re-serves the committed attempt — but only while it is live,
   and the shadow invoice behind a swap lasts about half an hour, after which the
   same click mints a NEW deposit address and the refund is off-screen. Keep the
   `payment_hash` and reopen the attempt with `POST /swaps/status`, which has no
-  such window. https://openreceive.org/guides/swap-refunds.md
+  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
 - 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
@@ -322,19 +353,20 @@ pip install "openreceive[fastapi]"
 npm install @openreceive/react
 ```
 
-One Python distribution with framework extras: `openreceive[fastapi]` brings
-FastAPI, Starlette and SQLAlchemy; the wallet client (websockets, coincurve,
-cryptography), the HTTP engine and the `openreceive` CLI come with the base
-package. The npm package is the checkout UI for your frontend. Different
-stack? Swap the two: `openreceive[django]` with the Django quickstart; a
-bundler-less page uses `@openreceive/elements` instead of React.
+OpenReceive is one Python distribution with framework extras.
+`openreceive[fastapi]` brings FastAPI, Starlette and SQLAlchemy. The base
+package includes the wallet client (websockets, coincurve, cryptography), the
+HTTP engine and the `openreceive` CLI. The npm package is the checkout UI for
+your frontend. On a different stack, swap the two: use `openreceive[django]`
+with the Django quickstart. A page without a bundler uses
+`@openreceive/elements` instead of React.
 
 |          | Packages                                                                                                                      |
 | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
 | Server   | `openreceive[fastapi]`, `openreceive[django]`, `openreceive[sqlalchemy]` (Flask and plain WSGI/ASGI: the Flask recipe) |
 | Frontend | `@openreceive/react`, `@openreceive/vue`, `@openreceive/svelte`, `@openreceive/angular`, `@openreceive/elements` (plain HTML) |
 
-Use `uv` or a virtualenv on Python 3.10 or newer; a system Python 3.9 cannot
+Use `uv` or a virtualenv on Python 3.10 or newer. A system Python 3.9 cannot
 install the package.
 
 ### 2. Migrate the payment tables
@@ -344,24 +376,27 @@ openreceive scaffold payments --alembic --dialect postgres    # or sqlite | mysq
 ```
 
 `openreceive scaffold payments --alembic` writes one Alembic revision into
-`alembic/versions/` that creates `openreceive_payments` (the payment attempts)
-and `openreceive_meta` (the reconcile gate) with the DDL frozen in the file.
-Set its `down_revision` to your current head (`alembic heads`), then apply it
-the way you apply your own: `alembic upgrade head`. It never opens a database
-connection.
+`alembic/versions/`. The DDL is frozen in the file, and it creates two tables:
+
+- `openreceive_payments`, the payment attempts
+- `openreceive_meta`, the reconcile gate
+
+Set the revision's `down_revision` to your current head (`alembic heads`).
+Then apply it the way you apply your own revisions: `alembic upgrade head`.
+The command never opens a database connection.
 → [openreceive scaffold payments](https://openreceive.org/guides/api-reference.md#openreceive-scaffold-payments-python)
 
 No Alembic? `openreceive scaffold payments --sql --dialect postgres` prints
-the same DDL for `psql`, a Flyway file, or whatever runs your migrations; in
-code, `payments_schema_sql(dialect)` from `openreceive.storage.sql` is the
-same string. OpenReceive owns the tables' logic at runtime — locking,
-write-once settlement, the reconciliation state machine — and there is
-nothing else to generate. Details: [Payment storage](https://openreceive.org/guides/storage.md).
+the same DDL. Feed it to `psql`, a Flyway file, or whatever runs your
+migrations. In code, `payments_schema_sql(dialect)` from
+`openreceive.storage.sql` returns the same string. OpenReceive owns the
+tables' logic at runtime: locking, write-once settlement, and the
+reconciliation state machine. There is nothing else to generate. Details: [Payment storage](https://openreceive.org/guides/storage.md).
 
 ### 3. Add wallet credentials
 
-Put the credentials in the server's environment (a `.env` your process
-manager loads, `uvicorn --env-file .env`, or your secret store):
+Put the credentials in the server's environment. That can be a `.env` your
+process manager loads, `uvicorn --env-file .env`, or your secret store:
 
 ```dotenv
 NWC_URI=
@@ -370,27 +405,33 @@ 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)).
 
-OpenReceive reads `os.environ`; a `.env` file on disk is not enough on its
-own. `uvicorn --env-file .env` loads one in development; in production the
-process manager or secret store injects the values. Every variable is on
-[Environment variables](https://openreceive.org/guides/environment-variables.md).
+OpenReceive reads `os.environ`, so a `.env` file on disk is not enough on its
+own. `uvicorn --env-file .env` loads one in development. In production, the
+process manager or secret store injects the values.
+[Environment variables](https://openreceive.org/guides/environment-variables.md) lists every variable.
 
 ### 4. Wire OpenReceive
 
-Twelve lines: your three hooks as a `Host`, a router included under a
-prefix, and a lifespan that checks the wallet at startup. The router builds
-the wallet client from `NWC_URI` and mounts the framework-free engine; there
-is no background reconciler — settlement piggybacks on requests through the
-durable gate.
+The wiring takes twelve lines:
+
+- your three hooks as a `Host`
+- a router included under a prefix
+- a lifespan that checks the wallet at startup
+
+The router builds the wallet client from `NWC_URI` and mounts the
+framework-free engine. 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.
 
 ```python
 from fastapi import FastAPI
@@ -439,26 +480,28 @@ app.include_router(
 )
 ```
 
-`authorize` receives the Starlette `Request`, so cookies, headers and whatever
+`authorize` receives the Starlette `Request`. Cookies, headers, and whatever
 `SessionMiddleware` or auth dependency this app already has are readable
-there — FastAPI ships no session of its own, so the payer's `reference` must
-be bound to something the request proves. Run uvicorn with `--proxy-headers`
-behind a reverse proxy, or `rate_limiting` counts the proxy as the one payer.
-
-**There is no CSRF layer to add.** FastAPI has none, and OpenReceive does not
-want one: every mounted route refuses a request whose `Sec-Fetch-Site` header
-says `cross-site`, which is what stops another origin's page from minting or
-refunding on a logged-in payer's behalf — exactly the protection the Express
-and Fastify adapters rely on. Its limit is the header itself: a client that
-does not send it (a non-browser, an old browser) is not refused, so
-`authorize` stays the actual boundary. [Security](https://openreceive.org/guides/security.md) has the full
-account.
+there. FastAPI ships no session of its own, so you must bind the payer's
+`reference` to something the request proves. Behind a reverse proxy, run
+uvicorn with `--proxy-headers`. Otherwise `rate_limiting` counts the proxy as
+the one payer.
+
+**There is no CSRF layer to add.** FastAPI has no CSRF (cross-site request
+forgery) layer, and OpenReceive does not want one. Every mounted route refuses
+a request whose `Sec-Fetch-Site` header says `cross-site`. That stops another
+origin's page from minting or refunding on a logged-in payer's behalf. The
+Express and Fastify adapters rely on exactly the same protection. Its limit is
+the header itself. A client that does not send it, such as a non-browser or an
+old browser, is not refused. So `authorize` stays the actual boundary.
+[Security](https://openreceive.org/guides/security.md) has the full account.
 
 `openreceive_lifespan` runs the receive-only wallet preflight when uvicorn
-starts and stops the process on a missing, unreachable or spend-capable code —
-the deploy fails instead of the first payer. Pass `lazy=True` for tests and
-secretless build steps; the first request then checks the wallet and answers
-`503 WALLET_UNAVAILABLE` until it passes.
+starts. It stops the process if the code is missing, unreachable, or able to
+spend. That way the deploy fails instead of the first payer. Pass `lazy=True`
+for tests and for build steps that have no secrets. The first request then
+checks the wallet, and requests get `503 WALLET_UNAVAILABLE` until the check
+passes.
 → [openreceive_router](https://openreceive.org/guides/api-reference.md#openreceive_router) ·
 [openreceive_lifespan](https://openreceive.org/guides/api-reference.md#openreceive_lifespan) ·
 [the authorize context](https://openreceive.org/guides/api-reference.md#the-authorize-context)
@@ -475,14 +518,16 @@ prices with exact decimal math, and returns the order id the page will pass as
 the `reference`. OpenReceive never prices from payer input.
 
 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 `on_paid`
-commits fulfillment 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.
+your order id. Use one per thing you fulfill, create it before checkout, keep
+it across retries, and never reuse it. OpenReceive never looks inside it, but
+the reference still matters:
+
+- `on_paid` commits fulfillment once per reference.
+- A new checkout under a reference that already settled is refused with 409.
+- A fresh id per page load lets one order be paid twice.
 
 Naming boundary: the Python API is snake_case (`payment_hash`,
-`amount_msats`) and so is everything on the wire — the mounted HTTP routes and
+`amount_msats`), and so is everything on the wire. The mounted HTTP routes and
 the browser snapshots use the same names.
 
 ### 5. Render checkout
@@ -494,49 +539,57 @@ import "@openreceive/react/styles.css";
 <Checkout reference={order.id} prefix="/openreceive" />;
 ```
 
-The checkout renders, polls, and settles itself. The compiled `styles.css`
-sheets (`@openreceive/react`, `@openreceive/elements`) are self-contained — a
-plain `<link rel="stylesheet">` works with no build step — and scoped: every
+The checkout renders, polls, and settles itself.
+
+`@openreceive/react` and `@openreceive/elements` each ship a compiled
+`styles.css`. Each sheet is self-contained, so a plain
+`<link rel="stylesheet">` works with no build step. Each is also scoped: every
 rule applies only inside what OpenReceive renders.
 
-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. Import it from
+JavaScript if your bundler handles CSS, or use a plain
+`<link rel="stylesheet">`. Do not `@import` it into your app's Tailwind entry.
+Its rules have zero specificity, so your page's styles can 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 inside the settlement transaction. Rolled-back transactions may retry the callback; use a host outbox for external delivery.
+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 page without a bundler renders the same checkout as a custom element:
 `<openreceive-checkout reference="…" prefix="/openreceive">` from
-`@openreceive/elements` (or its standalone build, served from your static
-directory). A runnable illustration of the boundary — not a template to copy
-models from — is Buy a Button
-(`examples/buttons/server/fastapi`):
-products, visitors and orders in SQLite, the three hooks as the only bridge,
-and the smallest correct FastAPI integration of the packaged checkout. Map
-that shape onto the models in THIS app.
+`@openreceive/elements`. You can also serve its standalone build from your
+static directory.
+
+Buy a Button is a runnable illustration of the boundary
+(`examples/buttons/server/fastapi`).
+It is not a template to copy models from. It keeps products, visitors and
+orders in SQLite, and the three hooks are the only bridge to OpenReceive. It
+is the smallest correct FastAPI integration of the packaged checkout. Map that
+shape onto the models in THIS app.
 
 ### 6. Verify
 
@@ -545,13 +598,13 @@ openreceive doctor --app main:app
 ```
 
 `openreceive doctor` checks Python, `NWC_URI`, and swap-provider
-configuration, and probes the wallet relay to confirm the code is
+configuration. It also probes the wallet relay to confirm the code is
 receive-only. With `--app module:attr` (your FastAPI app, the router, or an
-`OpenReceiveApp`) it also confirms the migration ran and names any hook still
-on a placeholder; add `--url http://localhost:8000` to confirm the routes are
-mounted. Every failing line states its own fix; exit code 1 when anything
-fails. `openreceive debug-report` prints the same as a redacted support
-report.
+`OpenReceiveApp`), it also confirms the migration ran and names any hook still
+on a placeholder. Add `--url http://localhost:8000` to confirm the routes are
+mounted. Every failing line states its own fix, and the command exits with
+code 1 when anything fails. `openreceive debug-report` prints the same output
+as a redacted support report.
 → [openreceive doctor](https://openreceive.org/guides/api-reference.md#openreceive-doctor-python)
 
 Then open the checkout in a browser, confirm the payment-method icons and
@@ -561,6 +614,6 @@ 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.
 
-Swap credentials (`LSC_URI_*`) stay server-side too: the provider order id and
-token live in the attempt's server-only `swap_data` column and never reach a
+Swap credentials (`LSC_URI_*`) stay server-side too. The provider order id and
+token live in the attempt's server-only `swap_data` column. They never reach a
 response or a log ([Automated swaps](https://openreceive.org/guides/automated-swaps.md)).