docs: layered architecture, decision page, version-adaptation guide

[bokelley]

Summary

Reorients adopters around how much of L0–L3 they want to inherit from @adcp/sdk vs. write themselves. Targets two recurring wrong conclusions:

1. Early implementers who built before the SDKs were mature and have a frozen-in-time picture of "what the SDK does." Most of L3 (lifecycle state machines, idempotency, conformance test surface, RFC 9421 baseline, expanded error catalog) was added with AdCP 3.0.
2. New implementers who say "I'll roll my own AdCP agent, I don't need an SDK" without seeing the L0–L3 scope.

What's in it

• docs/architecture/adcp-stack.md (new) — full L0–L4 reference. Each layer: what it does, what's in it, what an SDK at that layer should provide, what you give up by skipping it. Includes the version-adaptation summary and a "what early implementers underestimate" punch list.
• docs/where-to-start.md (new) — short decision page. Three questions (caller vs. agent / value-add / pre-existing hand-rolled), recommended path for ~95% of adopters, "what you give up by going lower" cost table.
• docs/guides/VERSION-ADAPTATION.md (new) — code-level recipes for the three version-handling mechanisms:
  1. Per-call adcpVersion pinning + bundle-gated runtime acceptance + ConfigurationError semantics
  2. @adcp/sdk/server/legacy/v5 subpath co-existence imports
  3. Wire-level supported_versions declaration with VERSION_UNSUPPORTED envelope and VersionUnsupportedError typed throw
• Wiring — top-of-page callouts on index.md, getting-started.md, guides/BUILD-AN-AGENT.md route mis-aimed readers to where-to-start.md without blocking on-target ones. Cross-link to CONFORMANCE.md from L3 + early-implementer item Fix Fly.io deployment timeout issues #2.

Reviewed by

• DX expert: caught three signature/semantics errors in the version-adaptation code samples (createAdcpServerFromPlatform(platform, opts) two positional args, bundle-gated vs. major-gated runtime acceptance, VersionUnsupportedError pre-flight throw alongside the envelope read). All addressed.
• Docs expert: caught the redundant layer table between where-to-start.md and adcp-stack.md (resolved by single-sourcing in the architecture doc), the "no single SDK" / "95% start at L4" tone tension (resolved with a bridge sentence), and a broken protocol-overview.md link in index.md (resolved by removal). Cross-linking gaps to CONFORMANCE.md filled.

Notes for reviewers

• Code samples were verified against src/lib/version.ts, src/lib/utils/adcp-version-config.ts, src/lib/core/SingleAgentClient.ts, src/lib/server/create-adcp-server.ts, src/lib/server/decisioning/runtime/from-platform.ts, and examples/decisioning-platform-mock-seller.ts.
• docs/architecture/adcp-stack.md was originally drafted on a sibling feature branch; this PR brings the file (with the reviewer-driven edits) into main directly. Order with that branch is fine either way — feature branch will rebase cleanly.

Test plan

• Markdown renders cleanly on the docs site
• All internal links resolve (./architecture/adcp-stack.md, ./guides/VERSION-ADAPTATION.md, ./where-to-start.md, ./guides/CONFORMANCE.md, ./guides/BUILD-AN-AGENT.md#two-paths)
• No conflict with the Account.mode feature branch on merge

🤖 Generated with Claude Code