@openreceive/node 0.4.14 → 0.4.17

package/README.md

@@ -48,3 +48,14 @@ exposing payment instructions.
 - [Optional swaps](https://github.com/openreceive/openreceive/blob/master/docs/guides/automated-swaps.md)
 - [Test with a fake wallet](https://github.com/openreceive/openreceive/blob/master/docs/guides/host-testing.md)
 - [Deploy and reconcile payments](https://github.com/openreceive/openreceive/blob/master/docs/guides/deploying.md)
+
+## Agent skills
+
+Run `npx openreceive skills install` from your application after installing an
+OpenReceive server adapter. The offline copy ships in `@openreceive/node`, a
+server-adapter dependency. For a frontend-only project, 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.

package/dist/{chunk-GOWL2Y6H.js → chunk-LD7HMUY3.js}

@@ -28,6 +28,7 @@ var NWC_ERROR_CODE_ALIASES = {
   EXPIRED: "INVOICE_EXPIRED",
   FETCH_ERROR: "WALLET_UNAVAILABLE",
   FORBIDDEN: "RESTRICTED",
+  INFO_UNAVAILABLE_ERROR: "WALLET_UNAVAILABLE",
   INVOICE_NOT_FOUND: "NOT_FOUND",
   INVALID_PARAMETER: "INVALID_REQUEST",
   INVALID_PARAMETERS: "INVALID_REQUEST",
@@ -37,6 +38,7 @@ var NWC_ERROR_CODE_ALIASES = {
   NIP47_NETWORK_ERROR: "WALLET_UNAVAILABLE",
   NOSTR_NETWORK_ERROR: "WALLET_UNAVAILABLE",
   NOT_AUTHORIZED: "UNAUTHORIZED",
+  NOT_SENT_ERROR: "WALLET_UNAVAILABLE",
   NOT_SUPPORTED: "UNSUPPORTED_METHOD",
   NOTFOUND: "NOT_FOUND",
   PERMISSION_DENIED: "RESTRICTED",
@@ -45,6 +47,7 @@ var NWC_ERROR_CODE_ALIASES = {
   SERVICE_UNAVAILABLE: "WALLET_UNAVAILABLE",
   TIMED_OUT: "TIMEOUT",
   TIMEOUT_ERROR: "TIMEOUT",
+  TRANSPORT_ERROR: "WALLET_UNAVAILABLE",
   UNKNOWN_METHOD: "UNSUPPORTED_METHOD",
   UNSUPPORTED: "UNSUPPORTED_METHOD",
   UNSUPPORTED_ENCRYPTION_MODE: "UNSUPPORTED_ENCRYPTION",

package/dist/cli.js

@@ -2,13 +2,13 @@ import {
   createNwcReceiveClient,
   readLscConnectionsFromEnvironment,
   redactSecrets
-} from "./chunk-GOWL2Y6H.js";
+} from "./chunk-LD7HMUY3.js";
 
 // src/cli.ts
-import { existsSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, realpathSync, rmSync } from "node:fs";
 import { createRequire } from "node:module";
 import path2 from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import {
   formatInvalidNwcMessage,
   NwcUriParseError,
@@ -928,6 +928,8 @@ Commands:
   debug-report        Print the same diagnostics as a redacted support report
                       (alias of doctor; always exits 0).
   scaffold payments   Emit the openreceive_payments + openreceive_meta migration and wiring guide for your ORM.
+  skills install      Copy bundled agent skills into .agents/skills.
+                      --dir <path> selects another directory (e.g. .claude/skills).
 
 Options:
   -h, --help           Show this help.
@@ -965,6 +967,33 @@ async function runCli(options) {
         walletClientFactory: options.walletClientFactory
       });
     }
+    if (command === "skills") {
+      if (args[0] !== "install" || !(args.length === 1 || args.length === 3 && args[1] === "--dir" && args[2] && !args[2].startsWith("--"))) {
+        throw new Error("Usage: openreceive skills install [--dir <path>]");
+      }
+      const source = realpathSync(fileURLToPath(new URL("../skills/", import.meta.url)));
+      let target = path2.resolve(cwd, args[2] ?? ".agents/skills");
+      const names = ["integrate-openreceive", "debug-openreceive-payment"];
+      for (const name of names) {
+        if (!existsSync(path2.join(source, name, "SKILL.md"))) {
+          throw new Error(`Bundled skill missing: ${name}. Reinstall @openreceive/node.`);
+        }
+      }
+      mkdirSync(target, { recursive: true });
+      target = realpathSync(target);
+      if (target === source || target.startsWith(`${source}${path2.sep}`)) {
+        throw new Error("Choose a skills directory outside the installed package's bundle.");
+      }
+      for (const name of names) {
+        const destination = path2.join(target, name);
+        rmSync(destination, { recursive: true, force: true });
+        cpSync(path2.join(source, name), destination, { recursive: true });
+        stdout.write(`Wrote ${destination}
+`);
+      }
+      stdout.write("For Claude Code: openreceive skills install --dir .claude/skills\n");
+      return 0;
+    }
     if (command === "scaffold") {
       const [target = "help", ...scaffoldArgs] = args;
       if (target === "help" || target === "--help" || target === "-h") {
@@ -1047,6 +1076,7 @@ async function runDiagnostics(input) {
   }
   const lines = [
     `OpenReceive ${input.command}`,
+    "Agent skills: run `npx openreceive skills install`",
     `node: ${process.version}`,
     `cwd: ${input.cwd}`,
     "storage: payment-attempt rows live in the host database (no separate store)",

package/dist/index.js

@@ -19,7 +19,7 @@ import {
   summarizeReconcilePass,
   summarizeSwapProviderApiRequest,
   summarizeSwapProviderApiResponse
-} from "./chunk-GOWL2Y6H.js";
+} from "./chunk-LD7HMUY3.js";
 
 // src/index.ts
 import { OpenReceiveError as OpenReceiveError2 } from "@openreceive/core";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openreceive/node",
-  "version": "0.4.14",
+  "version": "0.4.17",
   "description": "Accept Bitcoin Lightning payments in Node.js with your own wallet and optional USDT, USDC, SOL and ETH swaps.",
   "keywords": [
     "bitcoin",
@@ -17,7 +17,7 @@
   "types": "./dist/index.d.ts",
   "dependencies": {
     "@getalby/sdk": "^8.0.3",
-    "@openreceive/core": "0.4.14"
+    "@openreceive/core": "0.4.17"
   },
   "bin": {
     "openreceive": "./bin/openreceive.mjs"

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

@@ -19,6 +19,12 @@ URL below is raw markdown — fetch it when the step needs it.
 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?
+bin/rails openreceive:doctor               # Rails
+manage.py openreceive_doctor               # Django
+openreceive doctor --app main:app           # FastAPI
+php artisan openreceive:doctor             # Laravel
+wp openreceive doctor                      # WordPress
+php bin/doctor                             # plain PHP: host script calling $engine->doctor()
 ```
 
 Each failing line states its own fix. `npx openreceive debug-report` prints the
@@ -32,7 +38,7 @@ same diagnostics redacted, always exit 0 — safe to share.
 | `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 |
+| "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`. Django: `manage.py openreceive_install <app> && manage.py migrate`. FastAPI: `openreceive scaffold payments --alembic --dialect <db>` (or `--sql`), then apply through the host workflow. Laravel: `php artisan openreceive:install && php artisan migrate`. Plain PHP: apply `OpenReceive\Storage\PaymentsSchema::statements($dialect)` through the host workflow. WordPress: check plugin activation/upgrades applied the tables. 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
@@ -51,7 +57,12 @@ same diagnostics redacted, always exit 0 — safe to share.
 - 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.
+  notifications worker: Rails `bin/rails openreceive:notifications`, Django
+  `manage.py openreceive_notifications`, FastAPI
+  `openreceive notifications --app main:app`, Laravel
+  `php artisan openreceive:notifications`, WordPress `wp openreceive notifications`,
+  or plain PHP's host script `php bin/notifications`. Node hosts run their
+  separate worker using the notifications API. No web-process timer is missing.
 - 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.
@@ -83,8 +94,13 @@ same diagnostics redacted, always exit 0 — safe to share.
 
 - 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).
+- Import `@openreceive/react/styles.css` or `@openreceive/elements/styles.css`
+  alongside the component registration. For standalone Django/Laravel/PHP,
+  serve both `openreceive-checkout.js` (as a module) and
+  `openreceive-checkout.css`. Django serves them from `static/openreceive/`
+  via `collectstatic`; Laravel/PHP serve the unpacked standalone assets from
+  the public directory. Check that both requests succeed and the custom
+  element is registered. Do not process the compiled stylesheet with Tailwind.
 - "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

package/skills/integrate-openreceive/SKILL.md

@@ -1,12 +1,13 @@
 ---
 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.
+  Integrate OpenReceive Bitcoin Lightning checkout and optional USDT, USDC,
+  SOL, and ETH swaps. Use for Node.js, Express, Fastify, Next.js, Rails,
+  Python, Django, FastAPI, Laravel, plain PHP, WordPress/WooCommerce,
+  React, Vue, Svelte, Angular, or plain HTML applications, or connecting
+  BTCPay Server to a receive-only NWC wallet. A configured swap provider
+  converts these payments to BTC over Lightning in the merchant's connected
+  wallet; asset and network availability depends on the provider.
 license: MIT
 ---
 
@@ -19,6 +20,10 @@ 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`).
 
+Optional swaps let customers pay with USDT, USDC, SOL, and ETH. A configured
+swap provider converts these payments to BTC over Lightning in the merchant's
+connected wallet; asset and network availability depends on the provider.
+
 ## Pick the stack, then follow its directions
 
 1. Identify the server stack of the application you are in.
@@ -28,6 +33,8 @@ code** (`NWC_URI`).
    - 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)
+   - Python, FastAPI: [references/fastapi.md](references/fastapi.md)
+   - Plain PHP: [references/php.md](references/php.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.
@@ -44,6 +51,9 @@ 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`.
+Django: `pip install "openreceive[django]"`; FastAPI:
+`pip install "openreceive[fastapi]"`; Laravel: `composer require openreceive/laravel`;
+plain PHP: `composer require openreceive/openreceive nyholm/psr7 nyholm/psr7-server`.
 
 ## The three server objects
 
@@ -108,25 +118,36 @@ overriding.
 
 ## Database tables
 
-```sh
-npx openreceive scaffold payments --orm prisma   # or drizzle | typeorm | sequelize | knex
-```
+Generate the two tables in the host's existing database:
 
-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.
+| Stack | Generate and apply |
+| --- | --- |
+| Node | `npx openreceive scaffold payments --orm <orm>`, then the app's normal migration command |
+| Rails | `bin/rails generate openreceive:install && bin/rails db:migrate` |
+| Django | `manage.py openreceive_install <app> && manage.py migrate` |
+| FastAPI | `openreceive scaffold payments --alembic --dialect <db>` (or `--sql`), then apply through the app's migration workflow |
+| Laravel | `php artisan openreceive:install && php artisan migrate` |
+| Plain PHP | Use `OpenReceive\Storage\PaymentsSchema::statements($dialect)` in the host's migration workflow, as in the PHP reference |
 
-## Verify, and test without a real wallet
+These emit `openreceive_payments` + `openreceive_meta`. The tables sit beside
+your models — no relations to them, no separate database, no Redis. WordPress
+and BTCPay manage installation through their plugins; follow their references.
 
-`npx openreceive doctor` checks the configuration and says what to fix.
+## Verify, and test without a real wallet
 
-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
+| Stack | Doctor | Test seam |
+| --- | --- | --- |
+| Node | `npx openreceive doctor` | `client` on `createOpenReceive` (`preflight`, `makeInvoice`, `listTransactions`), plus `StaticPriceProvider` |
+| Rails | `bin/rails openreceive:doctor` | `config.nwc_client`, `config.swap_providers`, `config.price_provider` |
+| Django | `manage.py openreceive_doctor` | `OPENRECEIVE["SERVICE"]`, a factory returning a `Service` built on `openreceive.testing` fakes |
+| FastAPI | `openreceive doctor --app main:app` | `nwc_client`, `price_provider`, `swap_providers` on `openreceive_router`, using `openreceive.testing` fakes |
+| Laravel | `php artisan openreceive:doctor` | Bind `ReceiveNwcClient`, `PriceProvider`, and `OpenReceiveServiceProvider::SWAP_PROVIDERS` in the container |
+| Plain PHP | `php bin/doctor` (host script calling `$engine->doctor()`) | Build `Service` with `OpenReceive\Testing\FakeWallet`, `FakeSwapProvider`, and `OpenReceive\Rates\StaticPriceProvider` |
+| WordPress | `wp openreceive doctor`, then `wp openreceive test-invoice <order id>` for a real invoice | Repository development: the documented Docker `compose.testkit.yml` override |
+| BTCPay | Follow the plugin reference's connection and checkout checks | Use the plugin's Docker test setup in its reference |
+
+The routes, persistence, reconciliation, and fulfillment hooks then run the
+production paths. Details: https://openreceive.org/guides/host-testing.md
 
 ## Deeper documentation
 

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (BTCPay Server)
 
-These directions describe OpenReceive 0.4.14.
+These directions describe OpenReceive 0.4.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/btcpay.md`), not through a summarizing tool: a summary drops steps.
 
 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
@@ -164,13 +164,17 @@ 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.

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Django)
 
-These directions describe OpenReceive 0.4.14.
+These directions describe OpenReceive 0.4.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/django.md`), not through a summarizing tool: a summary drops steps.
 
 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
@@ -366,17 +366,18 @@ Then add the app, point it at a host class, and mount the routes:
 INSTALLED_APPS += ["openreceive.django"]
 
 OPENRECEIVE = {
-    "HOST": "shop.openreceive_host.Host",   # the class with the three hooks (generated below)
+    "HOST": "shop.openreceive_host.Host",  # the class with the three hooks (generated below)
     "PRICE_CURRENCIES": ["USD"],
-    "RATE_LIMITING": False,                 # True for public web shops (see below)
-    "OPPORTUNISTIC_RECONCILE": True,        # or {"min_interval_seconds": …}; False only with your own worker
-    "DATABASE": "default",                  # the DATABASES alias that holds the two engine tables
+    "RATE_LIMITING": False,  # True for public web shops (see below)
+    "OPPORTUNISTIC_RECONCILE": True,  # or {"min_interval_seconds": …}; False only with your own worker
+    "DATABASE": "default",  # the DATABASES alias that holds the two engine tables
 }
 ```
 
 ```python
 # urls.py
 from django.urls import include, path
+
 urlpatterns += [path("openreceive/", include("openreceive.django.urls"))]
 ```
 
@@ -420,9 +421,9 @@ The generated host module explains this and shows the guarded transition:
 
 ```python
 def on_paid(self, settlement: PaymentSettlement) -> None:
-    claimed = Order.objects.filter(
-        pk=settlement.reference, state="awaiting_payment"
-    ).update(state="paid", paid_at=datetime.fromtimestamp(settlement.paid_at, tz=UTC))
+    claimed = Order.objects.filter(pk=settlement.reference, state="awaiting_payment").update(
+        state="paid", paid_at=datetime.fromtimestamp(settlement.paid_at, tz=UTC)
+    )
     if claimed == 0:
         return  # someone else already fulfilled it
 
@@ -450,7 +451,9 @@ instead:
 
 ```python
 def on_paid(self, settlement: PaymentSettlement) -> None:
-    order = Order.objects.select_for_update().filter(pk=settlement.reference).first()  # SELECT … FOR UPDATE
+    order = (
+        Order.objects.select_for_update().filter(pk=settlement.reference).first()
+    )  # SELECT … FOR UPDATE
     if order is None or order.state != "awaiting_payment":
         return
     order.state = "paid"
@@ -533,8 +536,9 @@ from openreceive.server import HookContext
 from openreceive.storage import PaymentSettlement
 
 from shop.models import Order  # YOUR model — it could be named anything. OpenReceive
-                               # never sees it or touches its table; these hooks are the
-                               # only bridge between the engine and your data.
+# 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`
@@ -564,8 +568,11 @@ class Host:
         order = Order.objects.filter(pk=reference).first()
         if order is None:
             return None
-        return {"currency": "USD", "value": str(order.total),
-                "description": f"{order.items.count()} items"}
+        return {
+            "currency": "USD",
+            "value": str(order.total),
+            "description": f"{order.items.count()} items",
+        }
 
     # Runs inside the settlement transaction, only for the order's first settled
     # attempt. The WHERE clause is the lock: a second fulfillment path of yours

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (FastAPI)
 
-These directions describe OpenReceive 0.4.14.
+These directions describe OpenReceive 0.4.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/fastapi.md`), not through a summarizing tool: a summary drops steps.
 
 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

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Fastify)
 
-These directions describe OpenReceive 0.4.14.
+These directions describe OpenReceive 0.4.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/fastify.md`), not through a summarizing tool: a summary drops steps.
 
 Add OpenReceive to a Fastify application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the packages are on npm, and

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Laravel)
 
-These directions describe OpenReceive 0.4.14.
+These directions describe OpenReceive 0.4.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/laravel.md`), not through a summarizing tool: a summary drops steps.
 
 Add OpenReceive to a Laravel application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the package is on Packagist

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Next.js)
 
-These directions describe OpenReceive 0.4.14.
+These directions describe OpenReceive 0.4.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/next.md`), not through a summarizing tool: a summary drops steps.
 
 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

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Node.js)
 
-These directions describe OpenReceive 0.4.14.
+These directions describe OpenReceive 0.4.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/node.md`), not through a summarizing tool: a summary drops steps.
 
 Add OpenReceive to a Node application — the app you are already working in. You
 do not need a copy of the OpenReceive source: the packages are on npm, and the

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (PHP)
 
-These directions describe OpenReceive 0.4.14.
+These directions describe OpenReceive 0.4.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/php.md`), not through a summarizing tool: a summary drops steps.
 
 Add OpenReceive to a PHP application — the app you are already working in. You
 do not need a copy of the OpenReceive source: the engine is on Packagist

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Rails)
 
