openreceive-rails 0.4.14 → 0.4.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e427ecbaa9d1cbb7007ea7799ff14eeef1a88b5e9b354d79dc9ad1c2d1fc4c53
-  data.tar.gz: e5a92ea94f6edb67a171c03d1bd1367bd66973d672bfd9cdf4f6eb16a52c9307
+  metadata.gz: f3b64d28550bbe44f3ca4b0b6fcc4e94430a415f168b8249f2513e7c85c56a46
+  data.tar.gz: 60dd73cfd9f11b23b99c34e64640c541aaf5404ba01980b35a31d23e7bd9eeb6
 SHA512:
-  metadata.gz: 2c2a061b4ce15de084a423ee8f440e4bcaf6ac2ce0b156855daae25492ac1df0a51d788739e3008c81c08faeb924cdb8faa83c1ca7f6e1b29e3919b0a139b93f
-  data.tar.gz: 933f003c11889f222970ca79353b04a468b9076f82466a6d3f9f76790b0b9d267c483b135f81852ddeb03f0c0e79e2dcf60291e09cab6c699dc2b8cef087c737
+  metadata.gz: 68dac8c68722b354533736a51fe7a870df757ac5ca17d76fe1e301cee750ed195a40403620bd7d1d34334adc95c8143418ca1bb6582d731c5b0c99da7087edcc
+  data.tar.gz: ab2e30e2e102aafa38f4b9c8e0f55bec5dcc18b9919d5f329c3b5e6f71b3ba80c59abef064afdb8d5ac7a43d7133a25f7e19b28e88221d06e1cb02d005ba856e

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.4.16 - 2026-10-06
+
+Release with the complete 0.4.16 package family and corrected shared agent
+directions. No Ruby runtime changes from 0.4.15.
+
+## 0.4.15 - 2026-10-06
+
+- Install agent skills with `bin/rails openreceive:skills` (optional
+  `--dir .claude/skills`). The core `openreceive` gem owns the one offline
+  bundle; Rails/server gems no longer duplicate it. Other Ruby hosts can use
+  `npx skills add OpenReceive/openreceive`.
+
+Requires `nwc-ruby ~> 0.3`. On 0.2.x a silent relay, or an offline wallet
+behind a live relay, could block a checkout's `make_invoice` and the boot
+preflight indefinitely, holding a web thread. 0.3 bounds every call by
+`request_timeout`, retries only failures from before the request is written,
+and tries each relay in the connection string. Relay failures now answer 503
+`WALLET_UNAVAILABLE` (retryable) instead of 502 `OTHER`.
+
 ## 0.4.14 - 2026-10-04
 
 Fixes two 0.4.13 reconciliation regressions. A host-clock attempt could be
@@ -162,7 +181,8 @@ warning links the rate-limiting guide.
 
 ### The gem carries the agent skills
 
-`skills/` ships in the gem — the integrate and debug playbooks for coding
+At this release, `skills/` shipped in this gem (now supplied by the core
+`openreceive` dependency; see Unreleased) — the integrate and debug playbooks for coding
 agents, kept byte-identical to the repository tree by
 `npm run generate:skills`.
 

data/README.md

@@ -131,3 +131,13 @@ Storage-free `openreceive-server` handlers can call `on_paid` on every settled
 poll, so advanced hosts own the conditional write/outbox. A raw create hook
 refusal returns 409 with instructions withheld; repository infrastructure failures
 remain retryable 503.
