adcontextprotocol · garvitkaushik-123 · Jun 27, 2026
diff --git a/docs/accounts/overview.mdx b/docs/accounts/overview.mdx
@@ -41,7 +41,7 @@ The Accounts Protocol applies across all vendor protocols. An orchestrator estab
 | Governance | Content standards billing |
 | Creative | Creative service billing |
 
-The account reference may be a seller-assigned `account_id` (seller-owned namespaces, usually `require_operator_auth: true`) or a natural key — `brand` + `operator` (buyer-declared accounts, `require_operator_auth: false`). For buyer-declared accounts, the natural-key `AccountRef` MUST remain valid on subsequent calls even if the seller also echoes an internal `account_id`. For sandbox, account-id namespaces use pre-existing test accounts discovered via `list_accounts` or supplied out-of-band, while buyer-declared accounts declare sandbox via `sync_accounts` with `sandbox: true`. See [Account references](/docs/building/integration/accounts-and-agents#account-references) for details.
+The account reference may be a seller-assigned `account_id` (seller-owned namespaces, usually `require_operator_auth: true`) or a natural key — `brand` + `operator` (buyer-declared accounts, `require_operator_auth: false`). For buyer-declared accounts, the natural-key `AccountRef` MUST remain valid on subsequent calls even if the seller also echoes an internal `account_id`. For sandbox, account-id namespaces use pre-existing test accounts discovered via `list_accounts` or supplied out-of-band, while buyer-declared accounts declare sandbox via `sync_accounts` with `sandbox: true`. See [Account references](/docs/building/by-layer/L2/accounts-and-agents#account-references) for details.
 
 ## Account Status Lifecycle
 
@@ -182,7 +182,7 @@ A single `SCOPE_INSUFFICIENT` response is observationally indistinguishable betw
 
 `FIELD_NOT_PERMITTED` does not follow this pattern. The agent-autonomous recovery path — strip the disallowed field and resubmit — supersedes the retry consideration. Buyers MUST NOT retry the identical failing request for `FIELD_NOT_PERMITTED`; they SHOULD correct and resubmit immediately.
 
-See [Authorization (RBAC)](/docs/building/implementation/error-handling#authorization-rbac) for the normative retry exception clause on these codes.
+See [Authorization (RBAC)](/docs/building/by-layer/L3/error-handling#authorization-rbac) for the normative retry exception clause on these codes.
 
 ### Standard named scope: `attestation_verifier`
 
@@ -258,7 +258,7 @@ The introspection model — "the caller asks the authorization-enforcing party w
 
 ## Parties
 
-The Accounts Protocol operates with four party types. See [Accounts and agents](/docs/building/integration/accounts-and-agents) for full details on billing hierarchy, trust models, and authorized operators.
+The Accounts Protocol operates with four party types. See [Accounts and agents](/docs/building/by-layer/L2/accounts-and-agents) for full details on billing hierarchy, trust models, and authorized operators.
 
 | Party | Role | Identified by |
 |-----------|------|---------------|

diff --git a/docs/accounts/tasks/get_account_financials.mdx b/docs/accounts/tasks/get_account_financials.mdx
@@ -76,7 +76,7 @@ asyncio.run(main())
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `account` | object | Yes | [Account reference](/docs/building/integration/accounts-and-agents#account-references) — by `account_id` or natural key (`brand` + `operator` + optional `sandbox`). Must be an operator-billed account. |
+| `account` | object | Yes | [Account reference](/docs/building/by-layer/L2/accounts-and-agents#account-references) — by `account_id` or natural key (`brand` + `operator` + optional `sandbox`). Must be an operator-billed account. |
 | `period` | object | No | Date range for spend summary: `start` and `end` as ISO 8601 dates. Defaults to the current billing cycle if omitted. |
 
 ## Response
@@ -230,4 +230,4 @@ asyncio.run(main())
 
 - [list_accounts](/docs/accounts/tasks/list_accounts) -- Discover accounts and check their status
 - [get_adcp_capabilities](/docs/protocol/get_adcp_capabilities) -- Check `account_financials` before calling this task
-- [Accounts and agents](/docs/building/integration/accounts-and-agents) -- Billing models and account references
+- [Accounts and agents](/docs/building/by-layer/L2/accounts-and-agents) -- Billing models and account references
diff --git a/docs/accounts/tasks/list_accounts.mdx b/docs/accounts/tasks/list_accounts.mdx
@@ -92,7 +92,7 @@ the authenticated caller. Use `account` when re-reading one known account by
 | `operator` | Operator domain. Always present — when the brand operates directly, `operator` equals the brand's domain. |
 | `status` | Current account state: `active`, `pending_approval`, `rejected`, `payment_required`, `suspended`, or `closed` |
 | `billing` | Billing model in effect: `operator` or `agent` |
-| `account_scope` | How the seller scoped this account: `operator`, `brand`, `operator_brand`, or `agent`. See [account scope](/docs/building/integration/accounts-and-agents#account-scope). |
+| `account_scope` | How the seller scoped this account: `operator`, `brand`, `operator_brand`, or `agent`. See [account scope](/docs/building/by-layer/L2/accounts-and-agents#account-scope). |
 | `payment_terms` | Payment terms agreed for this account: `net_15`, `net_30`, `net_45`, `net_60`, `net_90`, or `prepay`. Binding for all invoices when the account is active. |
 | `governance_agents` | Governance agent endpoints registered on this account. Present when governance agents have been configured via [`sync_governance`](/docs/accounts/tasks/sync_governance). |
 | `setup` | Present when `status: "pending_approval"`. Contains `url` for completing setup and `message` explaining what's needed. |
@@ -229,5 +229,5 @@ asyncio.run(main())
 
 - [sync_accounts](/docs/accounts/tasks/sync_accounts) — Sync advertiser accounts with a seller
 - [sync_governance](/docs/accounts/tasks/sync_governance) — Sync governance agents to accounts
-- [Accounts and agents](/docs/building/integration/accounts-and-agents) — Billing models, trust models, and authorized operators
+- [Accounts and agents](/docs/building/by-layer/L2/accounts-and-agents) — Billing models, trust models, and authorized operators
 - [Brand protocol](/docs/brand-protocol/brand-json) — How vendor agents resolve brand identity from the brand's `domain`
diff --git a/docs/accounts/tasks/report_usage.mdx b/docs/accounts/tasks/report_usage.mdx
@@ -28,7 +28,7 @@ Each record requires `account`, `vendor_cost`, and `currency`. Additional fields
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `account` | [AccountRef](/docs/building/integration/accounts-and-agents#account-references) | Yes | Account for this record — by `account_id` or `{ brand, operator }`. |
+| `account` | [AccountRef](/docs/building/by-layer/L2/accounts-and-agents#account-references) | Yes | Account for this record — by `account_id` or `{ brand, operator }`. |
 | `vendor_cost` | number | Yes | Amount owed to the vendor for this record, in `currency` |
 | `currency` | string | Yes | ISO 4217 currency code |
 | `pricing_option_id` | string | Vendor: Yes | Pricing option from the vendor's discovery response (`get_signals`, `list_creatives`, `list_content_standards`, `list_property_lists`) or execution response (`build_creative`). The vendor uses this to verify the correct rate was applied. |
@@ -187,4 +187,4 @@ Report upon campaign completion to close out the final period.
 
 - [sync_accounts](/docs/accounts/tasks/sync_accounts) — Sync advertiser accounts with a seller before reporting
 - [Accounts Protocol](/docs/accounts/overview) — How account establishment and settlement fit together
-- [Accounts and agents](/docs/building/integration/accounts-and-agents) — Billing hierarchy and operator model
+- [Accounts and agents](/docs/building/by-layer/L2/accounts-and-agents) — Billing hierarchy and operator model
diff --git a/docs/accounts/tasks/sync_accounts.mdx b/docs/accounts/tasks/sync_accounts.mdx
@@ -95,8 +95,8 @@ asyncio.run(main())
 |-------|------|----------|-------------|
 | `brand` | object | Yes | Brand reference identifying the advertiser. Contains `domain` (house domain where brand.json is hosted) and optional `brand_id` (for multi-brand houses). See [brand-ref](/docs/brand-protocol/brand-json). |
 | `operator` | string | Yes | Domain of the entity operating on the brand's behalf (e.g. `pinnacle-media.com`). When the brand operates directly, set to the brand's domain. Verified against the brand's `authorized_operators` in brand.json. |
-| `billing` | string | Yes | Who should be invoiced: `operator`, `agent`, or `advertiser`. Check `get_adcp_capabilities` for `supported_billing` to see what the seller accepts at the capability level. The seller must either accept this billing model or reject the request. Sellers MAY additionally reject a value the seller-wide capability accepts when the calling buyer agent's commercial relationship does not permit it — e.g., a buyer agent onboarded as passthrough-only (no payments relationship — only the operator can be invoiced). The two gates use distinct error codes — `BILLING_NOT_SUPPORTED` for the seller-wide capability gate, `BILLING_NOT_PERMITTED_FOR_AGENT` for the per-buyer-agent gate — so agents can dispatch on autonomous-retry vs human-onboarding without parsing prose. See [Buyer-agent identity](/docs/building/integration/accounts-and-agents#buyer-agent-identity) and [Billing and Account Setup](/docs/building/implementation/error-handling#billing-and-account-setup). |
-| `billing_entity` | object | No | Structured business entity details for the party responsible for payment. Contains `legal_name` (required), plus optional `vat_id`, `tax_id`, `registration_number`, `address`, `contacts`, and `bank`. Bank details are write-only — included in requests but never echoed in responses. See [billing entity and invoice recipient](/docs/building/integration/accounts-and-agents#billing-entity-and-invoice-recipient). |
+| `billing` | string | Yes | Who should be invoiced: `operator`, `agent`, or `advertiser`. Check `get_adcp_capabilities` for `supported_billing` to see what the seller accepts at the capability level. The seller must either accept this billing model or reject the request. Sellers MAY additionally reject a value the seller-wide capability accepts when the calling buyer agent's commercial relationship does not permit it — e.g., a buyer agent onboarded as passthrough-only (no payments relationship — only the operator can be invoiced). The two gates use distinct error codes — `BILLING_NOT_SUPPORTED` for the seller-wide capability gate, `BILLING_NOT_PERMITTED_FOR_AGENT` for the per-buyer-agent gate — so agents can dispatch on autonomous-retry vs human-onboarding without parsing prose. See [Buyer-agent identity](/docs/building/by-layer/L2/accounts-and-agents#buyer-agent-identity) and [Billing and Account Setup](/docs/building/by-layer/L3/error-handling#billing-and-account-setup). |
+| `billing_entity` | object | No | Structured business entity details for the party responsible for payment. Contains `legal_name` (required), plus optional `vat_id`, `tax_id`, `registration_number`, `address`, `contacts`, and `bank`. Bank details are write-only — included in requests but never echoed in responses. See [billing entity and invoice recipient](/docs/building/by-layer/L2/accounts-and-agents#billing-entity-and-invoice-recipient). |
 | `payment_terms` | string | No | Payment terms for this account: `net_15`, `net_30`, `net_45`, `net_60`, `net_90`, or `prepay`. The seller must either accept these terms or reject the account — terms are never silently remapped. When omitted, the seller applies its default terms. |
 | `sandbox` | boolean | No | When true, set up a sandbox account with no real platform calls or billing. Only applicable to buyer-declared accounts (`require_operator_auth: false`). For account-id namespaces, sandbox accounts are pre-existing test accounts discovered via `list_accounts` or supplied out-of-band. |
 | `notification_configs` | array | No | Account-level webhook subscribers for events that outlive any single media buy: creative lifecycle notifications and wholesale feed change webhooks. Omit to leave existing subscribers unchanged; send `[]` to remove all subscribers; send a full array to replace. Entries are keyed by account-scoped `subscriber_id`; an existing `subscriber_id` is upserted, and persisted IDs absent from the sent array are removed. |
@@ -126,7 +126,7 @@ Returns an `accounts` array with per-account results. Individual accounts may be
 | `status` | Current state of the account (see [Account status](#account-status)). |
 | `billing` | Billing model applied. Matches the requested value. |
 | `billing_entity` | Business entity details for the invoiced party, echoed from the request. Sellers may add fields the agent omitted (e.g., `registration_number` from a credit check) but must not return data from a different entity. Bank details are omitted (write-only). |
-| `account_scope` | How the seller scoped this account: `operator` (shared across brands for this operator), `brand` (shared across operators for this brand), `operator_brand` (dedicated to this operator+brand pair), or `agent` (agent-scoped account shared across declared brand/operator pairs). See [account scope](/docs/building/integration/accounts-and-agents#account-scope). |
+| `account_scope` | How the seller scoped this account: `operator` (shared across brands for this operator), `brand` (shared across operators for this brand), `operator_brand` (dedicated to this operator+brand pair), or `agent` (agent-scoped account shared across declared brand/operator pairs). See [account scope](/docs/building/by-layer/L2/accounts-and-agents#account-scope). |
 | `setup` | Present when `status: "pending_approval"`. Contains `url` for completing credit or legal setup, `message` explaining what's needed, and optional `expires_at`. |
 | `rate_card` | Seller-assigned rate card identifier (when applicable). |
 | `payment_terms` | Payment terms agreed for this account: `net_15`, `net_30`, `net_45`, `net_60`, `net_90`, or `prepay`. When the account is active, these are the binding terms for all invoices. |
@@ -141,7 +141,7 @@ Returns an `accounts` array with per-account results. Individual accounts may be
 
 | Status | Meaning | Next step |
 |--------|---------|-----------|
-| `active` | Ready to use | Use [account reference](/docs/building/integration/accounts-and-agents#account-references) in protocol operations |
+| `active` | Ready to use | Use [account reference](/docs/building/by-layer/L2/accounts-and-agents#account-references) in protocol operations |
 | `pending_approval` | Seller reviewing | Human may need to visit `setup.url` to complete credit or legal process. Poll `list_accounts` for updates. |
 | `rejected` | Seller declined the request | Review rejection reason in `warnings`, adjust and retry, or contact seller |
 | `payment_required` | Credit limit reached or funds depleted | Add funds or increase credit limit. Route spend to other accounts. |
@@ -170,7 +170,7 @@ If the buyer did not provide `push_notification_config`, poll [`list_accounts`](
 Each per-account entry uses one of two key shapes, never both:
 
 - **Provisioning mode** — flat `brand` + `operator` + `billing` at the entry root. The seller provisions or upserts accounts. Used for buyer-declared accounts (`require_operator_auth: false`). This is the shape AdCP 3.0 shipped with. Sellers MAY echo an `account_id`, but the natural-key `AccountRef` remains valid for subsequent calls.
-- **Settings-update mode** — `account` (an [AccountRef](/docs/building/integration/accounts-and-agents#account-references)) at the entry root, with `brand`/`operator`/`billing` absent. The seller updates the account's settable state — no provisioning side effects. Used for account-id namespaces only when the seller exposes settings updates through this task; upstream-managed accounts are discovered via `list_accounts`, while seller-defined account IDs may be supplied out-of-band. Buyer-declared account sellers MAY also accept this mode for settings updates against accounts they previously provisioned.
+- **Settings-update mode** — `account` (an [AccountRef](/docs/building/by-layer/L2/accounts-and-agents#account-references)) at the entry root, with `brand`/`operator`/`billing` absent. The seller updates the account's settable state — no provisioning side effects. Used for account-id namespaces only when the seller exposes settings updates through this task; upstream-managed accounts are discovered via `list_accounts`, while seller-defined account IDs may be supplied out-of-band. Buyer-declared account sellers MAY also accept this mode for settings updates against accounts they previously provisioned.
 
 Schema enforces the exclusivity via `oneOf` — sending both shapes on the same entry is a validation error. Sellers that don't implement settings-update mode reject `account`-keyed entries with `UNSUPPORTED_PROVISIONING`; sellers that don't provision through `sync_accounts`, including account-id namespaces, reject natural-key provisioning entries with the same code.
 
@@ -520,8 +520,8 @@ asyncio.run(main())
 | Error Code | Description | Resolution |
 |------------|-------------|------------|
 | `ACCOUNT_NOT_FOUND` | Referenced account does not exist or is not accessible | Check `account_id` or re-sync |
-| `BILLING_NOT_SUPPORTED` | Seller-wide capability gate (`supported_billing` does not include the value) or per-account-relationship gate; see [Billing and Account Setup](/docs/building/implementation/error-handling#billing-and-account-setup) | Check `get_adcp_capabilities` for `supported_billing`, adjust or omit `billing`; inspect `error.details.scope` to disambiguate capability vs account scope |
-| `BILLING_NOT_PERMITTED_FOR_AGENT` | Seller-wide capability accepts the value, but the calling buyer agent's commercial relationship does not (e.g., passthrough-only — no payments relationship); see [Buyer-agent identity](/docs/building/integration/accounts-and-agents#buyer-agent-identity) | Retry with `error.details.suggested_billing` (typically `operator`) when present; when absent, surface to a human — the agent cannot extend its own commercial relationship |
+| `BILLING_NOT_SUPPORTED` | Seller-wide capability gate (`supported_billing` does not include the value) or per-account-relationship gate; see [Billing and Account Setup](/docs/building/by-layer/L3/error-handling#billing-and-account-setup) | Check `get_adcp_capabilities` for `supported_billing`, adjust or omit `billing`; inspect `error.details.scope` to disambiguate capability vs account scope |
+| `BILLING_NOT_PERMITTED_FOR_AGENT` | Seller-wide capability accepts the value, but the calling buyer agent's commercial relationship does not (e.g., passthrough-only — no payments relationship); see [Buyer-agent identity](/docs/building/by-layer/L2/accounts-and-agents#buyer-agent-identity) | Retry with `error.details.suggested_billing` (typically `operator`) when present; when absent, surface to a human — the agent cannot extend its own commercial relationship |
 | `PAYMENT_TERMS_NOT_SUPPORTED` | Seller does not accept the requested payment terms | Omit `payment_terms` to accept the seller's default, or negotiate offline |
 | `ACCOUNT_PAYMENT_REQUIRED` | Account has an outstanding balance requiring payment | Resolve outstanding balance or route to another account |
 | `ACCOUNT_SUSPENDED` | Account is suspended | Contact seller to resolve |
@@ -531,6 +531,6 @@ asyncio.run(main())
 
 - [list_accounts](/docs/accounts/tasks/list_accounts) -- Poll for status changes on pending accounts
 - [sync_governance](/docs/accounts/tasks/sync_governance) -- Sync governance agents to accounts
-- [Accounts and agents](/docs/building/integration/accounts-and-agents) -- Billing models, trust models, and authorized operators
+- [Accounts and agents](/docs/building/by-layer/L2/accounts-and-agents) -- Billing models, trust models, and authorized operators
 - [Brand protocol](/docs/brand-protocol/brand-json) -- How seller agents resolve brand identity from the `brand.domain`
 - [get_adcp_capabilities](/docs/protocol/get_adcp_capabilities) -- Discover `supported_billing` and `require_operator_auth` before syncing accounts