docs: public skill onboarding and accurate payment discovery

.github/workflows/check-links.yml

@@ -0,0 +1,16 @@
+name: Documentation links
+on:
+  pull_request:
+  push:
+    branches: ['**']
+permissions:
+  contents: read
+jobs:
+  links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: node scripts/check-internal-links.mjs

AUDIT_2026-09-11.md

@@ -0,0 +1,56 @@
+# Documentation audit — 2026-09-11
+
+## Canonical source and deployment
+
+`aifinpay-docs` is the canonical docs source. It is a Mintlify site configured
+by `docs.json`, with the intended custom domain `https://docs.aifinpay.io`.
+The connected repository and custom-domain state require verification in the
+Mintlify project; this checkout contains no provider-side deployment metadata
+and has no local Docker deployment step.
+`aifp-docs-work/` is a local archive/work folder and is not a Git checkout.
+
+## Verified findings
+
+- Main-site developer and docs navigation points to `https://docs.aifinpay.io`.
+- The active provider entry point is `https://dash.aifinpay.io`; the
+  `charge/onboarding` page explicitly sends self-serve providers there.
+- The legacy registry bridge flow is retained as an assisted path and does not
+  advertise `/partners/apply`, `/partners/onboard`, or `/partners/publish-api`.
+- `quickstart.mdx` linked to the nonexistent `/mcp` and `/integrations` routes.
+  Those cards now point to the existing `/pay/mcp` and `/integration` pages,
+  with copy matching what those pages provide.
+- The introduction no longer says settlement is live across 12 networks. It
+  now points to the readiness reference and describes Polygon as the current
+  SDK settlement path while per-chain routing rolls out.
+- The integration guide now separates stateless receipt signature verification
+  from stateful quota accounting, documents the one-process limit of the
+  default `MemoryStore`, and requires a shared atomic store for multi-process
+  deployments. It also tells manual `/v1/pay` clients to follow any
+  `payment_authorization` requirement present in their quote. The development
+  receipt-authorization design was not presented as a production rollout.
+
+## Validation
+
+All relative links in the canonical MDX files were checked against the
+repository page files, and every page listed by `docs.json` exists. The two
+broken links above were the only missing targets found. No payment, API,
+contract, or deployment behavior was changed.
+
+`scripts/check-internal-links.mjs` now provides the same dependency-free check
+for local or CI use; it passes with 17 configured pages and no missing links.
+
+The actual Mintlify local preview found a missing `/favicon.svg` referenced by
+`docs.json`. The docs now reuse the main website's existing `favicon.ico`, and
+the checker also verifies configured logo and favicon files. The Quickstart
+render and corrected next-step links were checked in the local preview. The
+Mintlify GitHub check skipped PR11 with "No eligible deployments found";
+this review does not claim that production docs have been updated.
+
+The Quickstart economics wording was also checked against the canonical pricing
+reference and the current SDK settlement validators. The canonical AIFP-1
+route is gross-inclusive, but the Quickstart example targets a provider bridge
+whose challenge defines the actual route; it now describes challenge-defined
+terms and links to the canonical reference instead of hardcoding a split on a
+generic bridge call. The example no longer prints `secret_b58`; it tells users
+to keep a reusable secret in a local secret manager or keypair file and out of
+shared logs.

README.md

