Skip to content

[Improvement]: Expand glossary to cover missing repository terminology #2

Closed

Description

@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

Activity

  1. added a commit that references this issue on May 18, 2026
    b66c131
  2. simonlucalandi commented on May 19, 2026

    @simonlucalandi
    Contributor

    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
  3. added a commit that references this issue on May 19, 2026
    a5c7c99
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions