Document GPT request and delivery traceability in VitePress #1014

Context

PR #997, Attribute GPT renders to Trusted Server on observed evidence, is the latest pull request merged to main. It extends the opt-in GPT Runtime Diagnostics console originally introduced in #974.

Operators make the integration available with [integrations.gpt_diagnostics] and activate a browser session with ?ts_console=1. The public documentation needs to explain not only how to open the console, but also how to interpret the request, auction, delivery, replacement, and attribution evidence added by #997.

PR #997 already added substantial content to the existing GPT Runtime Diagnostics guide, and that VitePress deployment succeeded. Treat this issue as a completeness and discoverability pass against the final merged behavior, not as a new runtime implementation or a duplicate guide.

Documentation scope

Activation and navigation

• Keep docs/guide/integrations/gpt-diagnostics.md as the canonical public guide.
• Show a copy-paste example such as https://publisher.example.com/article?ts_console=1.
• Document the deployment prerequisite and the exact, case-sensitive activation and deactivation values: 1, true, 0, and false.
• Explain browser-session, URL-cleanup, cookie, and cache behavior.
• Confirm the guide is reachable from the VitePress sidebar and integrations overview, and link to it from the GPT integration guide where useful.
• State that activation requires no publisher-code changes. Trusted Server creative-progress evidence is available only for slots served through the GPT integration.

Request and refresh traceability

Document how each retained GPT request cycle reports:

• Request paths: trusted_server_direct, prebid_refresh, publisher_refresh, competing, and unattributed.
• Direct opportunities: renderable_candidate, unrenderable_candidate, and no_candidate.
• Request-intent evidence, the opaque per-auction diagnostics token, and opportunity-to-request latency when available.
• Refresh replacement observations, including the previous request, elapsed time, and observed creative-ID transition.
• Ambiguous or bypassed request paths without guessing a source.
• Normal load-before-render ordering through loadObservedBeforeRender without fabricating a negative duration or marking the cycle incomplete.

Delivery and GAM evidence

Explain the positive-evidence ladder from a direct Trusted Server opportunity through creative request, markup response, and GPT load. Define the derived delivery states:

• trusted_server_response_sent
• trusted_server_selected
• candidate_unconfirmed
• no_candidate
• unknown
• pending
• not_applicable

Also document:

• Safe creative-bridge failure categories without exposing payloads, URLs, markup, or error objects.
• Source-neutral GAM line item, order, advertiser, creative, yield-group, company, and backfill identifiers when GPT exposes them.
• Response classes: empty, backfill, reservation, and unclassified_non_empty.
• The distinction between callback-correlation issues and Trusted Server attribution issues.

Operator use, privacy, and limits

• Describe the overlay, badges, filters, five-method read-only browser API, and versioned JSON export.
• Explain the exported request-path, auction, delivery, replacement, response-class, issue, and retention fields.
• State that the auction token is minted per auction and is unrelated to the Edge Cookie ID.
• Preserve the browser-local, bounded-retention, and no-upload privacy guarantees.
• Make the evidence boundary explicit: the console reports observations, not bidder ownership, winner identity, iframe execution, pixel rendering, or visual correctness.
• Add troubleshooting guidance for absent diagnostics, missing early callbacks, unbound or ambiguous slots, unattributed or competing refreshes, candidate-unconfirmed delivery, and missing correlation evidence.

Acceptance criteria

• The published VitePress guide matches the final behavior merged in Attribute GPT renders to Trusted Server on observed evidence #997 and contains no stale contradictions from the earlier diagnostics implementation.
• A reader can activate the console using an exact ?ts_console=1 example and can find the guide from the GPT integration documentation.
• Every request-path, opportunity, delivery, and response-class value above is defined in operator-facing language.
• Replacement evidence, attribution issues, loadObservedBeforeRender, the browser API, export contents, privacy boundaries, and retention limits are documented.
• The guide consistently distinguishes positive evidence from inference and does not claim that a filled slot proves Trusted Server delivery.
• Existing VitePress navigation links resolve.
• cd docs && npm run lint && npm run format && npm run build passes.
• After merge to main, the Deploy VitePress Docs workflow succeeds and the updated guide is visible on the public site.

Out of scope

• Changes to diagnostics runtime behavior, query directives, or session-cookie semantics.
• New attribution heuristics or claims not supported by observed evidence.
• Duplicating public guidance under docs/superpowers/**.