You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
[Improvement]: Expand glossary to cover missing repository terminology #2
While reviewing the repository documentation, I identified a discrepancy between the terminology used in the README and playbooks and the definitions available in docs/glossary.md. Currently, several technical terms and roles are utilized throughout the repo without a centralized definition, which may lead to ambiguity for both human contributors and automated agents attempting to resolve these concepts.
Proposed change
Update docs/glossary.md to include clear, concise definitions for the following terms:
x402 facilitator: Define the role and technical context as referenced in /examples/README.md and /protocols/x402.md.
Quote-vs-settle drift: Provide a technical explanation of this variance to ensure a shared understanding of the concept.
Buyer agent vs. Seller agent: Explicitly define these roles as they are used in the /agent-playbooks.
Mock mode: Define the purpose and behaviour of the MOCK_MODE=true flag used in /examples to assist users in testing and exploration.
Public reference
docs/glossary.md
/examples/README.md
/protocols/x402.md
/agent-playbooks/
Public reference
No response
Submission checklist
One change per PR — this proposal is a single scoped edit
Hi @aurelienlair.
Thanks for the careful read of the docs and for flagging this. The gap you spotted is real: those four concepts are load-bearing across the README, playbooks, and protocol pages but were never centrally defined, which is exactly the kind of friction we want to remove for both human readers and agents resolving terminology.
I've opened #4 implementing your suggestion. It adds five entries to docs/glossary.md (buyer and seller agent are split into two so they're each independently linkable):
Buyer agent (B): user-side role across x402 / AP2 / ACP, with a cross-link to /agent-playbooks/x402-buyer-loop.md
Facilitator (F): the x402 third-party verify-and-settle service, framed as trusted-but-verified (Coinbase, Stripe-on-Base, x402 Foundation)
Mock mode (M): definition of the MOCK_MODE=true default in /examples and the // MOCK: annotation convention
Quote-vs-settle drift (Q, new section): variance between T0 quote and T1 settlement, pointing to /merchant-playbooks/pricing-drift-and-requote.md for the bounding pattern
Seller agent (S): merchant-side counterpart of buyer agent
Activity
docs(glossary): add facilitator, mock mode, buyer/seller agent, quote…
simonlucalandi commentedon May 19, 2026
Hi @aurelienlair.
Thanks for the careful read of the docs and for flagging this. The gap you spotted is real: those four concepts are load-bearing across the README, playbooks, and protocol pages but were never centrally defined, which is exactly the kind of friction we want to remove for both human readers and agents resolving terminology.
I've opened #4 implementing your suggestion. It adds five entries to
docs/glossary.md(buyer and seller agent are split into two so they're each independently linkable):/agent-playbooks/x402-buyer-loop.mdMOCK_MODE=truedefault in/examplesand the// MOCK:annotation convention/merchant-playbooks/pricing-drift-and-requote.mdfor the bounding patterndocs(glossary): add facilitator, mock mode, buyer/seller agent, quote…