docs: move facilitator route to /products/payments-facilitator (with redirects)

[aaitor]

Why this matters

In #385 we renamed the product from "x402 Facilitator" to Payments Facilitator (it verifies and settles both x402 and MPP), but kept the old URL /products/x402-facilitator/* to avoid breaking inbound links. That left the page's name and its address out of step — a reader lands on "Payments Facilitator" at an x402-facilitator URL. This moves the pages to /products/payments-facilitator/* so the address matches the name, and adds redirects from every old path so nothing that already links to the old URLs — other docs, search results, external posts — 404s. No link breaks; the canonical URL just finally reads right.

What changed

• Moved products/x402-facilitator/{overview,how-it-works,mpp-seller}.mdx → products/payments-facilitator/ (git renames; page content unchanged apart from internal links).
• docs.json:

  • Nav group pages repointed to the new paths.

  • Redirects from every old path (Mintlify source → destination):

    Old path	New path
    /products/x402-facilitator	/products/payments-facilitator/overview
    /products/x402-facilitator/	/products/payments-facilitator/overview
    /products/x402-facilitator/overview	/products/payments-facilitator/overview
    /products/x402-facilitator/how-it-works	/products/payments-facilitator/how-it-works
    /products/x402-facilitator/mpp-seller	/products/payments-facilitator/mpp-seller

    Plus the new bare/trailing-slash root → overview, matching the convention used for Router, NVM Pay, etc.

• Rewrote every internal /products/x402-facilitator/ link to the new path: development-guide/nevermined-x402.mdx, products/catalog/overview.mdx, products/catalog/router/overview.mdx, solutions/api-providers.mdx, and the cross-links inside the moved pages. grep "/products/x402-facilitator/" is now empty across .mdx.
• Dropped the maintainer note from docs: document MPP as the plan-model sibling of x402 #385 that said "don't rename the route without redirects" — we're now doing exactly that, with redirects.

This is the clean follow-up r-marques and I flagged on #385 ("renaming them would break every inbound link … unless redirects are added"). Redirects are added, so the concern is resolved rather than traded.

Test plan

