adcontextprotocol · bokelley · Apr 16, 2026 · Apr 16, 2026
diff --git a/.changeset/v2-sunset-and-3x-stability-policy.md b/.changeset/v2-sunset-and-3x-stability-policy.md
@@ -0,0 +1,9 @@
+---
+---
+
+docs: add v2 sunset page and 3.x stability guarantees (issues #2220, #2221)
+
+- New `docs/reference/v2-sunset.mdx` documents v2 unsupported as of 3.0 GA, security-only patches through August 1 2026, full deprecation thereafter, and AAO certification/verification policy
+- `docs/reference/versioning.mdx` gains a "3.x stability guarantees" section covering field/enum/error/task guarantees, patch-level semantics, security-fix posture, and breaking-change notice requirements
+- Migration guide index gains a v2-unsupported warning and links to the sunset page; fixes a contradiction about version negotiation
+- Release notes link to both pages
diff --git a/docs.json b/docs.json
@@ -490,6 +490,7 @@
                   "docs/reference/media-channel-taxonomy",
                   "docs/reference/roadmap",
                   "docs/reference/versioning",
+                  "docs/reference/v2-sunset",
                   "docs/reference/release-notes",
                   "docs/reference/changelog",
                   "docs/reference/implementor-faq",

diff --git a/docs/reference/migration/index.mdx b/docs/reference/migration/index.mdx
@@ -9,6 +9,10 @@ description: "A complete guide to migrating AdCP integrations from v2.x to v3.0,
 
 This page covers every breaking change when upgrading from AdCP 2.x to 3.0, with effort estimates and links to detailed migration pages. For new features see [What's new in v3](/docs/reference/whats-new-in-v3); for release-candidate deltas see [prerelease upgrade notes](/docs/reference/migration/prerelease-upgrades).
 
+<Warning>
+**v2 is unsupported as of 3.0 GA and fully deprecated on August 1, 2026 (UTC).** See the [v2 sunset page](/docs/reference/v2-sunset) for the full timeline, AAO registry policy, and why v2 is not safe for interoperable production.
+</Warning>
+
 <Info>
 **Starting from v2?** See the [v3 readiness checklist](/docs/reference/migration/v3-readiness) for the 8 minimum requirements to pass storyboard testing before working through this full migration.
 </Info>
@@ -63,9 +67,11 @@ These capabilities are new in v3. None existed in v2, so there's nothing to migr
 
 ## Running v2 and v3 side by side
 
-During migration, you can run v2 and v3 handlers in parallel. AdCP does not define a version negotiation mechanism at the transport level.
+Dual-support is a temporary migration tool, not a long-term posture. After August 1, 2026, v3-only is the required configuration — see the [v2 sunset page](/docs/reference/v2-sunset).
+
+During migration, sellers can accept both v2 and v3 traffic and buyers can route to each seller on the correct version:
 
-1. **Check seller capabilities** — Call `get_adcp_capabilities` on each seller. If it succeeds, the seller supports v3. If the seller only exposes v2 tools (no `get_adcp_capabilities`), use your v2 code path.
+1. **Check seller capabilities** — Call `get_adcp_capabilities` on each seller. A successful response means the seller supports v3; buyers declare their version via `adcp_major_version` and sellers advertise the versions they accept via `major_versions`. See [version negotiation](/docs/reference/versioning#version-negotiation) for the full flow. A seller that does not respond to `get_adcp_capabilities` is v2-only.
 2. **Branch by seller** — Route v3-capable sellers through your v3 integration and v2-only sellers through your existing v2 code.
 3. **Migrate incrementally** — Start with the rename changes (pricing fields, channel updates), then tackle structural changes (creative assignments, optimization goals), then adopt new capabilities (accounts, governance) as needed.
 

diff --git a/docs/reference/migration/v3-readiness.mdx b/docs/reference/migration/v3-readiness.mdx
@@ -10,7 +10,7 @@ description: "The 8 minimum requirements for seller agents to pass AdCP v3 story
 AdCP storyboard testing requires v3 protocol support. Agents that only support v2 will fail. This page covers the minimum changes to unblock integration testing with v3 buyers — not the full migration. For the complete list, see the [migration guide](/docs/reference/migration).
 
 <Warning>
-Storyboard testing will hard-fail any agent that does not declare v3 support. Complete these 8 items first, then work through the [full migration checklist](/docs/reference/migration).
+Storyboard testing will hard-fail any agent that does not declare v3 support. Complete these 8 items first, then work through the [full migration checklist](/docs/reference/migration). v2 is fully deprecated on August 1, 2026 (UTC) — see the [v2 sunset page](/docs/reference/v2-sunset).
 </Warning>
 
 ---

diff --git a/docs/reference/release-notes.mdx b/docs/reference/release-notes.mdx
@@ -5,7 +5,7 @@ description: "AdCP release notes with version highlights and migration guides. C
 ---
 
 
-High-level summaries of major AdCP releases with migration guidance. For detailed technical changelogs, see [CHANGELOG.md](https://github.com/adcontextprotocol/adcp/blob/main/CHANGELOG.md).
+High-level summaries of major AdCP releases with migration guidance. For detailed technical changelogs, see [CHANGELOG.md](https://github.com/adcontextprotocol/adcp/blob/main/CHANGELOG.md). For version stability, schema-change scope, and the 3.x guarantees see [Versioning & Governance](/docs/reference/versioning). For v2 end-of-life see the [v2 sunset page](/docs/reference/v2-sunset).
 
 ---
 
@@ -831,22 +831,9 @@ First production release of the Advertising Context Protocol with:
 
 ---
 
-## Versioning Policy
+## Versioning and deprecation
 
-AdCP follows [Semantic Versioning 2.0.0](https://semver.org/):
-
-- **PATCH (x.x.N)** - Bug fixes, documentation, clarifications
-- **MINOR (x.N.0)** - New features, backward-compatible additions
-- **MAJOR (N.0.0)** - Breaking changes
-
-### Deprecation Process
-
-Breaking changes follow a 6-month deprecation cycle:
-
-1. **Deprecation Notice** - Feature marked deprecated in minor release
-2. **Transition Period** - Minimum 6 months support with warnings
-3. **Migration Guide** - Detailed upgrade path provided
-4. **Breaking Change** - Removed in next major version
+See [Versioning & Governance](/docs/reference/versioning) for the canonical version tiers, release cadence, 3.x stability guarantees, and deprecation policy. See the [v2 sunset page](/docs/reference/v2-sunset) for the v2 end-of-life timeline.
 
 ---
 

diff --git a/docs/reference/v2-sunset.mdx b/docs/reference/v2-sunset.mdx
@@ -0,0 +1,71 @@
+---
+title: v2 Sunset
+sidebarTitle: v2 sunset
+description: "AdCP v2 is unsupported as of 3.0 GA. Security-only patches through August 1, 2026 (UTC); full deprecation thereafter. Begin migration to 3.0 now."
+"og:title": "AdCP — v2 Sunset"
+---
+
+<Warning>
+**AdCP v2 is not supported and is not safe for interoperable production on the AAO network.** v2 predates the accounts and governance protections that the AAO architecture committee considers essential for live multi-party campaigns. The last v2 release was 2.5.3 in January 2026. Begin migrating to [3.0](/docs/reference/whats-new-in-v3) now.
+</Warning>
+
+## Timeline
+
+| Date (UTC) | Event |
+|---|---|
+| **April 2026** (3.0 GA) | v2 no longer supported by AAO. Security-only patches begin. No feature work. |
+| **August 1, 2026** | v2 fully deprecated. No further patches. Reference documentation archived. |
+
+The v2 sunset is not tied to 4.0. v2 reaches end of life on its own schedule because 2.5 was an early, preliminary version — adoption remained small, and the architecture committee identified protections missing from v2 that cannot be backported without a major redesign.
+
+## What "unsupported" means
+
+As of 3.0 GA:
+
+- **No feature work.** 2.5.3 is the last v2 release. No further minor or patch work in the 2.x line, other than security advisories.
+- **No AAO certification.** Certification requires v3.0 or later.
+- **Not verified in the AAO registry.** Verified seller and agent status requires v3.x. v2-only agents can be registered but cannot be verified.
+- **Frozen schemas.** v2 schemas are frozen as of 2.5.3 and remain at their existing schema URLs. No new fields, tasks, or protocols.
+
+After August 1, 2026 (UTC), v2 is fully deprecated: security patches stop and reference documentation is archived. The 2.5.3 schema URLs continue to resolve so existing integrations do not break silently, but those schemas receive no further updates.
+
+## Why v2 is not safe for interoperable production
+
+v2 is missing protections that 3.0 treats as essential for live multi-party campaigns on the AAO network:
+
+- **No accounts protocol.** Buyers and sellers cannot negotiate account scope, operator authorization, or buyer identity resolution.
+- **No governance.** No structured content standards, audience bias validation, or property list governance.
+- **No campaign governance.** No signed proposals, approval workflow, or proposal lifecycle.
+- **Limited optimization and measurement.** No structured optimization goals, event source health, or streaming/audio delivery metrics.
+
+Running v2 on the AAO network means running without these protections. Private deployments with their own governance and identity layers are the operator's call — but the AAO network treats v2 as out of scope for supported production traffic.
+
+## What to do
+
+### If you run a v2 agent
+
+1. Read [What's new in v3](/docs/reference/whats-new-in-v3).
+2. Work through the [v2→v3 migration guide](/docs/reference/migration).
+3. Validate with [storyboard testing](/docs/reference/migration/v3-readiness).
+4. Complete migration before August 1, 2026 (UTC).
+
+### If you are a buyer integrating with v2 sellers
+
+1. Inventory which of your sellers are v2-only.
+2. Notify them of the August 1, 2026 (UTC) deprecation and share the [migration guide](/docs/reference/migration).
+3. Shift traffic to v3 sellers as they become available.
+
+### If you use the AAO registry
+
+Verified seller and agent status requires v3.x. v2-only agents can be registered but are not eligible for verification. As the registry rolls out verified-default discovery, v2-only entries will not surface by default; endpoints that return unverified entries remain available for operators who need them.
+
+## Dual-support during migration
+
+Sellers in mid-migration can temporarily support both versions using `get_adcp_capabilities` and the `major_versions` array — see [Running v2 and v3 side by side](/docs/reference/migration#running-v2-and-v3-side-by-side). Dual-support is a migration tool, not a long-term posture. After August 1, 2026 (UTC), v3-only is the required configuration.
+
+## Related
+
+- **[What's new in v3](/docs/reference/whats-new-in-v3)** — feature-by-feature summary of what 3.0 adds
+- **[Migration guide](/docs/reference/migration)** — breaking changes and deep-dive pages for every protocol area
+- **[v3 readiness checklist](/docs/reference/migration/v3-readiness)** — 8 minimum requirements for storyboard testing
+- **[Versioning & governance](/docs/reference/versioning)** — 3.x stability guarantees and release cadence
diff --git a/docs/reference/versioning.mdx b/docs/reference/versioning.mdx
@@ -74,6 +74,37 @@ Every release with schema changes is called out in the changelog, release notes,
 
 ---
 
+## 3.x stability guarantees
+
+Implementations built against 3.0 can rely on the following through the 3.x cycle:
+
+| Artifact | Guarantee within 3.x |
+|---|---|
+| **Fields** | Never removed. May be renamed with a documented alias that accepts both names in the same release. Optional → required only after a prior deprecation release. |
+| **Enums** | Only additive. Existing values are never removed or renamed. Clients must tolerate unknown values and fall back to sensible defaults. |
+| **Error codes** | Only additive. Existing codes retain their semantics. Clients that handle unknown error codes generically remain compatible. |
+| **Task names** | Never removed or renamed. New tasks may be added. |
+| **Authentication, transport, core security** | Never changed. These are version-level changes only. |
+
+### Patch releases
+
+A patch release (`3.0.1`, `3.1.2`) changes only documentation, wording, or validation that was diverging from the documented spec. Patches never change schema — no new fields, no renamed fields, no new enum values. Upgrading to the latest patch of your current release is always safe.
+
+### Security fixes
+
+Security-relevant fixes are documented in release notes with a `security` label and land in the current release. Implementations SHOULD upgrade promptly after a security advisory. Older releases within 3.x do not receive routine backports; upgrading to the current release is the expected remediation path. The same posture applies to v2 during its security-only window — see the [v2 sunset page](/docs/reference/v2-sunset) for that timeline.
+
+### Breaking-change notice
+
+Any change that requires an implementation to adapt — renamed field, required-to-optional transition, tightened validation — ships with all of the following:
+
+- An entry in the [release notes](/docs/reference/release-notes) with a migration note
+- An entry in the [changelog](/docs/reference/changelog)
+- A section in the [migration guide](/docs/reference/migration) or a dedicated deep-dive page
+- Where possible, an alias accepting both old and new names in the release that introduces the change
+
+---
+
 ## Release cadence
 
 AdCP releases frequently early in a version cycle (every 6–8 weeks) and stretches toward quarterly as the version stabilizes. This gives builders fast iteration when they need it and predictability when they don't.

diff --git a/docs/reference/whats-new-in-v3.mdx b/docs/reference/whats-new-in-v3.mdx
@@ -6,6 +6,10 @@ description: "What's new in AdCP 3.0: brand identity and rights, creative workfl
 
 AdCP 3.0 expands the protocol beyond media buying into brand identity, governance, media planning, and conversational brand experiences.
 
+<Warning>
+**v2 is unsupported as of 3.0 GA and fully deprecated on August 1, 2026 (UTC).** See the [v2 sunset page](/docs/reference/v2-sunset) for the timeline and AAO registry policy.
+</Warning>
+
 ## At a glance
 
 | Area | v2.x | v3.x |