docs: correct API examples to the current wire contract

[atc964]

Summary

The integrator-facing docs still described the retired wire format, so every documented quote, booking, order-transition, and change-request example failed against the API as it actually behaves today. This is a correction pass against the current contract: routers, interfaces/api/schemas.py, interfaces/api/contract_mappers.py, and the pinned iab-agentic-primitives v0.5.1. No prose was rewritten beyond what accuracy required.

docs/api/quotes.md

• Was false: the request body omitted the required idempotency_key (every example 422s today); target_cpm was documented as a bare float; the response was shown flat; product_id used a fake catalog slug ("display").
• Now says: idempotency_key is required on every quote request, with replay/conflict semantics explained; target_cpm is a Money object ({"amount_micros": <int>, "currency": "USD"}); the response is a {"quote": {...}} envelope wrapping the shared Quote primitive, with every price field shown as Money; product_id uses a realistic seller-issued id (prod-3f2a9c81) and notes that real IDs come from GET /products.

docs/integration/buyer-agent.md

• Was false: the recommended Quote-Book flow failed at four steps — the quote curl 422s (missing idempotency_key), the book curl 422s (same), the order-transition step was shown as something a buyer agent calls directly even though POST /api/v1/orders/{id}/transition is operator-only, and the change-request curl 422s (idempotency_key required since fix: enforce idempotency for change requests #64). The agent-card description also claimed the card advertises a2a capability.
• Now says: quote and book curls both carry idempotency_key with a note on replay semantics; the order-transition example is shown with an operator credential and a note that a buyer agent cannot call it directly; the change-request curl carries idempotency_key; the agent-card description states the card currently serves only opendirect21 (A2A is a documented design, not yet a served surface).

docs/api/change-requests.md

• Was false: the request-body table and both create-request curl examples omitted the required idempotency_key; the review and apply curls were shown with no auth even though both are operator-only.
• Now says: idempotency_key is documented as required in the table and both create examples; the review and apply curls carry Authorization: Bearer <operator_api_key>, with prose noting the operator-only gate.

docs/api/orders.md

• Was false: the headline stated 20 allowed transitions (the state machine table has 21); the transition example showed an unauthenticated call to an endpoint that is actually operator-only.
• Now says: the headline reads 21 allowed transitions; the transition example carries an operator credential, with a note explaining the gate.

Test plan

• Verified the pin: pyproject.toml and uv.lock pin iab-agentic-primitives to v0.5.1; checked out that tag in a local clone to read Money, Quote, QuoteRequest/QuoteResponse, DealBookingRequest/DealBookingResponse, ChangeRequestCreate, IdempotentRequest, and the OrderStatus/transition primitives directly from source.
• Traced every documented request/response shape to the live code: routers/quotes.py, routers/deals.py, routers/orders.py, routers/change_requests.py, routers/registry.py, interfaces/api/contract_mappers.py, interfaces/api/schemas.py, interfaces/api/deps.py, and models/order_state_machine.py (confirmed 21 transitions in _DEFAULT_TRANSITIONS, 12 OrderStatus values).
• Confirmed the prod-{hash} product-id format from services/catalog_service.py.
• Ran mkdocs build --strict (via uv run with the docs extra installed) — builds clean with no new warnings from the changed pages.

[Sirajmx]

Verified: unit + integration passed (0 failed) - identical to current main's own
baseline, as expected for a docs-only change. Also ran mkdocs build --strict, clean. Spot-
checked a sample of the corrected examples (idempotency keys, Money pricing, envelope
responses, operator auth on transition/review/apply) against the live wire contract - accurate.
No conflicts merging onto main.