• mintlify validate (strict) passes — only the pre-existing react import warning in /snippets/hero-banner.jsx, untouched.
• mintlify broken-links clean; no residual /products/x402-facilitator/ link targets in .mdx.
• docs.json valid JSON.
• Branch cut from current main (includes docs: document MPP as the plan-model sibling of x402 #385).
• Mintlify preview (bot adds it): confirm the nav still shows "Payments Facilitator", the three pages load at /products/payments-facilitator/*, and an old /products/x402-facilitator/overview URL redirects.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PWktbVkhw2RC6LPiUVjFpH

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
Nevermined	🟢 Ready	View Preview	Sep 10, 2026, 3:03 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[Copilot]

🔵 Needs a closer look

The new MPP seller page includes copy/paste curl examples with an invalid Authorization header (placeholder and missing Bearer), which will cause immediate authentication failures for readers.

Pull request overview

Moves the Payments Facilitator docs from the legacy /products/x402-facilitator/* route to /products/payments-facilitator/* and updates navigation/cross-links, while preserving link stability via Mintlify redirects.

Changes:

• Repoints docs.json navigation to products/payments-facilitator/* and adds redirects from all legacy /products/x402-facilitator/* paths (plus the new bare/trailing-slash root).
• Updates internal links across solution/product/dev-guide pages to the new Payments Facilitator routes.
• Introduces the facilitator pages under products/payments-facilitator/ with internal cross-links updated.

File summaries

File	Description
solutions/api-providers.mdx	Updates Payments Facilitator links to the new route.
products/payments-facilitator/overview.mdx	Updates cross-links/cards to point at the new facilitator subpages.
products/payments-facilitator/how-it-works.mdx	Updates the “Accepting MPP payments” cross-link to the new route.
products/payments-facilitator/mpp-seller.mdx	Adds/relocates the MPP seller guide under the new route (contains curl examples).
products/catalog/router/overview.mdx	Updates Payments Facilitator link in the Router comparison table.
products/catalog/overview.mdx	Updates Payments Facilitator cross-link from Catalog overview.
development-guide/nevermined-x402.mdx	Updates buyer-side note linking to the MPP seller page under the new route.
docs.json	Updates nav entries and adds redirects for old and new facilitator roots/paths.

Review details

• Files reviewed: 7/8 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[aaitor]

Re the Copilot review — this is a false positive, no change made:

The mpp/challenge and mpp/settle curl examples already use the correct header: -H "Authorization: Bearer $NVM_API_KEY" (mpp-seller.mdx lines 57 and 81). Bearer is present, and $NVM_API_KEY is a shell environment variable — the standard copy-paste idiom for a secret in a curl example, not a broken placeholder. (The Authorization: Payment <…> on line 26 is the buyer→seller MPP credential header, which is correct and deliberately not Bearer.)

This PR only moves mpp-seller.mdx to the new route; its content shipped unchanged in #385. Leaving the examples as-is.

[r-marques]

👀 Reviewing

[r-marques]

🤖 Automated PR review — ✅ Ready to merge

Moves the facilitator route from products/x402-facilitator/* to products/payments-facilitator/*, so the URL matches the product name that #385 established. This is the one change in a docs repo that silently breaks every inbound link if done carelessly — and it is done carefully: all five old URL shapes redirect, every internal link is updated so nothing relies on the hop, and the now-obsolete "don't rename without redirects" note is removed rather than left to rot. Nothing to address.

What I reviewed

• Diff range origin/main...HEAD — 8 files, +36/−18, head fde357f0.
• Panel: none — no pr-review-toolkit agents were spawned in this session, so this is my own verification only, not multi-agent coverage.
• Redirect coverage, enumerated from the parsed docs.json rather than the diff. Five sources cover every shape an existing link can take:

  /products/x402-facilitator              -> /products/payments-facilitator/overview
  /products/x402-facilitator/             -> /products/payments-facilitator/overview
  /products/x402-facilitator/overview     -> /products/payments-facilitator/overview
  /products/x402-facilitator/how-it-works -> /products/payments-facilitator/how-it-works
  /products/x402-facilitator/mpp-seller   -> /products/payments-facilitator/mpp-seller
  

  Both bare forms and all three pages — the bare-path pair is the one usually forgotten, and it is the shape a human types.
• No internal link still points at the old path — grepped every .mdx in the repo, not just the changed ones. So the redirects are a safety net for external inbound links, not load-bearing for the site's own navigation, which is the right way round.
• docs.json nav entries all moved (parsed the JSON: zero remaining products/x402-facilitator/* page entries) and the file is still a text edit, not a json.load/dump round-trip.
• Every internal link in the changed files resolves to a real .mdx, checked by script rather than by eye — including the updated anchor …/mpp-seller#protocol-isolation, whose ## Protocol isolation heading is at mpp-seller.mdx:139.
• mintlify broken-links will not abort. git sees the renamed files as wholly new, so every line reads as added; of the three <…> placeholders that surfaced in mpp-seller.mdx, all three are inside code fences (lines 20, 26, 32) — verified with fence tracking, not just a backtick check.
• The rename is faithful: how-it-works and mpp-seller are line-for-line identical; overview is −2, and those two lines are exactly the MDX note that should go (below).
• CI: Mintlify Deployment pass, link-rot pass. (vale-spellcheck reports skipping.)

One thing worth recording — my review on #385 said the paths were deliberately left alone and that renaming them would break inbound links. #385 merged at 14:55 having added a note in overview.mdx saying precisely that. This PR then does the rename and satisfies the condition the note set, so removing it is correct: the instruction was followed, not overridden. That is the loop closing properly rather than a comment being deleted because it was in the way.

Verdict: ✅ Ready to merge — 0 blockers, 0 should-fix, 0 nits.

🧭 Inline comments (2)

Each is posted on its line in Files changed.

• ✅ NICE — Every old URL shape redirects, including the two bare forms — docs.json:506
• ✅ NICE — The note that forbade this rename is removed because its condition was met — products/payments-facilitator/overview.mdx:10

[r-marques]

✅ Approved — no blockers, nothing to address.

Inline review: #388 (review)