-These directions describe OpenReceive 0.4.14.
+These directions describe OpenReceive 0.4.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/rails.md`), not through a summarizing tool: a summary drops steps.
 
 Add OpenReceive to a Rails application — the app you are already working in. You
 do not need a copy of the OpenReceive source: the gem is on RubyGems, the

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

@@ -1,79 +1,165 @@
 # OpenReceive agent directions (WordPress + WooCommerce)
 
-These directions describe OpenReceive 0.4.14.
+These directions describe OpenReceive 0.4.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/woocommerce.md`), not through a summarizing tool: a summary drops steps.
+
+Install and configure the OpenReceive payment gateway in the WooCommerce store
+you are working in. Preserve its theme, checkout, customer accounts, order
+model and prices. The plugin bundles the PHP engine and checkout assets: do not
+install npm or Composer packages on the WordPress server, and do not clone the
+OpenReceive repository unless the release download in Step 1 fails.
+
+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
+customers pay with USDT, USDC, ETH or SOL instead; the provider converts the
+payment to BTC over Lightning in the merchant's connected wallet. Available
+assets and networks depend on the provider.
+
+Run every `wp` command below where this store's WP-CLI runs. When WordPress
+runs in Docker Compose, prefix it with the service that has WP-CLI, for
+example `docker compose run --rm -T cli wp …` or
+`docker compose exec -T wordpress wp …`. `-T` passes stdin through. If the
+store has no WP-CLI at all (managed hosting without a shell), say so and walk
+the user through the quickstart's admin screens instead.
+
+## Step 0 — ask for the two codes, one question at a time
+
+Before anything else, check one thing: whether OpenReceive is already
+installed (`wp plugin is-active openreceive`). If it is, run
+`wp openreceive doctor`. It prints `NWC_URI: set` or `unset` (likewise
+`LSC_URI_PRIMARY`), never the values. A code that is already set is not asked
+for again; if both are set, skip to `wp openreceive configure --enable` at
+the end of Step 2.
+
+Otherwise your next action is a question to the user. Do not install the
+plugin, edit Docker files or search anywhere else before asking it. Do not
+read wp-config.php, deploy config, container environments or other projects
+looking for a code: a new store has neither code yet.
+
+The user never runs a command and never edits a file. They paste each code
+into this chat; you store it. That is the supported path: do not ask them to
+run the save command themselves, and do not tell them to revoke or replace a
+code because it was pasted here. Ask one question per message.
+
+1. **First message — the NWC code, and nothing else.**
+
+   > 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.
+
+2. **When they paste it.** If it does not start with `nostr+walletconnect://`,
+   ask them to copy the receive-only code again. Otherwise do not repeat it:
+   reply only that you have it, then ask the next question. You store it in
+   Step 2.
+3. **Second message — swaps.** If the user asked for stablecoins, USDT, USDC,
+   ETH, SOL, altcoins or "crypto" (as in "Bitcoin and stablecoin payments"),
+   this message IS the walkthrough below: do not skip it, and do not ask yes
+   or no first. Otherwise ask whether customers should also be able to pay
+   with USDT, USDC, ETH or SOL, then give the walkthrough. 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. Swaps are now on,
+   so keep the route back (the swap non-negotiable below).
+
+Do not report setup as complete until the NWC code is saved, and the LSC code
+is saved or the user said "Bitcoin only". Never invent a placeholder code.
+
+## Step 1 — install the plugin
+
+Install the plugin built for this release. Never install the GitHub
+source-code ZIP or a ZIP from an older release:
 
