docs(building): IA Phase 3 — split schemas-and-sdks, add build-a-caller#4031
Merged
Conversation
Phase 3 of the IA reorg in specs/building-ia-by-layer.md. Two pages added, one split, internal cross-refs updated. New: by-layer/L4/build-a-caller.mdx — the missing client-side L4 build guide. Build-shaped (install SDK, discover the agent, make a call, handle the three response shapes, recover from errors, receive webhooks, ingest reporting), distinct from the spec-level wire contract at /docs/protocol/calling-an-agent. Closes the placeholder Card on building/index.mdx that previously linked to the protocol reference. Split: schemas-and-sdks.mdx → two pages: - by-layer/L0/schemas.mdx (new) — the wire-layer reference: schema access, protocol tarball, Sigstore signature verification, compliance storyboards, common schemas, schema versioning, bundled schemas, version discovery, registry API. - by-layer/L4/choose-your-sdk.mdx (new) — the adopter decision: AdCP 3.0 support matrix, coverage matrix, JS/Python/Go install + sample code, package exports, CLI tools. - schemas-and-sdks.mdx deleted — redirect added. Nav rewritten (both 3.0 and latest blocks): - L0 group: index → schemas → mcp-guide → a2a-guide → ... - L4 group: index → choose-your-sdk → build-an-agent → build-a-caller → migrate-from-hand-rolled - Cross-cutting: schemas-and-sdks removed (replaced by L0/L4 pages). Internal cross-references updated in 7 docs files. Out-of-tree updates to server/public/llms.txt, llms-full.txt, schemas-middleware.ts, and template-literal URLs in certification-tools.ts. FQDN URLs in check:owned-links scope intentionally left at old paths per the post-merge sweep policy in #4025. Will 30x to canonical post- deploy via the new redirect. Phase 3 status: - ✅ Item 1 (split schemas-and-sdks) — done. - ✅ Item 2 (build-a-caller) — done. - ⏸ Item 3 (verification placement) — deferred awaiting AAO Verified L3/L4 reframing per #3925, #3046. Cross-link comments posted. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Address dx-expert + copywriter on PR #4031: build-a-caller.mdx: - Added Authenticate section between Install and First call (most common first-call failure is missing creds, not capability mismatch) - Replaced placeholder createWebhookReceiver({ resolveKey: /* … */ }) with the zero-config form; the SDK does brand.json discovery by default, so the simpler example is what 95% of adopters need - Tightened reporting section: dropped the comment-only stream-style placeholder; left a real getMediaBuyDelivery example with a window - Cut sales-close residue: "starting page for you" → "start here", "naïve callers create duplicate buys" → "creates duplicate buys", "the SDK helps but doesn't decide for you" → cut, "If you also configure" → "If you configure", "that's where your team's value lives" → cut choose-your-sdk.mdx: - Merged the AdCP 3.0 support table into the coverage matrix as a Minimum 3.0 / Current column pair (avoids the prior 5.13.0 vs 6.7.0 drift that confused readers scanning the page) - Replaced⚠️ cells' opaque "Row to refresh" editorial leak with a user-facing "Coverage updates on 4.0 GA" + a paragraph below the matrix naming what's specifically missing in Python (RFC 9421 signing, brand-resolution helpers, webhook emission) and Go (types + transport only) so adopters can tell whether the gap blocks them - Cut "there's no benefit to switching languages..." sentence; the matrix shows the conformance-bar parity - "first-class languages" framing rewritten to lead with what carries full L0–L4 coverage rather than the doubled qualifier schemas.mdx: - Removed the orphaned "### For AI coding agents" H3 — folded the Tip block in directly with the AI-coding-agent framing inside it. The H3 promised content the Tip didn't deliver. verification/get-test-ready.mdx: - Bumped @adcp/client pin from ^5.8.0 to ^5.13.0 (the 3.0 floor declared on choose-your-sdk). Was a real adopter footgun: copy-paste from get-test-ready and you don't get 3.0. Anchors flagged as "broken" by dx-expert (#account-is-oneof--... and #error-recovery--read-issues) verified correct; mintlify broken-links passes locally — Mintlify slugifies em-dash to "--", matching the link syntax. No fix needed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced May 3, 2026
bokelley
pushed a commit
that referenced
this pull request
May 3, 2026
Closes #1733 Adds docs/building/operating/tmp-provider.mdx — a step-by-step guide for TMP providers implementing POST /context and POST /identity endpoints. File placed in docs/building/operating/ to match seller-integration.mdx pattern established by IA Phase 2 (#4022). Registered in both nav blocks after seller-integration; redirect added from old implementation/ path. Non-breaking justification: adds one new docs page, two nav entries, and one redirect; no existing file is modified; no schema changes. Rebased onto main to resolve CI drift from IA Phase 2/3 doc restructuring (#4022, #4031) that moved the Implementation Patterns nav section. Session: https://claude.ai/code/session_011jy4RA7uEWHe6n7nzuoZtZ
Merged
4 tasks
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>
3 tasks
3 tasks
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
Phase 3 of the IA reorg in
specs/building-ia-by-layer.md. Two pages added, one split, internal cross-refs updated.New:
by-layer/L4/build-a-caller.mdx— the missing client-side L4 build guide. Build-shaped (install SDK, discover the agent, make a call, handle the three response shapes, recover from errors, receive webhooks, ingest reporting). Distinct from the spec-level wire contract at/docs/protocol/calling-an-agent. Closes the placeholder Card onbuilding/index.mdxthat previously linked to the protocol reference.Split:
schemas-and-sdks.mdx→ two pages:by-layer/L0/schemas.mdx(new) — the wire-layer reference (schema access, protocol tarball, Sigstore verification, compliance storyboards, schema versioning, bundled schemas, registry API).by-layer/L4/choose-your-sdk.mdx(new) — the adopter decision (AdCP 3.0 matrix, coverage matrix, JS/Python/Go install + sample code, CLI tools).schemas-and-sdks.mdxdeleted; redirect added.Nav rewritten in both 3.0 and latest blocks. L0 group now leads with
schemas. L4 group:index → choose-your-sdk → build-an-agent → build-a-caller → migrate-from-hand-rolled. Cross-cutting dropsschemas-and-sdks.Internal cross-references updated in 7 docs files plus
server/public/llms.txt,llms-full.txt,schemas-middleware.ts, and template-literal URLs incertification-tools.ts. FQDN URLs incheck:owned-linksscope intentionally left at old paths per #4025 (will 30x post-deploy).Phase 3 status
Test plan
mintlify broken-linkspasses locallydocs.jsonJSON validates/docs/building/schemas-and-sdksreferences rewritten indocs/schemasin L0 andbuild-a-caller+choose-your-sdkin L4🤖 Generated with Claude Code