docs(protocol): design principles + capabilities explorer

[bokelley]

Summary

Adds two new pages and a callout pattern that together close the structural reason wrong-shape RFCs land in the working group.

• docs/protocol/design-principles.mdx — the meta-protocol page contributors and reviewers need to make and evaluate sound RFCs. Seven load-bearing principles. Each one: rule / why / what this rules out / when you'd be right to push. Honest about where the surface still violates them.
• docs/protocol/capabilities-explorer.mdx — browsable view of the get_adcp_capabilities response schema, walking every top-level domain to one sub-namespace deep, with per-node "propose extension here" GitHub issue links that pre-fill the schema path. Plus gate questions before proposing a new top-level key.
• "Why this shape" callout demonstrated on get_products and get_adcp_capabilities — three sentences citing the principle and the rejected alternative, at the top of the task reference. Pattern to roll out across all task pages.
• docs/spec-guidelines.md surfaced in the Protocol nav so the cross-links from the principles page resolve.

Why

Origin: a four-RFC thread on 2026-05-01 where Jeffrey Mayer (DanAds) drafted CPQ pricing, TMP direct-sold signals, bilateral trust, and brand.json verification proposals — each of which got rebuffed in Slack on a wrong-shape premise (proposing a field that doesn't exist; proposing a new task for a behavior already expressible via existing tasks plus modes; framing trust as a centralization problem when the protocol's stance is bilateral). The pattern wasn't ignorance — the philosophy these proposals were missing was distributed across trust.mdx, architecture.mdx, targeting.mdx, and spec-guidelines.md, with no single place a contributor would land.

A four-agent third-party review of the protocol surface (ad-tech-protocol-expert, adtech-product-expert, docs-expert, dx-expert) converged on:

1. The design philosophy is unevenly legible — gold-standard rationale-at-the-point-of-friction in a few pages, none on most task references.
2. The single biggest structural reason wrong-shape RFCs happen: nested feature flags are private details of one schema file, while top-level keys get named everywhere. Proposals naturally land at the level the surface makes visible.
3. The principles page alone won't load-bear — it needs the capabilities-explorer (so the nested surface is as visible as the top level) and the per-task callout (so philosophy meets contributors at the point of friction).

What's in scope vs. out of scope

In scope:

• The principles page, the capabilities explorer, two demo callouts.
• Naming five surface contradictions explicitly (trusted_match placement, axe_integrations, three top-level "things this agent does" lists, three signing-related top-level keys, the trust substrate gap to 4.0).

Out of scope (followups):

• Rolling the "why this shape" callout across all ~30 task reference pages — pattern is demonstrated; rollout is a sweep PR.
• Auto-generating the capabilities-explorer from the schema — current version is hand-curated to one level deep. If the schema sub-namespacing changes, the page needs an update.
• Resolving the named contradictions — those are RFCs in their own right (the page makes them explicit so they land in the queue).

Test plan

• npm run test:docs-nav — passes
• Mintlify preview renders both new pages
• Cross-links from design-principles to capabilities-explorer + spec-guidelines + per-task pages resolve
• CI green

Files

• docs/protocol/design-principles.mdx (new)
• docs/protocol/capabilities-explorer.mdx (new)
• docs/protocol/get_adcp_capabilities.mdx (callout)
• docs/media-buy/task-reference/get_products.mdx (callout)
• docs.json (nav: principles + explorer + spec-guidelines surfaced)
• .changeset/protocol-design-principles.md (empty)
• static/schemas/source/index.json (pre-existing main hygiene fix the verify-version-sync hook required)