docs: document schema URL convention for MDX links

[bokelley]

Closes #3634

Contributors writing MDX docs naturally reach for bare /schemas/enums/foo.json paths when linking to a JSON schema — it's how schemas are referenced everywhere else in the repo ($ref, changeset text, commit messages). But the Mintlify broken-links checker rejects bare paths: they're not Mintlify pages, they're external artifacts. The correct convention (use absolute https://adcontextprotocol.org/schemas/v3/... URLs) existed only in .agents/playbook.md, invisible to contributors.

This PR adds the convention to contributor-facing docs in three places:

• docs/contributing/schema-links.md (new) — full guidance page following the existing x-entity-annotation.md / testable-snippets.md pattern. Covers released vs. unreleased schemas, the $schema-vs-hyperlink distinction, and both CI validators (mintlify broken-links + check-schema-links.yml).
• CONTRIBUTING.md — one-line pointer under "Schema conventions" linking to the new page.
• docs/building/schemas-and-sdks.mdx — <Note> cross-link at the Schema Versioning section, where contributors reading about schema URLs are most likely to need this guidance.

Non-breaking justification: adds new docs/content only; no schema, protocol, or API surface changed; existing consumers unaffected.

Pre-PR review:

• code-reviewer: approved — 2 blockers caught and fixed (stale 3.0.0-rc.3 version ref → 3.0.1; released schema used as "unreleased" example → replaced with core/account-authorization.json); 1 nit (CONTRIBUTING.md link pattern) fixed; changeset verified
• docs-expert: approved — audience fit correct, structure follows existing contributing-docs pattern, cross-links adequate; same blockers caught and fixed

Triage-managed PR. This bot does not currently iterate on
review comments or PR conversation threads (only on the source
issue). To unblock:

• Push fixup commits directly: gh pr checkout <num> →
  fix → push.
• Or re-trigger: comment /triage execute on the source
  issue.

See #3121
for context.

Session: https://claude.ai/code/session_01MzMHhmkVpMuiLTnCVLpJWx

---

Generated by Claude Code

[bokelley]

Pushing back on this PR — the convention it documents is wrong for the most common case.

https://adcontextprotocol.org/schemas/v3/... is the prod URL for shipped schemas. But active spec work — including the PR (#3576) that surfaced this issue in the first place — adds new fields to schemas before they ship. Linking to the prod URL during in-flight work either 404s or shows stale content that doesn't have the field the doc is talking about.

Concretely: PR #3576 adds qualifier to package.committed_metrics. If I link from create_media_buy.mdx to https://adcontextprotocol.org/schemas/v3/core/package.json, the linked artifact won't have that field until #3576 ships. So the doc and the linked schema disagree, and the disagreement is permanent until release. This is the common case for spec authors, not an edge case.

Documenting "use prod URLs" trains contributors into a habit that breaks exactly when they need links most.

The right fix is environment-aware resolution, not a doc patch:

• Local dev: /schemas/... resolves to http://localhost:3000/schemas/latest/... (or whatever the dev server serves)
• PR preview: resolves to the Mintlify preview's bundled schemas
• Prod build: resolves to https://adcontextprotocol.org/schemas/v3/...

Three programmatic options, in increasing order of invasiveness:

1. remark/rehype plugin that rewrites /schemas/... based on env. ~50 lines.
2. Build step copies dist/schemas/latest/ into the Mintlify content tree at a path that /schemas/... natively resolves to. Schemas become real docs-site artifacts; the link checker is happy.
3. <SchemaLink id="..."> MDX component that resolves at render time.

Proposing:

• Close this PR. Documenting the prod-URL convention misleads contributors during active dev.
• Re-scope Mintlify link checker rejects bare /schemas/... paths; convention is undocumented #3634 to land one of the programmatic fixes above. If we can't land that immediately, the honest doc patch would be: "schema links from MDX are currently broken for in-flight work — code-format the filename in prose and skip the link until env-aware resolution lands."

cc @bokelley

[bokelley]

Closing per #3634 re-scope — the convention this PR documents is wrong for in-flight schema work. The right fix is programmatic env-aware resolution, tracked in #3634.