docs(building): fix AAO hallucination, reframe sdk-stack, add IA spec#4017
Merged
Conversation
Four edits to docs/building/sdk-stack.mdx: 1. Fix AAO expansion. The L2 bullet expanded AAO as "AdCP Authorization Object" linking to a non-existent /docs/aao page. AAO is AgenticAdvertising.org. Rewrote the bullet to describe what the SDK's AAO bridge actually resolves (member org, AAO Verified badges, registry visibility) with links to /docs/registry/registering-an-agent and /docs/building/aao-verified. 2. Reframe the intro and "early implementers" section. Opening previously called out "two audiences arriving at the same wrong conclusion" and the later section was titled "What early implementers underestimate" — both read as telling the reader they're wrong before laying out the data. Reframed around "where do you want to spend your engineering time?" so the cost decompositions later in the page do the persuasion. 3. Name Python + TypeScript as first-class supported languages and add a contribution CTA. Above the SDK coverage snapshot, called out that Python and TypeScript are committed to full L0–L4 coverage (TypeScript GA today, Python in flight on 4.x), Go is moving in the same direction, and community-maintained ports for other languages are welcome — with links to the Builders Working Group page and the AgenticAds Slack invite. 4. Thread server/client asymmetry through the layer model. The L0–L4 model previously read as if it described an agent only. Added an intro paragraph naming both sides, *Client side* notes at L0–L4, and a new "Server vs client at each layer" comparison table after L4 showing the cost asymmetry (a from-scratch caller is weeks-to-month at L0–L3; a from-scratch agent is the 3–4 person-month build documented later). Also flagged that the SDK coverage checklist describes the server surface and named the parallel client-side primitives an SDK should ship. Plus: specs/building-ia-by-layer.md — proposed information architecture for /docs/building organized by the L0–L4 spine. Five decisions locked (rename Concepts, keep hosted-implementations table on sdk-stack, three- level sidebar depth with default-collapse, side-band callout pattern for client/server asymmetry, fork /docs/protocol/calling-an-agent into a build guide). One deferred (verification placement) pending the AAO Verified L3/L4 reframing tracked under #3925 and #3046. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Address review feedback from dx-expert / copywriter / docs-expert on PR #4017: Copy tightenings on docs/building/sdk-stack.mdx: - Drop "rather than reflexive" — same finger-wag as the old "wrong conclusion" framing - Drop two "Worth a look" sales-close phrasings (intro bullet + TL;DR closer) - "in the room from the start" → "visible up front" - "Five recurring scope-surprises" → "Five places L3 cost concentrates" (less leading) - "Your competitive surface as a seller/buyer" → "What differentiates you as a seller/buyer" (page hadn't earned the jargon) - Drop "SDK authors should treat the client surface as a parallel obligation, not an afterthought" — manifesto tone - "first-class supported languages" → "first-class languages" (doubled qualifier) Number consistency: client L3 was "days-to-weeks" in one note vs "weeks-to-month" in the comparison table prose. Reconciled to "weeks of handler glue" in both places, plus a brief decomposition in the table prose ("handler glue, signing, registry lookup, response parsing"). Caller-side: - Added a "Caller-only?" jump-link near the top of "The five layers" pointing at the comparison table - Added a link from the L4 client-side note to /docs/protocol/calling-an-agent so caller readers have an onward path specs/building-ia-by-layer.md: added the three missing index.mdx rows the docs-expert flagged (understanding/index → concepts/index rename; integration/index and implementation/index deleted with redirects to the most-cited new layer landings). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
5 tasks
bokelley
added a commit
that referenced
this pull request
May 3, 2026
Address review feedback from dx-expert / copywriter / docs-expert on PR #4020: Copy tightenings (preachy/jargon residue from where-to-start.mdx source): - "going lower because you have a specific reason to" → "going lower" - Drop "Your competitive surface is what you build on top of the protocol, not the protocol itself" — same finger-wag pattern as #4017 - Drop "Going lower is rarely the win it looks like" → "See [what you write at each layer] before going lower" - Drop "The default path for sellers, publishers, and platforms" — gentle steering - "Picking a starting layer = picking how much of L0–L3 you take on yourself" → "Where you start determines how much of L0–L3 you own" - Match Go description to sdk-stack ("L0 and partial L1 in active development" vs vague "in active development") Structure (dx-expert: drop Q1, keep Q2/Q3): - "Three questions to confirm your entry point" → "Two checks before you start" - Dropped Q1 (caller-vs-agent-vs-both) — already routed by the CardGroup; was redundant - Q2 and Q3 retained (value-add and hand-rolled re-evaluation actually shift the decision) L0–L4 SDK package anchors (dx-expert: agent buildability): - Each layer bullet now names the canonical SDK entry point ("In SDKs:" suffix) - L4 explicitly marked "Not in any SDK — adopter writes this" Caller card honesty (dx-expert: pit of failure): - Build a caller card now flags that the destination is the protocol reference until the build-shaped guide ships in a later IA phase - Links the IA spec on GitHub for context Validation pointer (docs-expert: missing after-build step): - Added "After your first build: run Validate your agent... then enroll for AAO Verified" line under the CardGroup Anchor accuracy (docs-expert: prose overpromise): - "what you give up" → "what you write at each layer" — matches what's actually at the #where-can-you-start anchor (the layer-entry table, not a cost framing) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
bokelley
added a commit
that referenced
this pull request
May 3, 2026
…A Phase 1) (#4020) * docs(building): rewrite /building overview as single decision page Phase 1 of the IA reorg in specs/building-ia-by-layer.md. Rewrote docs/building/index.mdx from a section-overview-with-CardGroups page into a single decision page that opens with "where do you want to spend your engineering time?" and routes the reader to one of four entry points (build an agent, build a caller, migrate from hand-rolled, go lower than L4). Absorbs content from docs/building/where-to-start.mdx: - The five-layers-in-one-paragraph summary - The "recommended path" framing (95% of adopters: start at L4) - The three-questions decision flow (caller-vs-agent, what's-your-value- add, hand-rolled-already) where-to-start.mdx left in place per the phasing plan; it'll be merged or redirected in a later PR. The two pages now overlap on content but the new index is the primary entry point from the section header. Cross-cutting concerns (schemas, version adaptation, conformance, AAO Verified, operating) get their own section. "Going deeper" links into the existing Understanding / Foundations / Implementation subgroups so they remain discoverable until the layered reorg lands in PR2. Caller-side gets a parallel Card to the agent-side build path (currently linking to /docs/protocol/calling-an-agent since the build-shaped build-a-caller page doesn't exist yet — that's a Phase 3 deliverable). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(building): apply review feedback to /building decision page Address review feedback from dx-expert / copywriter / docs-expert on PR #4020: Copy tightenings (preachy/jargon residue from where-to-start.mdx source): - "going lower because you have a specific reason to" → "going lower" - Drop "Your competitive surface is what you build on top of the protocol, not the protocol itself" — same finger-wag pattern as #4017 - Drop "Going lower is rarely the win it looks like" → "See [what you write at each layer] before going lower" - Drop "The default path for sellers, publishers, and platforms" — gentle steering - "Picking a starting layer = picking how much of L0–L3 you take on yourself" → "Where you start determines how much of L0–L3 you own" - Match Go description to sdk-stack ("L0 and partial L1 in active development" vs vague "in active development") Structure (dx-expert: drop Q1, keep Q2/Q3): - "Three questions to confirm your entry point" → "Two checks before you start" - Dropped Q1 (caller-vs-agent-vs-both) — already routed by the CardGroup; was redundant - Q2 and Q3 retained (value-add and hand-rolled re-evaluation actually shift the decision) L0–L4 SDK package anchors (dx-expert: agent buildability): - Each layer bullet now names the canonical SDK entry point ("In SDKs:" suffix) - L4 explicitly marked "Not in any SDK — adopter writes this" Caller card honesty (dx-expert: pit of failure): - Build a caller card now flags that the destination is the protocol reference until the build-shaped guide ships in a later IA phase - Links the IA spec on GitHub for context Validation pointer (docs-expert: missing after-build step): - Added "After your first build: run Validate your agent... then enroll for AAO Verified" line under the CardGroup Anchor accuracy (docs-expert: prose overpromise): - "what you give up" → "what you write at each layer" — matches what's actually at the #where-can-you-start anchor (the layer-entry table, not a cost framing) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
8 tasks
bokelley
added a commit
that referenced
this pull request
May 3, 2026
…edirects) (#4022) * docs(building): IA Phase 2 — relocate pages by layer, add redirects + nav Phase 2 of the IA reorg in specs/building-ia-by-layer.md (merged in #4017, decision page in #4020). Mechanical relocation of /docs/building/ pages into the layered structure the spec proposed. Page moves (~41 pages): - build-an-agent, migrate-from-hand-rolled → by-layer/L4/ - implementation/{task-lifecycle,async-operations,webhooks, error-handling,comply-test-controller} → by-layer/L3/ - integration/{authentication,account-state,accounts-and-agents, context-sessions} → by-layer/L2/ - implementation/{security,webhook-verifier-tuning} → by-layer/L1/ - integration/{mcp-guide,a2a-guide,a2a-response-format} + implementation/{mcp,a2a}-response-extraction → by-layer/L0/ - understanding/* (6 pages) → concepts/* (renamed group) - sdk-stack, version-adaptation, implementation/known-ambiguities → cross-cutting/ - operating-an-agent, implementation/{orchestrator-design, transport-errors,seller-integration,storyboard-troubleshooting} → operating/ - conformance, compliance-catalog, validate-your-agent, grading, get-test-ready, aao-verified → verification/ Deleted: where-to-start.mdx, integration/index.mdx, implementation/index.mdx — replaced by the new layer landings and the Phase 1 decision page. New layer-landing index.mdx stubs at by-layer/L0/index, L1/index, L2/index, L3/index, L4/index. docs.json nav rewritten in both "3.0" and "latest" version blocks. New structure: Concepts → Build by layer (L4/L3/L2/L1/L0) → Cross-cutting → Schemas → Verification & trust → Operating. Default-expand is on L4 only. 43 redirects added so every old URL keeps working transparently. External references (~114 files outside /docs/building/) intentionally NOT swept — Mintlify redirects handle them. Out-of-tree updates so Addie's URL knowledge stays canonical (not redirected): server/src/addie/mcp/certification-tools.ts (~16 URLs), server/src/addie/prompts.ts (1 URL), server/src/addie/rules/urls.md (3 URLs). scripts/build-protocol-tarball.cjs (1 URL). Tests: tests/addie/cross-publisher-frequency-docs.test.ts updated for the understanding → concepts rename. Followups: server/public/llms.txt and llms-full.txt are autogenerated flat files with stale building paths — they'll regenerate next build. server/public/stories/the-studio.html and community/hub.html have hardcoded old URLs — work via redirect, low priority. Deferred to Phase 3: splitting schemas-and-sdks.mdx into by-layer/L0/schemas + by-layer/L4/choose-your-sdk; creating the build-shaped by-layer/L4/build-a-caller.mdx; verification-section placement (top-level vs nested) pending the AAO Verified L3/L4 reframing per #3925 / #3046. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(building): apply review feedback — external sweep + nav nit Address review feedback from dx-expert / docs-expert / code-reviewer on PR #4022: External canonical-source sweep (docs-expert): paths in these files are structural identifiers (compliance runners may key off literal strings) or ship in SDK source (schema descriptions land in generated types). Mintlify redirects don't cover these surfaces. - static/compliance/source/test-kits/signed-requests-runner.yaml (verifier_checklist: field) - static/compliance/source/test-kits/webhook-receiver-runner.yaml (spec_section: field) - static/compliance/source/universal/{security,signed-requests}.yaml - static/compliance/source/test-vectors/request-signing/README.md - static/compliance/source/test-vectors/webhook-signing/README.md - static/schemas/source/protocol/get-adcp-capabilities-response.json (description strings that ship in @adcp/sdk + adcp Python types) - server/public/llms.txt and llms-full.txt (canonical agent index; agents that consume llms.txt as truth would have seen stale paths) These all rewrite to the new layered paths so the canonical source- of-truth files stay accurate going forward. Nav nit (dx-expert): schemas-and-sdks was an orphaned top-level entry between Cross-cutting and Verification. Folded it into the Cross- cutting group as the fourth entry. Updated both 3.0 and latest version blocks in docs.json. Layer-landing anchor consistency (dx-expert nit): verified all five by-layer/L*/index.mdx stubs deep-link to sdk-stack#l<n>--... anchors. L0/L1/L2/L3 use the per-layer anchors; L4 links to the top of sdk-stack (correct — L4 isn't decomposed there because L4 is the adopter's surface, not an SDK contract). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(building): revert server-source FQDN URLs to old paths for CI CI's check:owned-links job fetches each https://docs.adcontextprotocol.org/... URL referenced in server/src/addie/ files and 404s when the URL doesn't resolve on production docs. The new layered paths added in this PR (e.g. /docs/building/by-layer/L4/build-an-agent) only become live once docs.json deploys with the redirects — chicken-and-egg before merge. Reverted 5 FQDN URL literals in server-source files back to OLD paths so they hit live redirects on merge: - server/src/addie/rules/urls.md (4 URLs) - server/src/addie/rules/knowledge.md (3 URLs) - server/src/addie/rules/behaviors.md (3 URLs) - server/src/addie/mcp/certification-tools.ts (3 URL literals) - server/src/addie/prompts.ts (1 URL) Template-literal URLs (~16 of `${DOCS_BASE}/docs/...`) in certification-tools.ts were left at new paths — the check:owned-links script filters out URLs containing `${`, so they're not validated against production. Functionally they work either way once redirects deploy. Follow-up after merge + deploy: a single sweep PR can update all server-source paths to canonical (no-redirect) once redirects are live on production. Until then, the old paths 30x correctly via Mintlify. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
bokelley
added a commit
that referenced
this pull request
May 3, 2026
…ths (closes #4025) (#4034) The IA reorg in PRs #4017 / #4020 / #4022 / #4031 / #4032 / #4033 moved /docs/building/ pages into a layered structure. Mintlify redirects keep old URLs working, but Addie's source-of-truth URL knowledge still cited the old paths — meaning Addie handed users redirected URLs (30x → canonical instead of canonical directly). Tracked under #4025 as a post-deploy follow-up: check:owned-links couldn't pass with the new paths until the redirect deploy was live on production. Verified deploy state before this PR (all five new paths return 200 directly). 13 FQDN URLs updated across 5 files: - server/src/addie/rules/urls.md (4 URLs) - server/src/addie/rules/knowledge.md (4 URLs) - server/src/addie/rules/behaviors.md (3 URLs) - server/src/addie/mcp/certification-tools.ts (3 URL constants) - server/src/addie/prompts.ts (2 URLs) Mapping matches the redirects[] in docs.json: - /docs/building/build-an-agent → by-layer/L4/build-an-agent - /docs/building/validate-your-agent → verification/validate-your-agent - /docs/building/schemas-and-sdks → by-layer/L4/choose-your-sdk - /docs/building/understanding/adcp-vs-openrtb → concepts/adcp-vs-openrtb - /docs/building/implementation/seller-integration → operating/seller-integration Note: schemas-and-sdks was split in Phase 3 (PR #4031) into L0/schemas (wire-layer reference) and L4/choose-your-sdk (SDK list / coverage matrix / install / CLI). All Addie's pre-existing references were SDK-list shaped, so they map to choose-your-sdk. npm run check:owned-links passes locally. Closes #4025 Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Four edits to
docs/building/sdk-stack.mdx:Fix AAO expansion. The L2 bullet expanded AAO as "AdCP Authorization Object" linking to a non-existent
/docs/aaopage. AAO is AgenticAdvertising.org. Rewrote the bullet to describe what the SDK's AAO bridge actually resolves (member org, AAO Verified badges, registry visibility) with links to the registry and AAO Verified pages.Reframe the intro and "early implementers" section. Opening previously called out "two audiences arriving at the same wrong conclusion" and the later section was titled "What early implementers underestimate" — both read as telling the reader they're wrong before laying out the data. Reframed around "where do you want to spend your engineering time?" so the cost decompositions later in the page do the persuasion.
Name Python + TypeScript as first-class supported languages and add a contribution CTA. Above the SDK coverage snapshot, called out that Python and TypeScript are committed to full L0–L4 coverage (TypeScript GA today, Python in flight on 4.x), Go is moving in the same direction, and community-maintained ports for other languages are welcome — with links to the Builders Working Group page and the AgenticAds Slack invite.
Thread server/client asymmetry through the layer model. The L0–L4 model previously read as if it described an agent only. Added an intro paragraph naming both sides, Client side notes at L0–L4, and a new "Server vs client at each layer" comparison table after L4 showing the cost asymmetry. Also flagged that the SDK coverage checklist describes the server surface and named the parallel client-side primitives an SDK should ship.
Plus:
specs/building-ia-by-layer.md— proposed information architecture for/docs/buildingorganized by the L0–L4 spine. Five decisions locked (rename Concepts, keep hosted-implementations table on sdk-stack, three-level sidebar depth with default-collapse, side-band callout pattern for client/server asymmetry, fork/docs/protocol/calling-an-agentinto a build guide). One deferred (verification placement) pending the AAO Verified L3/L4 reframing tracked under #3925 and #3046.This is Phase 0 of a multi-PR sequence; the spec lays out the remaining PRs (decision-page rewrite, mechanical move, schemas-and-sdks split).
Test plan
/docs/registry/registering-an-agent,/docs/building/aao-verified,/docs/community/working-groupexist)🤖 Generated with Claude Code