-Install and configure the OpenReceive gateway in the existing WooCommerce
-store. Preserve its theme, checkout, customer accounts, order model and prices.
-The plugin bundles the PHP engine and checkout assets; the merchant does not
-install npm or Composer packages on the WordPress server.
+```sh
+wp plugin install https://github.com/OpenReceive/openreceive/releases/download/v0.4.17/openreceive-wordpress-0.4.17.zip --activate
+```
+
+It needs WooCommerce active, and PHP 8.2+ with GMP and sodium in BOTH the web
+PHP and the WP-CLI PHP. On the official `wordpress` and `wordpress:cli` Docker
+images, activation fails with "OpenReceive requires the PHP sodium and GMP
+extensions": add GMP to both images as "Enable GMP in both PHP runtimes" below
+says, rebuild both, then install again. If the URL answers 404, build the same
+tag as "Get the installable archive" below says.
+
+## Step 2 — store the codes, then enable the gateway
+
+Store each code yourself, one per command, and never as a shell argument:
 
-## Step 0 — inspect configuration
+1. Write the code with your file-editing tool, not a shell command (no
+   `echo`, `printf` or heredoc), to a new file outside the repository, such
+   as `/tmp/openreceive-code`.
+2. Run `wp openreceive configure --nwc-uri=- < /tmp/openreceive-code`. In
+   Docker: `docker compose run --rm -T cli wp openreceive configure --nwc-uri=- < /tmp/openreceive-code`.
+   For the LSC code, use `--lsc-uri-primary=-`.
+3. Delete the file (`rm /tmp/openreceive-code`), whether the command passed
+   or not.
 
