Consolidate 14 open Mintlify docs PRs (#19, #20, #21, #22, #24-#33)

[A1igator]

Summary

Consolidates all 14 open Mintlify bot PRs into a single PR for review. Merged oldest-first with --no-ff -X theirs so each PR's intent is preserved as a discrete merge commit and later PRs supersede earlier ones where they overlap.

Consolidated PRs

#	Title
#19	Update SDK docs for @x402r/sdk API and new chain support
#20	Sync SDK docs with contracts v3 API
#21	Replace refundable() with forwardToArbiter() in SDK docs
#22	Add delivery protection operator docs, fix marketplace operator signature
#24	Add forwardToArbiter docs and named address constants
#25	Document DeliveryProtectionOperator preset exports
#26	Update delivery protection SDK docs for v2
#27	Remove ArbiterRegistry references from SDK docs
#28	Add ERC-8004 plugin docs to SDK reference
#29	Update SDK docs to match @x402r/sdk 0.2.x API
#30	Add ERC-8004 helpers and identity.check() SDK docs
#31	Fix broken internal links in cursor AI tools guide
#32	Add @x402r/cli documentation
#33	Document commerce-payments v1 addresses, remove SKALE Base

Conflict resolutions

The V2 SDK Getting Started rewrite (#23) landed on main after most of these PRs were opened, so several conflicts had to be resolved:

• sdk/installation.mdx — V2 rewrite intentionally deleted this file. Kept the deletion; dropped PR Update SDK docs for @x402r/sdk API and new chain support #19, Sync SDK docs with contracts v3 API #20, and Add forwardToArbiter docs and named address constants #24 modifications.
• sdk/helpers/refundable.mdx — PR Replace refundable() with forwardToArbiter() in SDK docs #21 deletes this page (replaces with forward-to-arbiter.mdx). Accepted the deletion; later PRs that modified refundable.mdx (PR Add forwardToArbiter docs and named address constants #24) had their refundable-touching parts dropped.
• docs.json — V2 rewrite kept sdk/helpers/refundable in nav. PR Replace refundable() with forwardToArbiter() in SDK docs #21's theirs-strategy merge added forward-to-arbiter but the V2 entry for refundable was preserved as a dangling reference. Removed in the final fix commit so the Mintlify build doesn't fail.
• All other content conflicts — resolved with -X theirs (incoming Mintlify PR wins). Newer PRs in the chronological merge order override older PRs where they touch the same lines.

Verification

• python3 -m json.tool docs.json — valid JSON
• All deleted-file references checked: no remaining links to sdk/installation or sdk/helpers/refundable
• Diff stat: 29 files changed, ~2,332 insertions, ~2,091 deletions

Next steps (for reviewer)

1. Skim merge commits in order to see what each upstream PR contributed.
2. After merging, close PRs Update SDK docs for @x402r/sdk API and new chain support #19-Add delivery protection operator docs, fix marketplace operator signature #22 and Add forwardToArbiter docs and named address constants #24-Document commerce-payments v1 addresses, remove SKALE Base #33 with a comment pointing here.
3. Run npx mint dev locally to verify rendering before merging.

[vraspar]

Fifth pass — fix verification + remaining items

Verified 524a0f5 and c1dc43d against the four-round audit checklist (38 items): 37 PASS, 1 PARTIAL, 2 correctly UNCHANGED (license + audits pending separate review).

The bonus authCapture → auth-capture rename held — zero stale 'authCapture' strings in docs/, zero stale @x402r/evm/authCapture/ import paths, error codes correctly renamed to invalid_auth_capture_*, and the upstream scheme package actually has src/auth-capture/{server,client,facilitator}/ with package.json exports for ./auth-capture/server and ./auth-capture/client. Was the most likely source of breakage; it held.

One nit (2-line fix)

contracts/examples.mdx:532,604 still have inline comments // No refunds next to refundPreActionCondition: '0x0000...'. Since address(0) is default-allow, these are inconsistent with the L458 voidPreActionCondition comment that you correctly updated to // default-allow in 524a0f5. Two-line sweep to mirror.

Still needing action — not blocking but worth flagging

These were noted in the audit as needing human decision or cross-repo work — listing here so they don't get lost in the merge.

1. contracts/license.mdx legal review. The "no deploy outside factories" restriction on L46-57 isn't in the LICENSE file's literal text. Either amend LICENSE with an Additional Use Grant (factory-deploy carve-out), or rewrite the page to match the literal BUSL terms. Needs a product/legal call before code fix — that's why the file was correctly left untouched in this PR.

2. Companion SDK PR for helpers upstream drift. x402r-sdk/packages/helpers/src/forward-to-arbiter.ts:36 and helpers/README.md:17 still reference the wrong class name AuthCaptureServerScheme. Docs side is now correct; SDK side will compile (the symbol's local), but consumers following the README pattern will hit a missing export against @x402r/evm. Worth a small follow-up PR to align both repos.

3. contracts/audits.mdx provenance. The audit counts ("Spearbit 2 audits", "Coinbase Protocol Security 3 audits") aren't verifiable from this workspace (no audits/ directory, no audit-report links). Two options:

• Add an audits/ directory to the contracts repo with PDF links / commit-pinned report URLs
• Restructure the page to defer to the upstream base/commerce-payments audit history with a single link-out

Lower priority than 1-2 but worth deciding before the Resources tab goes public.

4. Gas-costs regen cadence (open question). c1dc43d pinning bb188dbc + the forge test command is exactly right for a snapshot. Open question: should a CI job re-run the benchmark and open a PR when numbers drift past a threshold, or is manual regen the policy? Just noting — no action required if manual is intentional.

---

Pending those four, the PR looks ready from a code-accuracy + IA standpoint. Merge call when you're ready.

[A1igator]

Re: fifth-pass item 2 (companion SDK / client drift) — the client side just got upstreamed, so the docs now reference it directly rather than the @x402r/evm helper.

Landed in e419b0b:

• The client half of the auth-capture scheme now ships in the x402 monorepo as AuthCaptureEvmScheme on the @x402/evm/auth-capture/client subpath (@x402/evm v2.14.0). It's pure signing: reads the requirement's extra, reconstructs the PaymentInfo struct, derives the payer-agnostic nonce, and emits the ERC-3009 (default) or Permit2 payload.
• x402-integration/auth-capture/wire-format.mdx — added a Signing the payload (client) section above the EIP-3009/Permit2 payload blocks, showing the canonical new x402Client() + client.register('eip155:*', new AuthCaptureEvmScheme(account)) + wrapFetchWithPayment(fetch, client) flow. Matches the upstream client example field-for-field.
• x402-integration/auth-capture/index.mdx — References now link the upstream client implementation alongside the x402r-scheme reference impl.

npx mintlify@latest broken-links still passes.

Scope note: this covers the client. The remaining forward-to-arbiter.ts / helpers/README.md drift you flagged is server-side (@x402r/evm/auth-capture/server, AuthCaptureEvmScheme), which hasn't been upstreamed yet — upstream ships client-only for now, server and facilitator follow later. Those docs already use the correct server names; the SDK-repo helper rename stays a separate follow-up.

[A1igator]

Status on the rest of the fifth-pass review (beyond the client item above):

• Nit — contracts/examples.mdx "No refunds" comments ✅ Fixed in 252d6a6. refundPreActionCondition: address(0) is default-allow (anyone can call refund()), not "no refunds". Mirrored the void() default-allow wording. Caught a third instance (line 673, "No post-delivery refunds") with the same defect and swept it too.

Remaining items are decisions/cross-repo work, not doc fixes, so still open:

• 1. license.mdx legal review — unchanged, needs the product/legal call on factory-deploy carve-out vs literal BUSL. Left untouched on purpose.
• 2. Companion SDK helpers drift — docs side resolved (see comment above; client upstreamed). The forward-to-arbiter.ts / helpers/README.md rename in x402r-sdk is still a separate follow-up.
• 3. audits.mdx provenance — still needs the audit-dir-vs-link-out decision before the Resources tab goes public.
• 4. Gas-costs regen cadence — open question (CI vs manual), no action taken since manual is the current intent.

broken-links passes.

[A1igator]

Update on the remaining fifth-pass items 3 and 4:

• 3. audits.mdx provenance ✅ Restructured in 1782321 to defer to upstream. The page now links Base's canonical commerce-payments audits/ directory and the README Security Audits section, which host the dated report PDFs (3 Coinbase Protocol Security + 2 Spearbit). The unsourced counts are gone; the x402r-specific unaudited disclosure stays intact.

• 4. Gas-costs cadence ✅ Went with CI, not manual. Added a gas-docs-drift workflow in x402r-contracts (PR #38 there) that re-runs GasBenchmark.t.sol weekly + on main src/test changes, snapshots a committed baseline, and opens a tracking issue when numbers drift so this page and its pinned commit get refreshed. gas-costs.mdx now notes the CI check and adds an upstream commerce-payments escrow reference for the baseline the x402r figures build on.

• 1. license.mdx Left as-is per direction, no rewrite.

broken-links passes.

[A1igator]

Consolidated status across the review passes

Everything actionable from the audits is now landed or wired up. Recap of what changed since the last comment:

Docs (this PR)

• Client scheme upstreamed (e419b0b) — auth-capture wire-format now documents the canonical client flow via @x402/evm/auth-capture/client (AuthCaptureEvmScheme on an x402Client), and the scheme References link the upstream implementation.
• contracts/examples.mdx nit (252d6a6) — the misleading // No refunds comments are fixed; refundPreActionCondition: address(0) is default-allow. Swept a third instance the audit missed (line 673).
• audits.mdx provenance (1782321) — restructured to defer to Base's canonical commerce-payments audits/ directory + README Security Audits section (the dated PDFs), dropping the unsourced counts. x402r-specific unaudited disclosure kept.
• gas-costs.mdx (1782321) — added an upstream commerce-payments escrow baseline reference, and a note that CI checks the benchmark for drift.

Contracts repo (separate PR)

• Gas-costs CI — added a gas-docs-drift workflow that re-runs GasBenchmark.t.sol weekly + on main src/test changes, snapshots a committed baseline, and on drift opens a draft docs PR (bumping the pinned commit + date, surfacing the fresh --gas-report for human transcription) when a cross-repo token is configured, or a tracking issue otherwise. So drift maintenance is now automated end-to-end.

Intentionally untouched

• license.mdx — no rewrite, per direction. Still needs the product/legal call on the factory-deploy carve-out vs literal BUSL.

Cross-repo follow-up (not this PR)

• The x402r-sdk helpers server-side rename (forward-to-arbiter.ts / helpers/README.md referencing AuthCaptureServerScheme) is still its own follow-up. Upstream ships client-only for now; server + facilitator follow later.

broken-links passes on every docs change.

[vraspar]

Sixth pass — fix verification

Verified 252d6a6, e419b0b, and 1782321 against the fifth-pass items.

All five items resolved

• Nit (examples.mdx "No refunds") — fixed in 252d6a6, with a bonus third instance at L673 ("No post-delivery refunds") the audit missed. Comment wording mirrors the L458 void() default-allow style.
• Client drift — e419b0b adds the "Signing the payload (client)" section to wire-format.mdx documenting @x402/evm/auth-capture/client. Spot-checked against upstream @x402/evm v2.14.0: AuthCaptureEvmScheme class signature, ClientEvmSigner type (address + signTypedData, optional reads only for EIP-2612 enrichment), default-eip3009 behavior (extra.assetTransferMethod ?? "eip3009"), and the wrapFetchWithPayment / x402Client.register('eip155:*', new AuthCaptureEvmScheme(account)) API all match the canonical upstream client example field-for-field.
• audits.mdx provenance — 1782321 defers to the upstream canonical audit list; unsourced counts replaced with backed link-out. x402r-specific unaudited disclosure preserved.
• gas-costs.mdx cadence — CI-based approach is the right call.
• license.mdx — correctly left for product/legal.

One forward-reference to flag

gas-costs.mdx now states "A scheduled CI job in x402r-contracts re-runs GasBenchmark.t.sol and flags drift past threshold." The workflow PR (BackTrackCo/x402r-contracts#38) is currently open, not merged — created ~2 minutes before the docs commit 1782321. The local x402r-contracts main has no gas-docs-drift.yml workflow yet. If x402r-contracts#38 lands first, fine; if docs#35 merges first, the docs briefly ship a claim that's not yet true.

Not blocking — just flagging for merge sequencing. Suggest merging the contracts CI PR first, then docs#35.

Outstanding (separate follow-ups)

• x402r-sdk helpers/src/forward-to-arbiter.ts + helpers/README.md server-side drift — confirmed stays a separate follow-up since upstream ships client-only for now.
• license.mdx legal call.

PR is ready from a code-accuracy and IA standpoint.

[vraspar]

Quick scope question — the cross-tab content-dedupe table from the fourth-pass review (the 9-row redundancy map: "What is x402r" in 3 pages, authCapture flow in 4, operator slot tables in 4, fee math in 4, etc.) hasn't been addressed yet. The structural IA reorg in c1dc43d solved the where things live question; the which page owns each topic question is separate.

Is the dedupe in scope for this PR, or are you deferring to a follow-up cleanup PR? Either's fine — just want to confirm so it doesn't get lost.

[A1igator]

Did the dedupe in-scope this PR (c1f8182). Worked from the 9-row map in the fourth-pass review. Net -83 lines, broken-links passes.

Trimmed to canonical owner (duplicate block replaced with a pointer)

• Fee-math worked example -> contracts/fees — removed from architecture.mdx and payment-operator.mdx. Bonus: both carried a 3 bps + 2 bps (-> 999.50) variant that disagreed with the canonical 50 + 250 bps (-> 970) example in fees.mdx; that inconsistency is gone.
• 7-day timelock walkthrough -> contracts/fees — removed the queue/wait/execute code blocks from architecture.mdx and payment-operator.mdx.
• Condition-singleton address table -> periphery/overview — removed the duplicate table from factories.mdx (inline factory addresses in deploy examples kept).
• EscrowPeriod+Freeze composition -> conditions/freeze — conditions/escrow-period.mdx now points there.
• Supported-networks table -> sdk/overview — removed the duplicate tables from index.mdx and deploy-operator.mdx.
• auth-capture two-phase flow -> auth-capture/index + architecture — removed the duplicate sequence diagram from x402-integration/overview.mdx.

Pointer added, scoped content kept (judgment calls)

• "What is x402r" -> index — contracts/overview.mdx now defers for the protocol intro and keeps its contract-layer framing.
• Operator slot tables -> payment-operator — kept the condition-only table on conditions/overview and the hook-only table on hooks/overview (each owns its half, on-topic), each now links to the full 10-slot config.
• Deploy preset comparison -> deploy-operator — sdk/overview links there for the full feature matrix; the conceptual two-models prose stays.

Deliberately not trimmed

• Homepage hero diagram (index.mdx) — a landing-page visual, not harmful redundancy. Left in place.

The structural IA reorg (c1dc43d) and this content-ownership pass are now both done.

[vraspar]

Approving — every audit item from the six review passes is now resolved.

Final pass — c1f8182 dedupe verification

Verified all 9 rows of the fourth-pass cross-tab redundancy map landed correctly:

• Fully trimmed (6 rows): fee-math example, 7-day timelock walkthrough, condition-singleton table, EscrowPeriod+Freeze composition, supported-networks table, auth-capture two-phase sequence — each now lives only at its canonical owner; non-canonical pages carry a pointer link to the right anchor.
• Pointer + scoped content kept (3 rows): "What is x402r" intro (contracts/overview keeps contract-layer framing), operator slot tables (condition-half on conditions/overview, hook-half on hooks/overview), deploy preset comparison (sdk/overview keeps the two-models prose, links for the full matrix). Defensible judgment calls.
• Deliberately not trimmed: homepage hero diagram — correct.

Net −83 lines matches git show --stat. No orphan paragraphs, all pointers use correct Mintlify anchor syntax.

Bonus catch confirmed

The dedupe surfaced a real consistency bug — architecture.mdx and payment-operator.mdx had a 3 bps + 2 bps → 999.50 fee-math example that disagreed with the canonical 50 + 250 bps → 970 in fees.mdx. Removing the duplicates fixed the inconsistency.

Final state

All in-PR audit items addressed. Two confirmed out-of-PR follow-ups (license.mdx legal review, x402r-sdk helpers/forward-to-arbiter.ts + helpers/README.md server-side rename) tracked separately.

One soft merge-sequencing note from review #6 still applies: the gas-costs.mdx CI claim references the gas-docs-drift workflow which is in x402r-contracts#38 (still open at time of writing). Suggest merging x402r-contracts#38 first, then this PR, so the claim is true at merge time.

Otherwise: ready to merge whenever you are.