docs: clarify business-populated response values for identity-linked sessions

[jamesandersen]

docs: clarify business-populated response values for identity-linked sessions

Motivation

This is a focused, docs-only alternate to #519. That thread converged on a
clear conclusion (thanks @karangoel16 for raising it, and @raginpirate /
@amithanda for the framing): surfacing business-owned user state — saved payment
instruments, loyalty membership, buyer profile — does not need a new
extension or a new schema field. It is already possible through existing base
entities. The real gap is discoverability: today the mechanic is implicit,
spread across the ucp_request annotations, the loyalty extension, and identity
linking, and an implementer is unlikely to connect those on their own.

Rather than add a standalone concept page (which risks becoming a second source
of truth that drifts from the annotations that actually govern behavior — see
@amithanda's point in
#519 (comment)),
this PR lands the same intent as small edits anchored to the specs that already
own each concept.

What this PR changes

• identity-linking.md — adds a ### Business-Populated Response Values
  subsection right after Access Levels (where the auth model already lives). It
  names the pattern: fields annotated ucp_request: "omit" are business-populated
  by definition; fields the platform MAY also supply (optional/unannotated) MAY
  additionally be populated by the business from stored user state on a response.
  Identity linking is what makes those values user-specific.
• checkout.md — adds a pointer in the Payments section explaining that
  payment.instruments may carry display-safe, business-scoped saved instruments
  (opaque id + display, no raw credential), links to the existing
  create-checkout REST example that already returns this shape, and to Identity
  Linking for the access levels/scopes that gate it.
• payment_instrument.json — corrects the id description. It previously
  said "assigned by the platform," which is wrong for an identity-linked saved
  instrument: there the business assigns the id and the platform MUST treat it
  as an opaque, business-scoped reference.
• loyalty.md — one-line cross-link from the existing "business populates
  loyalty from authenticated identity" paragraph to the new subsection, so the
  loyalty case is explicitly framed as an instance of the general pattern.

What this PR deliberately does not do

• No standalone page. No business-owned-response-values.md; no mkdocs.yml
  nav entry.
• No new schema fields. No payment.saved_instruments[],
  no credential_state enum, no generic tokenized-node abstraction.
• No unencrypted-credential example. The response example in the original
  draft that transmitted a raw credential is omitted, consistent with the
  payment handler security guidance
  (and the review comments from @jamesandersen / @dkoch74).
• Saved shipping addresses are out of scope. Populating
  fulfillment from stored user state is trickier and belongs in its own PR.

Follow-ups (intentionally separate)

These surfaced on the thread and are worth their own enhancement proposals given
the PII implications:

1. A generic reference/tokenized-node abstraction to mark any response node as an
   opaque business-owned reference (@raginpirate / @rosew).
2. A machine-readable way to distinguish a ready-to-resolve saved reference from
   an instrument that still needs credential collection — credential absence is
   ambiguous between the two, and id naming is the signal we agreed not to lean
   on (@karangoel16's credential_state idea).

Category (Required)

• Documentation: Updates to README, or documentation regarding schema or
  capabilities.

Checklist

• I have followed the Contributing Guide (Conventional Commits title, no
  breaking changes).
• I have updated the documentation.
• My changes pass local linting (cspell, markdownlint). The full mkdocs
  build could not be run locally; relying on CI (docs.yml) as authoritative.
• I have added tests. Docs + one schema-description clarification; no
  behavior change.
• (For Core/Capability) The one schema change is a description-only
  clarification on payment_instrument.id; no structural or contract change.

Verified claims

The annotation statements in the identity-linking subsection were checked
against source/schemas/shopping/:

• totals, messages, order are ucp_request: "omit" in checkout.json.
• buyer is ucp_request: {create: optional, update: optional, complete: omit}.
• payment.instruments carries no ucp_request annotation in payment.json
  (bidirectional by default).

[raginpirate]

Thanks for defining this missing prose @jamesandersen! I had a couple non-blocking doc nits.