[enot3615]

What was wrong

charge/gateway.mdx (Configure the Gateway) and charge/onboarding.mdx (self-serve step 3) said a new hosted gateway endpoint is "live immediately" once saved. It is not: the page was wrong, the code is right.

• backend/app/aifp/gateway-routing.js selectGateway refuses any gateway that is not eligible, and eligibility needs enabled_intent plus dns-state.js gatewayReadiness(...).ok, which needs a DNS_VALID, recent proof for the upstream host. The refusal is refused() → 403 {"error":"gateway_unavailable"}, returned in routes/gateway.js before any policy or quota step, so there is no 402 challenge. (A site router slug with no matching resource gets 503 default_gateway_unavailable instead.)
• Production runs aifinpay-web e3632bd (deployed 2026-10-24 18:26 UTC). Since 3e1c69d (#239) it has carried this gating, and gateway-routing.js, dns-state.js and routes/gateway.js are byte-identical between e3632bd and main (fb7f6f8).
• Live, read-only: GET https://gateway.aifinpay.io/vapan/ (a configured gateway that is not ready) → 403 {"error":"gateway_unavailable","detail":"the selected gateway is not available"}. An unknown slug → 404 gateway_not_found.
• Dashboard (paywall-dashboard main): the page is Site settings (sidebar and page header). The flow is Add gateway → Review changes → Apply changes, and the new-gateway form defaults Enable after verification to ticked. The Domain verification card shows the TXT record (_aifp-verify.<upstream-host>) and Check DNS now, and the account Dashboard lists gateway rows in the DNS connection queue.

Change

• charge/gateway.mdx: the Configure step uses the Site settings / Add gateway flow. It says the endpoint starts forwarding once the upstream's TXT record verifies, and that until then it answers 403 gateway_unavailable. It names where the record is shown and asks the merchant to keep the record in place: the monitor re-checks it, and a stale or missing proof stops forwarding. It notes that when the Site URL has the same host as the upstream, one record verifies both (reconcileSiteProof / reconcileProofs add the site ref to the existing proof, same generation).
• charge/onboarding.mdx: step 3 says the same thing in two sentences and uses the Site settings label.

This is based on main and does not touch the lines changed by #24 (verify your domain). A git merge-tree against docs/verify-your-domain is clean.

Checks

• node scripts/check-internal-links.mjs → OK: 18 configured pages and no missing internal links
• git diff --check clean
• Both pages compile with @mdx-js/mdx 3.1.0

Linked surfaces

• Backend API (aifinpay-web backend/): not affected. The page now matches selectGateway / gatewayReadiness on main and on prod e3632bd. No API change.
• Public site (llms.txt, agent.txt, /manifesto.json, marketing app): not affected. None of them claims a hosted gateway goes live on save (grepped main).
• Merchant dashboard (paywall-dashboard): not affected. It already says Enable after verification and shows the TXT record. The labels used here are taken from main (Sidebar.tsx, pages/Gateway.tsx, GatewayConfigManager.tsx, ConfigImportModal.tsx, SiteDnsQueue.tsx).
• SDK / MCP / gate packages (AiFinPay/sdk): not affected. The self-hosted gate does not go through hosted-gateway readiness, and no README claims immediacy.
• Docs: updated (this PR). It complements docs(charge): verify your domain before MCP agents will pay #24, which adds the Site URL verification step.