-Check WordPress, WooCommerce and PHP versions, GMP and sodium availability,
-whether the plugin is installed, and whether the Doctor panel reports the
-receive-only NWC credential as set. Never display its value. For a real store,
-ask the merchant to configure a receive-only wallet if none is available.
-For repository development, use the Docker demo's explicit testkit override.
+The command runs the receive-only wallet preflight, encrypts the code and
+prints only "Settings saved; wallet preflight passed."; a failure keeps the
+previous settings. If it reports spend methods such as `pay_invoice`, ask the
+user for a receive-only code again. Never turn on the spend-capable override.
+`wp wc payment_gateway` and WooCommerce REST writes of these fields are
+rejected on purpose; do not use them. A code set as a constant in
+wp-config.php wins over the stored one and changes only through the host's
+secret workflow.
 
-Upload a built plugin archive, not a zip of the source directory. The plugin
-has not yet been accepted into the WordPress.org directory. Configuration and
-the complete quickstart follow below.
+Then run `wp openreceive configure --enable` and `wp openreceive doctor`.
+Doctor names any failed check and exits nonzero; fix it before going on.
 
-The plugin owns only its payment-attempt tables in the WordPress database.
-WooCommerce owns orders, totals, stock and email. Do not add an external
-idempotency store, payment database, browser wallet credentials or custom
-fulfillment implementation. Guest return links use WooCommerce's order key;
-the plugin verifies it before issuing an expiring order-bound cookie.
+## Step 3 — mint a test invoice
+
+Create a pending test order that pays with OpenReceive, then mint its
+Lightning invoice from the terminal:
+
+```sh
+wp wc shop_order create --user=<admin user id> --payment_method=openreceive \
+  --line_items='[{"product_id":<product id>,"quantity":1}]' --porcelain
+wp openreceive test-invoice <order id>
+```
 