+
+## Agent skills
+
+In Rails, run `bin/rails openreceive:skills` from your application. The offline
+skills ship once in the core `openreceive` gem. Non-Rails projects can use
+`npx skills add OpenReceive/openreceive`.
+See [agent setup](https://openreceive.org/agents). The bundled installers write
+to `.agents/skills/`; use `--dir .claude/skills` for Claude Code. They replace
+only `integrate-openreceive` and `debug-openreceive-payment`, preserving
+unrelated skills.

data/lib/openreceive/rails/version.rb

@@ -5,6 +5,6 @@ module OpenReceive
   # top-level `::Rails` framework constant — engine code always references the framework as
   # `::Rails` to avoid shadowing.
   module Rails
-    VERSION = "0.4.14"
+    VERSION = "0.4.16"
   end
 end

data/lib/rails/commands/openreceive/openreceive_command.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "rails/command"
+require "openreceive/skills"
+
+module Rails
+  module Command
+    # A Rails command accepts --dir before the Rake fallback parses arguments.
+    # It does not boot the application or require wallet credentials.
+    class OpenreceiveCommand < Base
+      desc "skills", "Install the bundled OpenReceive agent skills into this project"
+      method_option :dir, type: :string, default: ".agents/skills"
+      def skills
+        OpenReceive::Skills.install(directory: options[:dir])
+      end
+    end
+  end
+end

data/lib/tasks/openreceive.rake

@@ -1,6 +1,12 @@
 # frozen_string_literal: true
 
 namespace :openreceive do
+  desc "Install agent skills (optional directory: openreceive:skills[path])"
+  task :skills, [:dir] do |_task, args|
+    require "openreceive/skills"
+    OpenReceive::Skills.install(directory: args[:dir] || ".agents/skills")
+  end
+
   # Step 0 of the agent directions, as one command.
   #
   # "Look for NWC_URI in this app's server environment" is a SEARCH, and it has
@@ -18,6 +24,7 @@ namespace :openreceive do
     set = ->(name) { ENV[name].to_s.strip.empty? ? "unset" : "set" }
     lines = [
       "openreceive:doctor",
+      "Agent skills: run `bin/rails openreceive:skills`",
       "  NWC_URI:          #{set.call('NWC_URI')}",
       "  LSC_URI_PRIMARY:  #{set.call('LSC_URI_PRIMARY')}",
       "  LSC_URI_BACKUP:   #{set.call('LSC_URI_BACKUP')}"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openreceive-rails
 version: !ruby/object:Gem::Version
-  version: 0.4.14
+  version: 0.4.16
 platform: ruby
 authors:
 - OpenReceive
@@ -15,28 +15,28 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.4.14
+        version: 0.4.16
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.4.14
+        version: 0.4.16
 - !ruby/object:Gem::Dependency
   name: openreceive-server
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.4.14
+        version: 0.4.16
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.4.14
+        version: 0.4.16
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -57,20 +57,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.2.4
+        version: '0.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.2.4
+        version: '0.3'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -130,19 +124,8 @@ files:
 - lib/openreceive/rails/version.rb
 - lib/openreceive/reconcile.rb
 - lib/openreceive/reconcile_scan.rb
+- lib/rails/commands/openreceive/openreceive_command.rb
 - lib/tasks/openreceive.rake
-- skills/debug-openreceive-payment/SKILL.md
-- skills/integrate-openreceive/SKILL.md
-- skills/integrate-openreceive/references/btcpay.md
-- skills/integrate-openreceive/references/django.md
-- skills/integrate-openreceive/references/fastapi.md
-- skills/integrate-openreceive/references/fastify.md
-- skills/integrate-openreceive/references/laravel.md
-- skills/integrate-openreceive/references/next.md
-- skills/integrate-openreceive/references/node.md
-- skills/integrate-openreceive/references/php.md
-- skills/integrate-openreceive/references/rails.md
-- skills/integrate-openreceive/references/woocommerce.md
 homepage: https://openreceive.org
 licenses:
 - MIT

data/skills/debug-openreceive-payment/SKILL.md

@@ -1,97 +0,0 @@
----
-name: debug-openreceive-payment
-description: >
-  Diagnose a failing OpenReceive integration. Use when an OpenReceive-powered
-  checkout misbehaves: the server refuses to boot, checkout routes return 403,
-  404, 409, or 5xx, a paid invoice never settles, a swap refund seems
-  unreachable, or the checkout UI renders nothing.
-license: MIT
----
-
-# Debug an OpenReceive payment
-
-Work top-down: configuration, then the request, then settlement. Every guide
-URL below is raw markdown — fetch it when the step needs it.
-
-## 1. Run the doctor first
-
-```sh
-npx openreceive doctor                     # Node version, NWC_URI, swap config, wallet probe
-npx openreceive doctor --db <db>           # + are openreceive_payments/openreceive_meta migrated?
-npx openreceive doctor --url http://localhost:3000   # + are the routes actually mounted?
-```
-
-Each failing line states its own fix. `npx openreceive debug-report` prints the
-same diagnostics redacted, always exit 0 — safe to share.
-
-## 2. Boot failures
-
-| Symptom | Cause and fix |
-| --- | --- |
-| `MISSING_NWC` / "needs a receive-only NWC code" | `NWC_URI` is not in the server process env. A `.env` file alone is not enough — something must load it (`dotenv/config`, Next auto-load). Get a code: https://openreceive.org/get_a_nwc_code_to_receive_payments |
-| `INVALID_NWC` / "not a valid NWC code" | The value is malformed (must be `nostr+walletconnect://` with 64-hex pubkey and secret, ≥1 `wss` relay). Re-copy it from the wallet. |
-| "NOT receive-only" / spend methods advertised | The wallet minted a spend-capable code; OpenReceive fails closed because a leak would drain the wallet. Mint a receive-only code. Overriding (`allowSpendCapableWallet` / `OPENRECEIVE_ALLOW_SPEND_CAPABLE_NWC`) is a last resort. |
-| Wallet preflight failed (methods/encryption) | The wallet must advertise `make_invoice` + `list_transactions` and NIP-04 or NIP-44 v2. Use a compatible wallet. |
-| "The openreceive_meta table does not exist" / raw `no such table: openreceive_payments` | The migration was never applied. Node: `npx openreceive scaffold payments --orm <yours>`, then run the emitted migration through the app's normal workflow. Rails: `bin/rails generate openreceive:install`, then `bin/rails db:migrate`. https://openreceive.org/guides/storage.md |
-| "requires amountFor / onPaid / authorize / host" | The factory is missing a required hook — see the host contract in https://openreceive.org/guides/api-reference.md |
-
-## 3. Request-time errors from the routes
-
-| Status | Meaning | Where to look |
-| --- | --- | --- |
-| 403 FORBIDDEN | Your own `authorize` hook denied it, or the request looked cross-site. Check the session/cookie actually reaches the checkout routes. https://openreceive.org/guides/authorization.md |
-| Never 403s — any visitor can mint, poll, or refund for any reference | The opposite failure: on Rails the generated `config.authorize = OpenReceive::ALLOW_ALL_AUTHORIZE` placeholder is still installed (the engine warns at boot; `bin/rails openreceive:doctor` reports it). Replace it with the app's real ownership check. https://openreceive.org/guides/authorization.md |
-| 404 NOT_FOUND | `amountFor` returned `null` (unknown reference), or the `payment_hash` does not belong to that reference. |
-| 409 CONFLICT | **Normal state, not a bug**: the reference already settled, or an unpaid checkout for that method is already live. Show it as order state; never retry-loop. |
-| 503 retryable | The host hook failed while persisting the attempt (instructions withheld), or the wallet is unavailable. Read the server log for the underlying error. |
-| Framework 404 / HTML error page | The router is not mounted, or mounted at a different prefix than the UI's `prefix` prop. `doctor --url` distinguishes these. |
-
-## 4. Paid but never settles
-
-- Settlement is opportunistic: any OpenReceive request runs one reconcile pass
-  through a durable gate (min 3s between wallet scans, stretched by invoice
-  age). A quiet server settles on the next request — or run the optional
-  notification worker. No timer is missing; that is the design.
-- An unpaid attempt closes only after a successful wallet scan at/after expiry
-  plus a 900s grace constant — a local clock alone never closes one. `expired`
-  arriving "late" is correct.
-- `onPaid` runs once per reference, first settled attempt only, inside the
-  settlement transaction. If your fulfillment did not run, check whether the
-  guarded `UPDATE … WHERE` matched zero rows (already transitioned).
-  https://openreceive.org/guides/storage.md
-
-## 5. Swaps and refunds
-
-- A deposit that arrives short or late becomes `refund_required`; the payer
-  claims it on a second visit. That needs a per-order URL you serve
-  (`/checkout/:reference`, `syncUrl` on the drop-ins). Keep the
-  `payment_hash`: `POST /swaps/status` reopens the attempt with no expiry
-  window, while re-picking the coin mints a new deposit after ~30 minutes.
-- Refunds exist only for swap deposits from `refund_required`. There is **no
-  Lightning refund** — the wallet cannot spend. Do not chase one.
-  https://openreceive.org/guides/swap-refunds.md
-- "Payer reports two different amounts on a stablecoin checkout" (50.05 or
-  50.03?): the deposit amount is a token quantity, `fee.pay_in_fiat` is its
-  fiat valuation. Only `swap.deposit_amount` is an instruction. From 0.4.10 the
-  packaged checkout renders a USD stablecoin's breakdown in the token and never
-  shows `pay_in_fiat`; on an older bundle, upgrade `@openreceive/*`. To verify,
-  read the row's `deposit_amount` and `fee` and confirm the UI shows only the
-  deposit amount. A custom UI must call `createSwapFeeBreakdown(fee, swap)`
-  with the swap, not the fee alone.
-
-## 6. Checkout UI shows nothing
-
-- The components require `prefix` — the exact base path the routes are mounted
-  at (`"/openreceive"` unless you changed it).
-- Import the stylesheet (`@openreceive/react/styles.css` or the elements
-  sheet).
-- "invoice must not be an NWC connection string" means a server secret leaked
-  into a browser payload — stop and fix the server response; never render it.
-  https://openreceive.org/guides/frontend-checkout.md
-
-## Still stuck
-
-The full route/option/error reference:
-https://openreceive.org/guides/api-reference.md · machine-readable contract:
-https://openreceive.org/openapi.yaml · library bug reports:
-https://openreceive.org/contact

data/skills/integrate-openreceive/SKILL.md

@@ -1,139 +0,0 @@
----
-name: integrate-openreceive
-description: >
-  Integrate OpenReceive inbound Bitcoin Lightning payments into an application.
-  Use when adding Bitcoin, Lightning, or crypto checkout to a Node.js, Express,
-  Fastify, Next.js, Rails, React, Vue, Svelte, Angular, or plain-HTML
-  application with OpenReceive (the @openreceive/* npm packages or the
-  openreceive-rails gem), or when connecting a BTCPay Server store to a
-  receive-only NWC wallet with the OpenReceive plugin.
-license: MIT
----
-
-# Integrate OpenReceive
-
-OpenReceive is a payment library that runs inside the application you are
-editing. It mounts HTTP routes there, issues Lightning invoices against a
-wallet the merchant already controls, and calls back into your code when one
-settles. There is no OpenReceive account and no API key; funds land directly in
-the merchant's wallet. The one required credential is a **receive-only NWC
-code** (`NWC_URI`).
-
-## Pick the stack, then follow its directions
-
-1. Identify the server stack of the application you are in.
-2. Open the matching reference — it is complete (quickstart inlined) and needs
-   no network access:
-   - Node, Express: [references/node.md](references/node.md)
-   - Node, Fastify: [references/fastify.md](references/fastify.md)
-   - Node, Next.js App Router: [references/next.md](references/next.md)
-   - Rails: [references/rails.md](references/rails.md)
-   - Django: [references/django.md](references/django.md)
-   - Laravel: [references/laravel.md](references/laravel.md)
-   - WordPress + WooCommerce: [references/woocommerce.md](references/woocommerce.md) — the packaged gateway and merchant settings.
-   - BTCPay Server: [references/btcpay.md](references/btcpay.md) — a plugin,
-     configured in BTCPay's store UI or Greenfield API; no application code,
-     no npm packages, no gem. The rest of this file is about the library.
-3. Follow its **Step 0** first: before writing code or searching the machine,
-   ask the user for the receive-only NWC code (then the swap URI), one question
-   per message, and store each pasted code in the project's env file yourself.
-   Never print the value; never invent a placeholder.
-
-Install, per adapter — Express: `npm install @openreceive/express @openreceive/react`;
-Fastify: `npm install @openreceive/fastify @openreceive/react`; Next.js:
-`npm install @openreceive/next @openreceive/react`. Swap the UI package (`vue`,
-`svelte`, `angular`, `elements`) for the frontend the app already has. Install
-(Rails): `bundle add openreceive-rails`.
-
-## The three server objects
-
-| Object | Built with | Talks to |
-| --- | --- | --- |
-| Wallet client | `createOpenReceive()` | the merchant's wallet — mints invoices, reads settlement, holds the NWC code |
-| Host | `createHost()` | your database — your hooks plus the `openreceive_payments` table |
-| HTTP routes | `openReceiveExpress()` / `openReceiveFastify()` / `openReceiveNext()` / the Rails engine | the browser — mounted at `/openreceive` by default |
-
-The quickstart's one-factory form (`openReceiveExpress({ wallet, storage,
-amountFor, authorize })`) builds all three; compose them separately only for a
-shared wallet client or a custom repository. The checkout UI
-(`<Checkout reference={...} prefix="/openreceive" />`) is the optional fourth
-piece.
-
-## The host contract: authorize, amountFor, onPaid
-
-Your application keeps orders, users, prices, and fulfillment. Three hooks are
-the entire bridge — wire them to the models this app already has, never to
-copied demo models:
-
-- `amountFor(reference)` — the authoritative price, read from your own data.
-  Return `{ currency, value, description }` with `value` a **decimal string**
-  (never a float, never payer input), or `null` when there is nothing to pay
-  for. The `reference` is your order id: one per thing you fulfill, created
-  before checkout, kept across retries, never reused.
-- `authorize({ action, request, resource })` — your own access check, run on
-  every request. `resource.reference` is a claim the payer made, not proof;
-  read a real session.
-- `onPaid({ reference, paidAt, query })` — fulfillment, run once per reference
-  inside the settlement transaction, only for the first settled attempt. Use
-  the provided `query`, not your ORM's other connection, and guard the
-  transition (`UPDATE … WHERE state = 'awaiting_payment'`).
-
-## 409 is a state, not a failure
-
-The library serializes attempts per reference. A create that returns **409
-CONFLICT** is normal checkout flow: the reference already settled, or an unpaid
-checkout for that payment method is already in progress. Surface it as order
-state; do not retry-loop it, and do not build an idempotency store around it —
-that serialization is the library's job. (A hook failure while persisting an
-attempt is a **503 retryable**, deliberately distinct.)
-
-## Amounts on the deposit panel
-
-`swap.deposit_amount` is the ONLY amount a payer is ever told to send, in the
-pay-in token. `swap.fee.pay_in_fiat` / `payout_fiat` are fiat valuations that
-explain the spread (why the deposit exceeds the cart total); they are not
-instructions. For a stablecoin pegged to the fee currency (USDT, USDC) the
-packaged checkout expresses the breakdown in the token and never renders
-`pay_in_fiat` — "$50.03" under "50.05 USDC" reads as the same number with a
-typo. A custom UI gets the same rule from `createSwapFeeBreakdown(fee, swap)`;
-pass the swap, not just the fee.
-
-## Secrets
-
-`NWC_URI` and `LSC_URI_*` are server-only. Never put them in browser code,
-logs, assets, or tests. Boot fails closed if the NWC code advertises spend
-methods such as `pay_invoice` — mint a receive-only code
-(https://openreceive.org/get_a_nwc_code_to_receive_payments) instead of
-overriding.
-
-## Database tables
-
-```sh
-npx openreceive scaffold payments --orm prisma   # or drizzle | typeorm | sequelize | knex
-```
-
-emits the `openreceive_payments` + `openreceive_meta` migration for THIS app's
-database (Rails: `bin/rails generate openreceive:install`); run it through the
-app's normal migration workflow. The tables sit beside your models — no
-relations to them, no separate database, no Redis.
-
-## Verify, and test without a real wallet
-
-`npx openreceive doctor` checks the configuration and says what to fix.
-
-For tests, inject a fake wallet at the stable seams — `client` on
-`createOpenReceive` (any object with `preflight`, `makeInvoice`,
-`listTransactions`) or `config.nwc_client` in Rails — plus
-`StaticPriceProvider` for fiat pricing without a network. Your routes,
-persistence, reconcile, and `onPaid` then run the production code paths.
-Details: https://openreceive.org/guides/host-testing.md
-
-## Deeper documentation
-
-Fetch on demand — each URL is raw markdown:
-https://openreceive.org/guides/authorization.md ·
-https://openreceive.org/guides/storage.md ·
-https://openreceive.org/guides/api-reference.md ·
-https://openreceive.org/guides/security.md ·
-https://openreceive.org/openapi.yaml (the normative HTTP contract) ·
-https://openreceive.org/llms.txt (the full index)

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

@@ -1,224 +0,0 @@
-# OpenReceive agent directions (BTCPay Server)
-
-These directions describe OpenReceive 0.4.14.
-
-Connect a BTCPay Server store to a receive-only NWC wallet with the OpenReceive
-plugin, and optionally let payers pay BTCPay invoices with USDT, USDC, ETH or
-SOL. You do not need a copy of the OpenReceive source, and there is no
-application code to write: the plugin is configured through BTCPay's store UI
-or its Greenfield API, and the quickstart is appended to this file in full.
-
-This is the BTCPay plugin, not the Node or Rails library. Do not install
-`@openreceive/*` packages or the `openreceive-rails` gem into a BTCPay
-deployment, do not add `openreceive_payments` tables, and do not mount
-OpenReceive HTTP routes. BTCPay's invoices, checkout, webhooks and Greenfield
-API are the host; the plugin only supplies the Lightning backend and the swap
-rail.
-
-## What the plugin is
-
-A BTCPay Server plugin (`BTCPayServer.Plugins.OpenReceive`) that registers a
-Lightning connection-string handler for `type=openreceive;nwc=<NWC URI>`.
-Saving that string makes the NWC wallet the store's Lightning node: BTCPay
-mints every Lightning invoice in that wallet and its own `LightningListener`
-records the payments. The plugin never calls a NIP-47 `pay_*` method, so
-every send-side BTCPay feature (Lightning payouts, pull-payment refunds over
-Lightning, the send tab) is unavailable by design.
-
-The one required credential is a receive-only NWC code. A Lightning Swap
-Connect (LSC) code optionally adds server-side swaps: a provider order aimed at
-the invoice's existing BOLT11, tracked in the plugin's own table, with the
-refund path on the same checkout screen.
-
-## Step 0 — check the deployment before you change anything
-
-1. Confirm the BTCPay Server version is 2.4.4 or later (Server Settings →
-   About, or `GET /api/v1/server/info`). The plugin declares that minimum and
-   BTCPay refuses to load it below.
-2. Check whether the plugin is installed (the Plugins menu — the plug icon in
-   the top-right corner — under Installed Plugins, or the store navigation
-   shows an "OpenReceive" entry). If not, install it from the BTCPay plugin
-   directory (the same Plugins menu → Plugin Directory, search "openreceive",
-   then Install and Restart now), as the quickstart says; do not invent an
-   installer command.
-3. Check whether the store already has an OpenReceive connection:
-   `GET /api/v1/stores/{storeId}/openreceive/settings` returns
-   `lightningNodeIsOpenReceive`. If true, the wallet step is done — go to
-   swaps only if the user wants them.
-4. If no receive-only NWC code is available, stop and tell the user exactly
-   what to create:
-
-   > OpenReceive cannot mint an invoice without a receive-only NWC code. Get
-   > one at https://openreceive.org/get_a_nwc_code_to_receive_payments and
-   > paste it into Store → OpenReceive → Test connection, or hand it to me and
-   > I will set it through the Greenfield API.
-
-   Never print, log or echo the code; report only whether it is set. Never
-   paste a bare `nostr+walletconnect://` string into BTCPay's Lightning node
-   screen — that form is claimed by the Nostr plugin, without the receive-only
-   guard.
-5. If the user wants altcoin payments, ask for an LSC code from
-   https://openreceive.org/set_up_swap_provider. Do not wait for it: the
-   wallet works without it, and swaps switch on later with one settings change.
-
-Only then start the quickstart.
-
-## Non-negotiables
-
-- The connection string is `type=openreceive;nwc=<NWC URI>[;allow-spend=true]`
-  and nothing else. Set it through the setup page or
-  `PUT /api/v1/stores/{storeId}/openreceive/settings` with `nwcUri`, never by
-  editing BTCPay's Lightning node screen by hand.
-- Receive-only is required. A code that advertises `pay_invoice` or another
-  spend method is refused on save. The override (`allowSpendCapableWallet`,
-  the checkbox on the setup page) is the user's explicit choice; never tick it
-  to make a save succeed.
-- The wallet's network must match BTCPay's. A mismatch is a refusal, not a
-  warning.
-- The wallet must grant `make_invoice` and `list_transactions`.
-  `lookup_invoice` is optional; do not ask the user for a code that grants it.
-- Swaps require the store's Lightning node to be the OpenReceive connection.
-  Enabling swaps on a store using the internal node is refused
-  (`wallet_required`).
-- Swaps set the store's invoice expiration to 60 minutes when it is shorter,
-  and the plugin refuses to create a swap on an invoice with less than the
-  provider's window left. Do not lower the expiration below 45 minutes on a
-  swap-enabled store.
-- Top-up (amountless) invoices are unsupported on this backend. Do not
-  configure a point of sale or payment link that relies on them with this
-  wallet.
-- Secrets stay server-side. The NWC code and LSC code live in BTCPay's
-  database like every other BTCPay credential; never copy them into
-  screenshots, tickets, browser code or logs. The provider's order token never
-  leaves the server.
-- BTCPay's `LightningListener` is the settlement authority. Provider
-  `completed` is not payment; only the wallet reporting the Lightning invoice
-  settled is. Do not build anything that fulfils on a provider state.
-- There is no merchant-initiated refund of a settled Lightning payment. A swap
-  refund is a payer reclaiming a deposit that never converted, and only from
-  the `refund_required` provider state.
-
-## Verifying
-
-Store → OpenReceive → **Run a health check** (the doctor page) runs every probe now: connection, preflight,
-notifications, last scan, provider reachability, invoice expiration, swaps
-needing attention. On a regtest machine, `packages/dotnet/docker/up.sh` then
-`e2e.sh` in the OpenReceive repository proves the whole path end to end, and
-that is the only situation where cloning the repository is the right move.
-
-## More documentation
-
-Fetch one when the moment comes. Each is raw markdown, so a plain GET is
-enough; drop the `.md` for the same page a person would read.
-
-- https://openreceive.org/guides/btcpay-reference.md — every setting, route, swap state, doctor probe and log event of the plugin
-- https://openreceive.org/guides/security.md — why receive-only is the only wallet credential
-- https://openreceive.org/guides/lightning-swap-connect.md — what an LSC code actually is
-- https://openreceive.org/guides/automated-swaps.md — provider states, and what turning swaps on commits a merchant to
-- https://openreceive.org/guides/swap-refunds.md — the refund states; the route back is BTCPay's own invoice checkout page here
-- https://openreceive.org/guides.md — the index, if what you need is not above
-
-Questions, or a problem with the plugin 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
-
-Inlined verbatim so this file needs no network access — follow it once Step 0
-passes. The page it comes from is https://openreceive.org/guides/quickstart-btcpay.
-
-## BTCPay Server quickstart
-
-Requires BTCPay Server ≥ 2.4.4.
-
-The OpenReceive plugin makes a receive-only NWC wallet the Lightning node of a
-BTCPay store. BTCPay creates every Lightning invoice in that wallet. It records
-payments the same way it records any other payment. You can also let payers pay
-a BTCPay invoice with USDT, USDC, ETH or SOL through a Lightning Swap Connect
-provider. The swap pays into the same wallet. The store's internal node is
-never used.
-
-This is not the Node or Rails library. There are no hooks, no
-`openreceive_payments` table and no OpenReceive HTTP routes. BTCPay's own
-invoices, checkout, webhooks and Greenfield API do that work.
-
-### 1. Prerequisites
-
-- A BTCPay Server, version 2.4.4 or later, on any network (mainnet, testnet,
-  signet, regtest). The wallet must be on the same network.
-- A receive-only NWC code for the wallet you want to receive into
-  ([get one here](https://openreceive.org/get_a_nwc_code_to_receive_payments)).
-  The code must grant `make_invoice` and `list_transactions` and must not
-  advertise any spend method. `lookup_invoice` is optional.
-- Optionally, a Lightning Swap Connect (LSC) code from a
-  [swap provider](https://openreceive.org/set_up_swap_provider), if payers
-  should be able to pay with USDT, USDC, ETH or SOL.
-
-### 2. Install the plugin
-
-Sign in as a **server administrator**. If someone else hosts your server, ask
-them to install the plugin for you.
-
-**1. Open the Plugins menu.** It is the plug icon in the top-right corner.
-
-**2. Click Plugin Directory.**
-
-**3. Search for `openreceive`** and click the **OpenReceive** result.
-
-**4. Click Install in BTCPay Server.** Confirm when prompted, then click
-**Restart now** and wait for BTCPay to come back.
-
-At startup, BTCPay creates the plugin's two tables in its own Postgres
-database: `openreceive_invoices` and `openreceive_swaps`, in the schema
-`BTCPayServer.Plugins.OpenReceive`. Nothing else is created.
-
-To build the plugin from source instead, follow
-[the .NET workspace README](https://github.com/OpenReceive/openreceive/blob/master/packages/dotnet/README.md).
-
-### 3. Connect the wallet
-
-1. Select your store and open **OpenReceive** in its sidebar, under Wallets.
-2. Paste your receive-only NWC code. To see what the wallet supports first,
-   click **Test connection**.
-3. Click **Save NWC Code**.
-4. To turn swaps on, paste a Lightning Swap Connect code and click **Save swap
-   settings**.
-
-The page then shows **Wallet connected**. If you set up a provider, it also
-shows **Swaps on**. There is nothing else to configure. You never open BTCPay's
-Lightning node screen, and the plugin never reads the internal node.
-
-Screenshots for each of those steps, and for creating a first test invoice,
-are in the plugin's
-[README](https://github.com/OpenReceive/openreceive/blob/master/packages/dotnet/BTCPayServer.Plugins.OpenReceive/README.md).
-
-The plugin refuses to save a code whose wallet advertises a spend method such
-as `pay_invoice`. Create a receive-only code instead. If your wallet cannot
-make one, there is an override, but using it is a deliberate choice and the
-plugin logs it.
-
-Turning swaps on raises the store's invoice expiration to 60 minutes if it is
-shorter. A swap needs the invoice to stay open for at least 45 minutes.
-
-### 4. Check it
-
-Click **Run a health check** on the OpenReceive page. It runs every check
-right there:
-
-- the connection
-- the wallet preflight
-- payment notifications
-- the last wallet scan
-- the swap provider and its assets
-- the invoice expiration
-- swaps that need a human
-
-Each failing check comes with a link to the fix.
-
-The [BTCPay plugin reference](https://openreceive.org/guides/btcpay-reference.md) lists every setting,
-Greenfield route, swap state, log event and check. It also lists what the
-plugin does not support by design: every send-side feature, top-up invoices,
-and a bare `nostr+walletconnect://` string in BTCPay's Lightning node screen.