[Improvement]: Expand glossary to cover missing repository terminology

[aurelienlair]

File or section being improved

docs/glossary.md

The gap

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
• No marketing language in the proposed text
• Official source linked for any factual claim
• I have read CONTRIBUTING.md

[simonlucalandi]

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