-Run `wp openreceive doctor` after configuration. Use the documented scheduled
-reconciliation or optional notifications command for offline settlement.
-Manual merchant refunds and provider-managed payer swap refunds are separate
-flows; a receive-only NWC wallet cannot send payments.
+`test-invoice` goes through the same checkout route as the order-pay page. It
+prints the amount in sats, the BOLT11 invoice and the order-pay link. Give the
+user that link: it opens the checkout with the configured methods and resumes
+this same invoice. Ask them to pay only if they want a real settlement test,
+and tell them the test order is theirs to delete.
+
+## Non-negotiables
+
+- Never print, log or commit a code, never put one in a shell argument, and
+  never write one into source files, wp-config.php or browser code. Doctor's
+  set/unset is all you report.
+- Receive-only NWC is required. Never turn on the spend-capable override to
+  get past the preflight.
+- The plugin owns only its payment-attempt tables in the WordPress database.
+  WooCommerce owns orders, totals, stock and email. Do not add an external
+  idempotency store, payment database or custom fulfillment code.
+- IF SWAPS ARE ON, KEEP THE ROUTE BACK. A deposit that arrives short or late
+  becomes refundable, and the customer claims it later on the same order-pay
+  link (guests return with the order key in it). Keep order-pay links
+  reachable, and keep the plugin installed while swap orders may still need a
+  refund. https://openreceive.org/guides/swap-refunds.md
+- A receive-only wallet cannot send merchant refunds. Refund a settled
+  payment manually from the wallet.
+- Settlement runs on checkout requests and an every-minute scheduled job. On a
+  low-traffic store, run WordPress scheduled work from a system cron;
+  `wp openreceive notifications` is an optional long-running worker.
 
 ## Further reading
 