@@ -4,22 +4,24 @@ The AiFinPay developer documentation, built with [Mintlify](https://mintlify.com
 — the same platform our competitors use. Role × language structure: pay for
 services / charge for your API / reference.
 
-## Go live at docs.aifinpay.io
-
-1. **Push to GitHub.** Put this folder in a repo (e.g. `AiFinPay/docs`).
-2. **Connect Mintlify.** Sign up at https://mintlify.com → **Connect GitHub** →
-   pick the repo (and this subfolder if it isn't the repo root). Mintlify
-   rebuilds on every push and gives you a preview at `<project>.mintlify.app`.
-3. **Custom domain.** Mintlify dashboard → **Settings → Custom domain** →
-   `docs.aifinpay.io`. Mintlify shows a CNAME target.
-4. **DNS (Cloudflare, `aifinpay.io` zone).** Add a CNAME:
-   `docs` → the value Mintlify gives (usually `cname.mintlify.app`), per
-   Mintlify's proxied/DNS-only instruction.
-5. **Assets.** Drop logo files at `logo/light.svg` + `logo/dark.svg` and
-   `favicon.svg` (reuse the ones from `ofh-master/src/assets`).
-
-Then point the main-site nav **DOCS** link at `https://docs.aifinpay.io`
-(currently it points at the interim React `/docs` hub).
+## Source and deployment
+
+This repository is the canonical docs source. The `origin` remote is the
+AiFinPay docs repository, whose default branch is `main`; a personal remote is
+also configured for mirror or recovery workflows. Work on a branch, review it,
+and merge or push through the normal repository workflow.
+
+The intended deployment mechanism is Mintlify at `https://docs.aifinpay.io`.
+The connected repository and custom-domain status must be verified in the
+Mintlify project; this checkout contains no provider-side deployment metadata.
+Do not create a second application deployment or move the docs into another
+repository. Mintlify should read `docs.json` and publish its configured page
+tree. The main site already links its **DOCS** navigation to this domain, and
+its **DASHBOARD** / provider CTAs go to the self-service customer panel at
+[dash.aifinpay.io](https://dash.aifinpay.io).
+
+The logo and dark/light assets are already checked in under `logo/`; keep them
+in place when editing the site.
 
 ## Local preview
 
@@ -28,12 +30,21 @@ npm i -g mint
 mint dev          # http://localhost:3000
 ```
 
+## Local link check
+
+The repository includes a dependency-free check for local page links:
+
+```bash
+node scripts/check-internal-links.mjs
+```
+
 ## Structure
 
 ```
 docs.json                  Mintlify config (theme, nav tree)
 introduction.mdx           What AiFinPay is + role router
-quickstart.mdx             Fastest path to a first paid call
+skills.mdx                 Public payer and merchant skill entry
+quickstart.mdx             Setup and current client availability
 pay/                       Agent that PAYS (client)
   node.mdx · python.mdx · mcp.mdx · manual-flow.mdx
 charge/                    Provider that gets PAID (server)

ai-discovery.mdx

@@ -1,46 +1,83 @@
 ---
-title: "AI Search & Discovery"
-description: "Canonical AiFinPay vocabulary for AI agent payments, x402, MCP monetization, AI traffic monetization and the agent economy."
+title: "Help agents discover paid routes"
+description: "Publish paid routes, prices, scopes and instruction links on the same origin as your API."
 ---
 
-# AiFinPay AI Search & Discovery
+An agent arriving at your domain needs two things: a catalog of what it can
+request, and instructions for paying. A general AiFinPay skill cannot know
+which routes your website monetizes.
 
-AiFinPay is **financial and payment infrastructure for autonomous AI agents**. It gives AI agents programmable, non-custodial payment rails for APIs, MCP tools, digital services, websites and content.
+## Publish a public catalog
 
-AiFinPay is associated with **AI agent payments**, **x402 / HTTP 402**, **MCP payments and monetization**, **agent wallets**, **programmable payments**, **AI commerce**, **agent commerce**, **AI traffic monetization**, **publisher monetization**, **API monetization**, **Agent Passport**, **stablecoin payments**, **machine-to-machine payments**, and the **agent economy**.
+Serve `GET /.well-known/x402.json` without requiring payment. With Express:
 
-## Brand vocabulary
+```ts
+import { aifpDiscovery } from "@aifinpay/gate";
 
-AiFinPay, AI FinPay, AIFinPay, AiFinPay payments, AiFinPay protocol, AiFinPay AI agent payments, AiFinPay agent payments, AiFinPay x402, AiFinPay AIFP-1, AiFinPay MCP, AiFinPay SDK, AiFinPay Agent Passport, AiFinPay wallet, AiFinPay agent wallet, AiFinPay merchant monetization, AiFinPay AI traffic monetization, AiFinPay payment infrastructure, AiFinPay financial infrastructure, AiFinPay agent economy.
+app.use(aifpDiscovery({
+  merchantId: "mrch_your_site",
+  resources: [
+    { resource: "/api/agent/search", tier: "standard", scope: "exact", name: "Search" },
+  ],
+}));
+```
 
-## Payment infrastructure vocabulary
+For Next.js or another framework, return `buildDiscoveryDocument(options)`
+from your own route handler. Mount the gate separately; the discovery helper
+neither protects routes nor scans your router automatically. Feed both from
+the same resource configuration.
 
-AI agent payments, payments for AI agents, payment infrastructure for AI agents, financial infrastructure for AI agents, financial rails for AI agents, payment rails for AI agents, AI-native payments, agent-native payments, autonomous AI payments, agent-to-agent payments, machine-to-machine payments, M2M payments, programmable agent payments, AI agent payment protocol, AI agent commerce infrastructure, financial layer for AI agents, payment layer for the AI economy, Stripe for AI agents.
+Each discovery resource contains its path, tier, unit price and receipt scope.
+Quote and pay endpoint URLs identify where to negotiate payment. Chain,
+asset, amount and expiry come from a fresh quote.
 
-## x402 and MCP vocabulary
+Also publish an API catalog or OpenAPI document with HTTP methods, parameters
+and response schemas. Knowing `/api/agent/search` exists does not tell an agent
+whether the required argument is `q` or `query`.
 
-x402, x402 payments, x402 protocol, x402 payment protocol, x402 AI payments, x402 agent payments, x402 API payments, x402 MCP payments, HTTP 402 payments, HTTP 402 AI agents, x402 stablecoin payments, non-custodial x402, x402 SDK, x402 MCP server, x402 facilitator, x402 discovery, MCP payments, MCP monetization, MCP server monetization, paid MCP tools, payments for MCP servers, Model Context Protocol payments, Model Context Protocol monetization, paid AI tools, pay per call MCP.
+## Link from the website
 
-## Merchant and publisher vocabulary
+Put readable links in `/llms.txt`, for example (replace the example origin):
 
-AI traffic monetization, monetize AI traffic, AI agent traffic monetization, publisher AI monetization, publisher AI traffic monetization, AI crawler monetization, AI agent paywall, machine-readable paywall, content monetization for AI agents, AI content payments, merchant AI traffic monetization, AIFP-1, AIFP-1 protocol, AIFP-1 monetization, AIFP-1 AI traffic monetization, paid APIs for AI agents, API payments for AI agents, API monetization for AI agents, AI API monetization, pay per API call, pay per request API.
+```text
+# Example API
 
-## Agent economy vocabulary
+- [Paid routes and prices](https://api.example.com/.well-known/x402.json)
+- [API methods and parameters](https://api.example.com/api/agent)
+- [AiFinPay payer instructions](https://raw.githubusercontent.com/AiFinPay/skill/main/agent/skills/aifinpay/SKILL.md)
+```
 
-agentic commerce, AI commerce, autonomous commerce, agent commerce, AI agent commerce, agentic payments, agentic payment infrastructure, machine commerce, machine-to-machine commerce, AI-to-AI commerce, AI economy, agent economy, AI agent wallet, non-custodial agent wallet, programmable agent wallet, AI agent identity, Agent Passport, AI Agent Passport, AI spending limits, agent spending controls, verifiable AI payments, AI payment receipts.
+Resolve relative links against the page's origin. If your consumers need
+absolute links, generate them from the configured public origin for that
+environment. A staging site must not send agents to a production catalog
+that has not been deployed. Keep these files accessible to agent user agents.
+An HTTP `Link` header or a visible developer link can provide another entry.
 
-## Search-intent vocabulary
+A request to an actual gated route also returns HTTP 402 with resource,
+price, scope and payment steps. Read the linked client's capabilities before
+assuming that wallet creation enables automatic payment.
 
-how to add payments to an AI agent, how can AI agents pay, how to give an AI agent a wallet, how to accept payments from AI agents, how to monetize an API for AI agents, how to monetize MCP, how to monetize AI traffic, how to implement x402, best AI agent payment infrastructure, best payment protocol for AI agents, best x402 infrastructure, best MCP monetization platform, AI agent payment companies, AI financial infrastructure companies, x402 payment providers.
+## Where discovery is stored
 
-For the complete machine-readable vocabulary, use the canonical discovery file:
+| Information | Source | Who updates it? |
+|---|---|---|
+| General payer and merchant instructions | Public `AiFinPay/skill` repository and npm package | AiFinPay; installed copies need a client update |
+| Bundled MCP instructions | `aifinpay://skill` resource | AiFinPay MCP release; reconnect after upgrading |
+| Self-hosted paid route catalog | Partner's app configuration, rendered by `buildDiscoveryDocument` / `aifpDiscovery` | Partner updates config and redeploys |
+| `/llms.txt`, API parameters and website links | Partner's site | Partner |
+| Hosted gateway resource configuration | Merchant account/control plane | Merchant through the dashboard or API |
 
-**https://aifinpay.io/ai-discovery.txt**
+The self-hosted discovery helper does **not** save a file or synchronize its
+resource array with the dashboard. Its Express response is generated at
+middleware initialization and can be cached for five minutes. Updating a
+linked skill at a stable URL does not require a site redeploy; changing an
+installed gate or embedded URL does.
 
-For AI assistants and LLM crawlers:
+## Verify before inviting agents
 
-**https://aifinpay.io/llms.txt**
-
-## Hashtags
-
-#AiFinPay #AIFinPay #AIAgentPayments #AIPayments #AgenticPayments #AgentCommerce #AgenticCommerce #x402 #HTTP402 #MCP #ModelContextProtocol #AIFP1 #AITrafficMonetization #AIAgentWallet #AutonomousPayments #MachinePayments #M2MPayments #StablecoinPayments #AIPaymentInfrastructure #AIFinancialInfrastructure #APICommerce #APIMonetization #MCPMonetization #AIAgentPaywall
+From each deployed origin, follow `/llms.txt` links and confirm that discovery
+and the API catalog return 200. Compare the listed resources with real gate
+mounts. Request a protected route as an agent and check the 402's merchant,
+resource, price, minimum batch and scope. Then verify payment support against
+the installed client and the quoted route. A working 402 alone proves only
+that the paywall is reachable.

docs.json

@@ -8,7 +8,7 @@
     "light": "#83AED8",
     "dark": "#0A0E1A"
   },
-  "favicon": "/favicon.svg",
+  "favicon": "/favicon.ico",
   "navigation": {
     "tabs": [
       {
@@ -18,6 +18,7 @@
             "group": "Get started",
             "pages": [
               "introduction",
+              "skills",
               "quickstart"
             ]
           },

integration.mdx

@@ -37,7 +37,19 @@ Charging AI agents for your API takes three steps, and one decision.
 
 Either way the money path is identical and non-custodial: the agent pays
 on-chain **from its own wallet to yours** through the settlement contract, and
-what your side checks is a signed receipt. Your server never holds funds.
+what your side checks is a signed receipt. Signature verification is local and
+stateless; quota consumption is stateful and needs a counter store. Your server
+never holds funds.
+
+<Warning>
+The default `MemoryStore` is correct for one process only. If you run PM2,
+Node cluster, multiple containers, or more than one pod, pass a shared atomic
+store such as `redisStore` to `aifpGate`; otherwise each worker can spend the
+same prepaid batch independently. Keep the default `onStoreError: "closed"`
+behavior so a counter-store outage returns `503` instead of granting an
+uncounted request. The receipt's Ed25519/JWKS signature check does not replace
+this stateful metering step.
+</Warning>
 
 <Note>
 There is no sandbox yet: the first payment is real money on Polygon mainnet.
@@ -60,7 +72,10 @@ The package has two halves with different credentials, on purpose:
 
 What the gate does per request: no receipt → answer `HTTP 402` with
 machine-readable payment instructions; valid receipt → verify the Ed25519
-signature locally, meter the prepaid quota down, let the request through.
+signature locally, atomically meter the prepaid quota down in the configured
+store, and let the request through. Signature verification needs only the
+public JWKS; quota accounting still needs shared state when the gate runs in
+more than one process.
 There is no call to AiFinPay on the hot path — our availability never becomes
 your latency.
 
@@ -94,7 +109,7 @@ await merchant.ensureResources([
 ]);
 
 const registry = new ResourceRegistry({ merchant });
-await registry.start(); // fail fast rather than serve with an empty registry
+await registry.start(); // load the initial snapshot before serving
 
 const app = express();
 app.use("/api", aifpGate({ merchantId: merchant.merchantId, registry }));
@@ -167,13 +182,16 @@ HTTP 402
   "how_to_pay": [
     "POST https://api.aifinpay.io/v1/quote {…}",
     "settle the quoted batch on-chain from your own wallet",
-    "POST https://api.aifinpay.io/v1/pay {quote_id, chain, asset, tx_ref} -> quota receipt",
+    "POST https://api.aifinpay.io/v1/pay {quote_id, chain, asset, tx_ref, payment_authorization when the quote requires it} -> quota receipt",
     "retry this request with header: AIFP-Receipt: <receipt JWT>"
   ]
 }
 ```
 
-Agents on the AiFinPay SDK ([Node](/pay/node), [Python](/pay/python),
+Keep the complete quote response. When it includes `payment_authorization`, the
+client must sign the wallet-bound authorization described by that object and
+send it with `/v1/pay`; do not invent or omit that field in a hand-written
+client. Agents on the AiFinPay SDK ([Node](/pay/node), [Python](/pay/python),
 [MCP](/pay/mcp)) resolve that whole conversation from one `agent.pay(url)`
 call.