Add a doctor command verifying the gateway configuration end to end

CLAUDE.md

@@ -115,6 +115,12 @@ fetches the route after page load, so the order page never blocks on Quickpay; f
 inline retry notice (HTTP 502). The controller resolves the api key from the payment's own gateway
 config and fetches via `Quickpay/ClientFactory`.
 
+`Command/DoctorCommand` (`setono:sylius-quickpay:doctor`) machine-checks the README's Troubleshooting
+section per configured gateway: api key ping, private key HMAC self-test (`CallbackValidator`), agreement
+existence (`GET agreements/{id}`, failing open on permission errors), order prefix length + cross-gateway
+uniqueness, and notify-route registration; `--live` creates a money-less test payment and attempts the
+link PUT to surface the missing-permission 403. Non-zero exit on any failed check; warnings don't fail.
+
 `Command/ReconcilePaymentsCommand` (`setono:sylius-quickpay:reconcile-payments`) is the backstop for
 callbacks that never arrive: `Provider/PendingPaymentProvider` queries non-final Quickpay payments with
 a `quickpayPaymentId`, the command polls each via `GetHumanStatus` and applies the matching transition

README.md

@@ -299,6 +299,24 @@ composer check-style   # coding standards
 For manual testing, use the credit card numbers from the
 [Quickpay test data](https://learn.quickpay.net/tech-talk/appendixes/test/#test-data).
 
+## Checking your configuration
+
+The plugin ships a doctor that runs the checks otherwise surfacing as support cases — try it first
+when something misbehaves, and after every configuration change:
+
+```bash
+bin/console setono:sylius-quickpay:doctor          # read-only
+bin/console setono:sylius-quickpay:doctor --live   # also probes the payment link permission
+```
+
+For every configured Quickpay gateway it verifies the api key against Quickpay, self-tests the private
+key's checksum computation, checks that a configured agreement id exists on the account, and validates
+the order prefix length — plus, across gateways, that no two share a prefix, and that the notify route
+is registered at all. With `--live` it also creates a money-less test payment and attempts the payment
+link `PUT` the checkout depends on, catching a missing *Create or update payment link* permission before
+a customer does (the test payment remains visible on the account; it never carries money). The command
+exits non-zero when any check fails, so it can run in CI or cron.
+
 ## Upgrading from 1.x
 
 See [UPGRADE-2.0.md](UPGRADE-2.0.md) for the full list of changes an upgrading store has to make —
@@ -307,6 +325,8 @@ behavioral changes around refunds and callbacks.
 
 ## Troubleshooting
 
+Run [the doctor](#checking-your-configuration) first — it detects every case below.
+
 - `Not authorized: Not authorized to PUT /payments/:id/link`
   at a `/payment/authorize/...` url:
 

UPGRADE-2.0.md

@@ -159,6 +159,10 @@ if you make those and want the store to notice. The README's *Callbacks* section
 - **New: a reconciliation command.** `setono:sylius-quickpay:reconcile-payments` polls Quickpay for
   payments stuck in a non-final state — e.g. because a callback never arrived — and applies the
   matching payment transition. See the README for options and a suggested cron cadence.
+- **New: a doctor command.** `setono:sylius-quickpay:doctor` verifies every configured gateway —
+  api key, private key self-test, agreement existence, order prefix length and uniqueness, and the
+  notify route — and with `--live` probes the payment link permission. See the README's *Checking
+  your configuration* section.
 - **New: Quickpay's fraud signals are surfaced.** The admin operation history shows a *Fraud suspected*
   badge, the reconciliation command gains a `--fraud-suspected` report mode, and an opt-in
   `fraud.block_capture` config flag skips the automatic capture on completion for fraud suspected