-- [Express Quickstart (Node)](https://openreceive.org/guides/quickstart-node.md)
-- [Fastify Quickstart](https://openreceive.org/guides/quickstart-fastify.md)
-- [FastAPI Quickstart](https://openreceive.org/guides/quickstart-fastapi.md)
-- [Django Quickstart](https://openreceive.org/guides/quickstart-django.md)
-- [Next.js Quickstart](https://openreceive.org/guides/quickstart-next.md)
-- [Rails Quickstart](https://openreceive.org/guides/quickstart-rails.md)
-- [PHP Quickstart (plain PHP)](https://openreceive.org/guides/quickstart-php.md)
-- [Laravel Quickstart](https://openreceive.org/guides/quickstart-laravel.md)
-- [BTCPay Server Quickstart](https://openreceive.org/guides/quickstart-btcpay.md)
-- [BTCPay Plugin Reference](https://openreceive.org/guides/btcpay-reference.md)
-- [Node ORM Recipes](https://openreceive.org/guides/node-orms.md)
-- [Authorization](https://openreceive.org/guides/authorization.md)
-- [Rate Limiting](https://openreceive.org/guides/rate-limiting.md)
-- [Frontend Checkout](https://openreceive.org/guides/frontend-checkout.md)
-- [Checkout UX](https://openreceive.org/guides/checkout-ux.md)
-- [Headless Checkout](https://openreceive.org/guides/headless-checkout.md)
+- [WordPress + WooCommerce Quickstart](https://openreceive.org/guides/quickstart-woocommerce.md)
 - [Automated Swaps](https://openreceive.org/guides/automated-swaps.md)
 - [Swap Refunds](https://openreceive.org/guides/swap-refunds.md)
 - [Lightning Swap Connect URI](https://openreceive.org/guides/lightning-swap-connect.md)
-- [Environment Variables](https://openreceive.org/guides/environment-variables.md)
-- [Payment Storage](https://openreceive.org/guides/storage.md)
-- [Deploying OpenReceive](https://openreceive.org/guides/deploying.md)
-- [Testing Your OpenReceive Integration](https://openreceive.org/guides/host-testing.md)
-- [API Reference](https://openreceive.org/guides/api-reference.md)
 - [Security](https://openreceive.org/guides/security.md)
-- [Provider Registry](https://openreceive.org/guides/provider-registry.md)
 - [Price Feeds](https://openreceive.org/guides/price-feeds.md)
-- [React Material UI Recipe](https://openreceive.org/guides/react-material-ui-recipe.md)
-- [Flask Recipe](https://openreceive.org/guides/flask-recipe.md)
-- [Writing Your Own Checkout Route](https://openreceive.org/guides/custom-checkout-route.md)
-- [Agent Directions: Node.js](https://openreceive.org/guides/agent-directions-node.md)
-- [Agent Directions: Fastify](https://openreceive.org/guides/agent-directions-fastify.md)
-- [Agent Directions: FastAPI](https://openreceive.org/guides/agent-directions-fastapi.md)
-- [Agent Directions: Django](https://openreceive.org/guides/agent-directions-django.md)
-- [Agent Directions: Next.js](https://openreceive.org/guides/agent-directions-next.md)
-- [Agent Directions: Rails](https://openreceive.org/guides/agent-directions-rails.md)
-- [Agent Directions: PHP](https://openreceive.org/guides/agent-directions-php.md)
-- [Agent Directions: Laravel](https://openreceive.org/guides/agent-directions-laravel.md)
-- [Agent Directions: BTCPay Server](https://openreceive.org/guides/agent-directions-btcpay.md)
-- [WordPress + WooCommerce Quickstart](https://openreceive.org/guides/quickstart-woocommerce.md)
-
-- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+- [Payment Safety Upgrade](https://openreceive.org/guides/payment-safety-upgrade.md)
 
 ---
 
@@ -84,6 +170,10 @@ passes. The page it comes from is https://openreceive.org/guides/quickstart-wooc
 
 ## WordPress + WooCommerce quickstart
 
+The [WordPress integration entry point](https://openreceive.org/integrations/wordpress)
+redirects to the WooCommerce integration, which uses this same guide and agent
+directions. OpenReceive checkout on WordPress requires WooCommerce.
+
 Activate WooCommerce first. Then install the built OpenReceive plugin zip
 through **Plugins → Add New → Upload Plugin**. You cannot upload the source
 directory as-is. It needs a build first. The plugin is not yet submitted to
@@ -96,15 +186,16 @@ database or application.
 
 ### Get the installable archive
 
-If the [OpenReceive GitHub release](https://github.com/OpenReceive/openreceive/releases)
-you picked lists `openreceive-wordpress-<version>.zip`, use that file. The GitHub
-source-code zip is not the plugin archive. If the release has no built zip yet,
-build one on a development machine with Node 22+, PHP 8.2+, Composer and WP-CLI:
+Download [openreceive-wordpress-0.4.17.zip](https://github.com/OpenReceive/openreceive/releases/download/v0.4.17/openreceive-wordpress-0.4.17.zip)
+from the matching release. Historical releases may lack this asset. If that exact
+URL returns 404, build the same tag below; never silently install an older ZIP.
+The GitHub source-code ZIP is not an installable plugin. On a development machine
+with Node 22+, PHP 8.2+ with GMP/sodium, Composer and WP-CLI:
 
 ```sh
 git clone https://github.com/OpenReceive/openreceive.git
 cd openreceive
-git checkout <release-tag>
+git checkout v0.4.17
 npm ci
 npm run build:packages
 composer install --working-dir=packages/php/wordpress
@@ -116,6 +207,40 @@ needs WP-CLI on `PATH`. Otherwise, set `OPENRECEIVE_WP_CLI` to the absolute path
 of its phar. Your WordPress server needs neither Node nor Composer. The built
 plugin already bundles its dependencies and checkout assets.
 
+### Enable GMP in both PHP runtimes
+
+GMP is required by the bundled elliptic-curve dependency. Enable it for both
+web PHP (Apache/FPM) and the PHP executable running WP-CLI. Installing it in
+only the WordPress container does not update a separate CLI container.
+
+For Debian-based official PHP/WordPress images, add to **each** Dockerfile:
+
+```dockerfile
+USER root
+RUN apt-get update && apt-get install -y --no-install-recommends libgmp-dev \
+    && docker-php-ext-install gmp \
+    && rm -rf /var/lib/apt/lists/*
+```
+
+For Alpine-based PHP/CLI images:
+
+```dockerfile
+USER root
+RUN apk add --no-cache gmp \
+    && apk add --no-cache --virtual .gmp-build $PHPIZE_DEPS gmp-dev \
+    && docker-php-ext-install gmp \
+    && apk del .gmp-build
+```
+
+Restore the base image's original runtime user after installing extensions.
+Rebuild and recreate both containers. On Debian/Ubuntu hosts, install the GMP
+package matching the active PHP version (for example `php8.2-gmp` for PHP 8.2),
+then restart that version's web PHP service. Verify `php --ri gmp` and
+`wp openreceive doctor` for CLI, and the gateway Doctor panel for web PHP.
+On managed WordPress hosting, ask the host to enable GMP and sodium in both
+runtimes; if they cannot, this plugin cannot run there. Do not use Composer's
+`--ignore-platform-reqs` to bypass the requirements.
+
 ### Configure the wallet
 
 1. Open **WooCommerce → Settings → Payments → OpenReceive**.
@@ -134,6 +259,40 @@ providers, you can also set the `OPENRECEIVE_LSC_URI_PRIMARY` and
 `OPENRECEIVE_LSC_URI_BACKUP` constants. Never put these values in browser code
 or logs.
 
+#### Configure through WP-CLI
+
+`wp openreceive configure` accepts one credential at a time from stdin. Feed
+stdin through your secret manager or an existing protected file, never a code
+literal in the command line:
+
+```sh
+wp openreceive configure --nwc-uri=- < /secure/path/wallet-code
+wp openreceive configure --lsc-uri-primary=- < /secure/path/swap-code
+wp openreceive configure --enable
+wp openreceive doctor
+```
+
+Omit the swap command for Bitcoin-only checkout. `--lsc-uri-backup=-` adds a
+backup. These commands share admin preflight and encrypted storage. Credential
+flags accept only `-`; blank input leaves settings intact. Generic WooCommerce
+REST and `wp wc payment_gateway` credential updates are rejected. `doctor`
+reports the failed check with credentials redacted and exits nonzero on failure.
+The default payment title becomes “Bitcoin & crypto (OpenReceive)” with swaps;
+a customized title is preserved.
+
+To check checkout from the terminal, mint an invoice for an unpaid order whose
+payment method is OpenReceive:
+
+```sh
+wp wc shop_order create --user=<admin user id> --payment_method=openreceive \
+  --line_items='[{"product_id":<product id>,"quantity":1}]' --porcelain
+wp openreceive test-invoice <order id>
+```
+
+`test-invoice` uses the same checkout route as the order-pay page. It prints the
+amount in sats, the Lightning invoice and the order-pay link, which opens the
+checkout on that invoice. Delete the test order when you are done.
+
 ### Checkout and settlement
 
 Both WooCommerce checkout blocks and classic checkout send the customer to the