refactor: organize specification hierarchy by domain verticals (Shopping, Payment, Common)

docs/documentation/core-concepts.md

@@ -141,7 +141,7 @@ each declares the date `D` of the UCP release it ships in. Third-party
 extensions publish versions on their own cadence.
 
 The following are examples of capabilities defined in UCP — see the
-[Specification](../specification/overview.md) for the authoritative and
+[Specification](../specification/overview/index.md) for the authoritative and
 up-to-date list.
 
 | Capability | Description |
@@ -165,10 +165,10 @@ core capabilities.
 {
   "dev.ucp.shopping.fulfillment": [
     {
-      "version": "2026-04-08",
+      "version": "{{ ucp_version }}",
       "extends": "dev.ucp.shopping.checkout",
-      "spec": "https://ucp.dev/2026-04-08/specification/fulfillment",
-      "schema": "https://ucp.dev/2026-04-08/schemas/shopping/fulfillment.json"
+      "spec": "https://ucp.dev/{{ ucp_version }}/specification/fulfillment",
+      "schema": "https://ucp.dev/{{ ucp_version }}/schemas/shopping/fulfillment.json"
     }
   ]
 }
@@ -179,7 +179,7 @@ intersection is automatically pruned. This ensures extension coherence —
 you never activate a discount extension without the checkout it extends.
 
 The following are examples of extensions defined in UCP — see the
-[Specification](../specification/overview.md) for the authoritative and
+[Specification](../specification/overview/index.md) for the authoritative and
 up-to-date list.
 
 | Extension | Extends | Description |
@@ -270,35 +270,35 @@ authentication are resolved together.
 ```json
 {
   "ucp": {
-    "version": "2026-04-08",
+    "version": "{{ ucp_version }}",
     "services": {
       "dev.ucp.shopping": [
         {
-          "version": "2026-04-08",
-          "spec": "https://ucp.dev/2026-04-08/specification/overview",
+          "version": "{{ ucp_version }}",
+          "spec": "https://ucp.dev/{{ ucp_version }}/specification/overview/",
           "transport": "rest",
-          "schema": "https://ucp.dev/2026-04-08/services/shopping/rest.openapi.json",
+          "schema": "https://ucp.dev/{{ ucp_version }}/services/shopping/rest.openapi.json",
           "endpoint": "https://business.example.com/ucp/v1"
         }
       ]
     },
     "capabilities": {
       "dev.ucp.shopping.checkout": [{
-        "version": "2026-04-08",
-        "spec": "https://ucp.dev/2026-04-08/specification/checkout",
-        "schema": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json"
+        "version": "{{ ucp_version }}",
+        "spec": "https://ucp.dev/{{ ucp_version }}/specification/shopping/checkout",
+        "schema": "https://ucp.dev/{{ ucp_version }}/schemas/shopping/checkout.json"
       }],
       "dev.ucp.shopping.fulfillment": [{
-        "version": "2026-04-08",
-        "spec": "https://ucp.dev/2026-04-08/specification/fulfillment",
-        "schema": "https://ucp.dev/2026-04-08/schemas/shopping/fulfillment.json",
+        "version": "{{ ucp_version }}",
+        "spec": "https://ucp.dev/{{ ucp_version }}/specification/fulfillment",
+        "schema": "https://ucp.dev/{{ ucp_version }}/schemas/shopping/fulfillment.json",
         "extends": "dev.ucp.shopping.checkout"
       }]
     },
     "payment_handlers": {
       "com.example.processor_tokenizer": [{
         "id": "processor_tokenizer",
-        "version": "2026-04-08",
+        "version": "{{ ucp_version }}",
         "spec": "https://example.com/specs/payments/processor_tokenizer",
         "schema": "https://example.com/specs/payments/merchant_tokenizer.json"
       }]
@@ -335,7 +335,7 @@ remains the client's decision.
 Platforms **MUST** validate this binding for declared `schema` URLs and **MUST**
 reject entities that fail it. Identifiers carry no fetched URL, and the `spec`
 (documentation) URL is not authority-bound (any `https` origin). See
-[Authority Binding](../specification/overview.md#authority-binding) for the
+[Authority Binding](../specification/overview/index.md#authority-binding) for the
 normative algorithm.
 
 The `dev.ucp.*` namespace is reserved exclusively for capabilities governed by
@@ -453,7 +453,7 @@ Every UCP-defined service, capability, and extension in release `D` declares
 version `D`. Third-party extensions and payment handlers are versioned by their
 authors, independently of UCP releases.
 
-See [Protocol Version](../specification/overview.md#protocol-version) for version
-discovery, [Component Versioning and Release Snapshots](../specification/overview.md#component-versioning-and-release-snapshots)
+See [Protocol Version](../specification/overview/index.md#protocol-version) for version
+discovery, [Component Versioning and Release Snapshots](../specification/overview/index.md#component-versioning-and-release-snapshots)
 for the normative release contract, and [Versioning](../versioning.md) for the
 release-branch and backport process.

docs/documentation/schema-authoring.md

@@ -113,7 +113,7 @@ Define transport bindings that appear in `ucp.services{}` registries. Each trans
   that service `version` repeats on each entry, and transport bindings have no
   separate version. The referenced OpenAPI/OpenRPC artifact carries its own
   `info.version` as artifact metadata, not a negotiated version. See
-  [Component Versioning and Release Snapshots](../specification/overview.md#component-versioning-and-release-snapshots)
+  [Component Versioning and Release Snapshots](../specification/overview/index.md#component-versioning-and-release-snapshots)
 - **Variants**: `platform_schema`, `business_schema`
 - **Transport requirements** (additional beyond the common base):
     - Platform profile (`platform_schema`): REST/MCP/Embedded require `schema` (OpenAPI/OpenRPC URL). A2A has no additional requirements.
@@ -130,7 +130,7 @@ Define payment handler configurations in `ucp.payment_handlers{}` registries.
 
 Examples: `com.google.pay`, `dev.shopify.shop_pay`, `dev.ucp.processor_tokenizer`
 
-**→ See [Payment Handler Guide](../specification/payment-handler-guide.md)** for detailed
+**→ See [Payment Handler Guide](../specification/payment/guide.md)** for detailed
 guidance on handler structure, config/instrument/credential schemas, and the full
 specification template.
 
@@ -209,7 +209,7 @@ The member name `ucp` is reserved at every structured UCP object scope — an
 object whose members are schema-defined fields — for the protocol namespace.
 The top-level envelope is its root manifestation. Dictionary containers are
 excluded because their keys are data rather than fields. See
-[The `ucp` Protocol Namespace](../specification/overview.md#the-ucp-protocol-namespace)
+[The `ucp` Protocol Namespace](../specification/overview/index.md#the-ucp-protocol-namespace)
 for the normative rules. For schema authors this means:
 
 - **Never mint a structured domain field named `ucp`.** Schema authors
@@ -374,7 +374,7 @@ does not replace negotiation: capabilities and extensions are still selected by
 exact-version intersection.
 
 Profile selection, including profiles for older supported releases, is defined
-in [Protocol Version](../specification/overview.md#protocol-version).
+in [Protocol Version](../specification/overview/index.md#protocol-version).
 
 ### Third-Party Extensions and Payment Handlers
 
@@ -523,7 +523,7 @@ object fields:
 ## The `request_constraints` Protocol Member
 
 Normative processing, scope, lifecycle, and invalid-member behavior are defined
-in [Request Constraints](../specification/overview.md#request-constraints).
+in [Request Constraints](../specification/overview/index.md#request-constraints).
 This section covers only the schema-authoring boundary.
 
 ### Local structure
@@ -583,7 +583,7 @@ admits that container through its optional reference to
 
 Every Action type is declared by an extension and becomes available only when
 that extension is negotiated, as defined in
-[Actions](../specification/overview.md#actions). Before advertising support,
+[Actions](../specification/overview/index.md#actions). Before advertising support,
 both the Business and the Platform should assess the extension's complete
 Action contract. Negotiation is pre-runtime agreement on that contract's
 semantics and support; it does not pre-approve every future `config` value or
@@ -963,7 +963,7 @@ Manual invocation:
 
 ```bash
 python3 scripts/validate_examples.py --schema-base source/schemas/
-python3 scripts/validate_examples.py --schema-base source/schemas/ --file docs/specification/checkout-rest.md docs/specification/cart.md
+python3 scripts/validate_examples.py --schema-base source/schemas/ --file docs/specification/shopping/checkout/rest.md docs/specification/shopping/cart/index.md
 python3 scripts/validate_examples.py --schema-base source/schemas/ --audit
 ```
 

docs/index.md

@@ -312,7 +312,7 @@ image: assets/banner.png
             <div class="pane-text">
               <h3>Checkout</h3>
               <p>Support complex cart logic, dynamic pricing, tax calculations, and more across millions of businesses through unified checkout sessions.</p>
-              <a href="/latest/specification/checkout/" class="learn-more-btn">Get Started</a>
+              <a href="latest/specification/shopping/checkout/" class="learn-more-btn">Get Started</a>
             </div>
             <div class="pane-visuals">
               <div class="image-container">
@@ -393,7 +393,7 @@ image: assets/banner.png
             <div class="pane-text">
               <h3>Identity Linking</h3>
               <p>OAuth 2.0 standard enables agents to maintain secure, authorized relationships without sharing credentials.</p>
-              <a href="latest/specification/identity-linking/" class="learn-more-btn">Get Started</a>
+              <a href="latest/specification/common/identity-linking/" class="learn-more-btn">Get Started</a>
             </div>
             <div class="pane-visuals">
               <div class="image-container">
@@ -433,7 +433,7 @@ image: assets/banner.png
             <div class="pane-text">
               <h3>Order</h3>
               <p>From purchase confirmation to delivery. Real-time webhooks power status updates, shipment tracking, and return processing across every channel.</p>
-              <a href="latest/specification/order/" class="learn-more-btn">Get Started</a>
+              <a href="latest/specification/shopping/order/" class="learn-more-btn">Get Started</a>
             </div>
             <div class="pane-visuals">
               <div class="image-container">
@@ -609,7 +609,7 @@ image: assets/banner.png
       <p>
         Integrate and negotiate directly with a seller's checkout API to power native UI and workflows for your platform.
       </p>
-      <a href="latest/specification/checkout-rest/" class="promo-button">Get Started</a>
+      <a href="latest/specification/shopping/checkout/rest/" class="promo-button">Get Started</a>
     </div>
 
     <div class="two-column-promo-item">
@@ -620,7 +620,7 @@ image: assets/banner.png
       <p>
         Embed and render business checkout UI to support complex checkout flows, with advanced capabilities like bidirectional communication, and payment and shipping address delegation.
       </p>
-      <a href="latest/specification/embedded-checkout/" class="promo-button">See how it works</a>
+      <a href="latest/specification/shopping/checkout/embedded/" class="promo-button">See how it works</a>
     </div>
 
   </div>
@@ -1109,7 +1109,7 @@ image: assets/banner.png
         <div class="get-started-container-step-icon-wrapper">
           <img src="assets/Icon=Experiment.svg" alt="Experiment" class="get-started-container-step-icon">
         </div>
-        <h3><a href="latest/specification/playground/" target="_blank">Experiment</a></h3>
+        <h3><a href="latest/specification/shopping/playground/" target="_blank">Experiment</a></h3>
         <p>Experiment with the protocol and its different agent roles</p>
       </div>
       <div class="get-started-container-step">

docs/specification/ap2-mandates.md

@@ -75,7 +75,7 @@ Businesses declare support by adding `dev.ucp.shopping.ap2_mandate` to their
       "dev.ucp.shopping.checkout": [
         {
           "version": "{{ ucp_version }}",
-          "spec": "https://ucp.dev/{{ ucp_version }}/specification/checkout",
+          "spec": "https://ucp.dev/{{ ucp_version }}/specification/shopping/checkout",
           "schema": "https://ucp.dev/{{ ucp_version }}/schemas/shopping/checkout.json"
         }
       ],
@@ -137,7 +137,7 @@ This extension uses the cryptographic primitives defined in the
 * **Canonicalization:** JCS ([RFC 8785](https://datatracker.ietf.org/doc/html/rfc8785))
 * **Key Format:** JWK ([RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517))
 * **Key Discovery:** `keys[]` in `/.well-known/ucp` (see
-  [Key Discovery](overview.md#key-discovery))
+  [Key Discovery](overview/index.md#key-discovery))
 
 See [Message Signatures](signatures.md) for key format and rotation.
 

docs/specification/buyer-consent.md

@@ -330,8 +330,8 @@ Some consent states depend on additional buyer or checkout data. For example,
 SMS marketing consent requires a buyer phone number. When the
 platform confirms a consent value whose required dependency is missing,
 businesses surface the gap through the standard [Checkout Status
-Lifecycle](checkout.md#checkout-status-lifecycle) and [Error
-Handling](checkout.md#error-handling) mechanisms.
+Lifecycle](shopping/checkout/index.md#checkout-status-lifecycle) and [Error
+Handling](shopping/checkout/index.md#error-handling) mechanisms.
 
 On `create_cart`, `update_cart`, `create_checkout`, and `update_checkout`,
 businesses SHOULD surface missing dependencies as `warning` messages so the
@@ -354,7 +354,7 @@ consent decisions remain valid; the warning is informational.
 On `complete_checkout`, businesses MUST NOT transition the checkout to
 `completed` while a confirmed consent decision has unmet data dependencies.
 Missing dependencies MUST be surfaced via the standard [Error
-Handling](checkout.md#error-handling) flow.
+Handling](shopping/checkout/index.md#error-handling) flow.
 
 ## Normative requirements
 

docs/specification/identity-linking.md → docs/specification/common/identity-linking/index.md

@@ -17,7 +17,7 @@
 # Identity Linking Capability
 
 * **Capability Name:** `dev.ucp.common.identity_linking`
-* **Schema:** `https://ucp.dev/schemas/common/identity_linking.json`
+* **Schema:** `https://ucp.dev/{{ ucp_version }}/schemas/common/identity_linking.json`
 
 ## Overview
 
@@ -90,8 +90,8 @@ business **MAY** populate it from stored state on the response (for example,
 
 Identity linking provides the authenticated user context for these values.
 Subject to the scopes that gate the operation, a business **MAY** return the
-user's loyalty membership in `loyalty` (see [Loyalty](loyalty.md)), saved
-payment instruments in `payment.instruments[]` (see [Checkout](checkout.md)), or
+user's loyalty membership in `loyalty` (see [Loyalty](../../loyalty.md)), saved
+payment instruments in `payment.instruments[]` (see [Checkout](../../shopping/checkout/index.md)), or
 buyer profile data in `buyer`.
 
 Businesses **MUST NOT** return stored user-specific state unless the request is
@@ -412,7 +412,7 @@ namespace; its value is an array of mechanism entries.
 
 A provider key is a reverse-domain **identifier**, not a schema-bearing entity:
 it declares no `schema` URL, so the
-[Authority Binding](overview.md#authority-binding) (which binds an entity's
+[Authority Binding](../../overview/index.md#authority-binding) (which binds an entity's
 `schema` URL to its namespace authority) does not apply here. A provider's trust
 anchor is its `auth_url`, governed by the discovery rules below; binding
 `auth_url` to the provider's namespace authority is a possible future hardening,
@@ -481,8 +481,8 @@ direct OAuth flows (always available via discovery):
     "capabilities": {
       "dev.ucp.common.identity_linking": [{
         "version": "{{ ucp_version }}",
-        "spec": "https://ucp.dev/specification/identity-linking",
-        "schema": "https://ucp.dev/schemas/common/identity_linking.json",
+        "spec": "https://ucp.dev/{{ ucp_version }}/specification/common/identity-linking/",
+        "schema": "https://ucp.dev/{{ ucp_version }}/schemas/common/identity_linking.json",
         "config": {
           "providers": {
             "app.example.login": [
@@ -1123,8 +1123,8 @@ operations gated:
     "capabilities": {
       "dev.ucp.common.identity_linking": [{
         "version": "{{ ucp_version }}",
-        "spec": "https://ucp.dev/specification/identity-linking",
-        "schema": "https://ucp.dev/schemas/common/identity_linking.json",
+        "spec": "https://ucp.dev/{{ ucp_version }}/specification/common/identity-linking/",
+        "schema": "https://ucp.dev/{{ ucp_version }}/schemas/common/identity_linking.json",
         "config": {
           "scopes": {
             "dev.ucp.shopping.order:read":    {},
@@ -1161,8 +1161,8 @@ No guest checkout — every transaction requires an authenticated user:
     "capabilities": {
       "dev.ucp.common.identity_linking": [{
         "version": "{{ ucp_version }}",
-        "spec": "https://ucp.dev/specification/identity-linking",
-        "schema": "https://ucp.dev/schemas/common/identity_linking.json",
+        "spec": "https://ucp.dev/{{ ucp_version }}/specification/common/identity-linking/",
+        "schema": "https://ucp.dev/{{ ucp_version }}/schemas/common/identity_linking.json",
         "config": {
           "scopes": {
             "dev.ucp.shopping.checkout:manage":  {},

docs/specification/discount.md

@@ -194,7 +194,7 @@ segment, or promotional rules:
 ## Eligibility Claims
 
 Eligibility claims are buyer claims about eligible benefits (see
-[Context](checkout.md#context)) such as loyalty membership, payment instrument
+[Context](shopping/checkout/index.md#context)) such as loyalty membership, payment instrument
 perks, and similar. When the discount extension is active, Businesses that
 choose to accept eligibility claims **MUST** surface their effect on pricing
 as provisional discounts in the `applied` array. Platforms **MUST** display
@@ -203,7 +203,7 @@ provisional discounts to the buyer.
 ### Discount Behavior
 
 Platforms send buyer claims via `context.eligibility` on cart or checkout
-requests (see [Context](checkout.md#context)). When a Business recognizes a
+requests (see [Context](shopping/checkout/index.md#context)). When a Business recognizes a
 claim and it affects pricing, it **MUST** surface a corresponding provisional
 discount in the `discounts.applied` array. This gives the Platform structured
 attribution to display to the buyer.
@@ -226,12 +226,12 @@ Discounts from accepted but unverified claims carry `provisional: true`.
 Provisional discounts remain until the claim is verified, rescinded, or
 replaced during the session. At checkout completion, all remaining provisional
 claims **MUST** be resolved (see
-[Eligibility Verification at Completion](checkout.md#eligibility-verification-at-completion)).
+[Eligibility Verification at Completion](shopping/checkout/index.md#eligibility-verification-at-completion)).
 
 ### Example: Provisional Discount with Attribution
 
 Using the same claim-resolution pattern described in
-[Eligibility Verification at Completion](checkout.md#eligibility-verification-at-completion),
+[Eligibility Verification at Completion](shopping/checkout/index.md#eligibility-verification-at-completion),
 the discount extension provides structured attribution. The Platform claims a
 store card benefit; the Business surfaces the provisional discount with full
 stacking and allocation details:

docs/specification/embedded-protocol.md

@@ -33,8 +33,8 @@ Capability-specific details — discovery, URL parameters, delegation contracts,
 message payloads, and schema definitions — are defined in each capability's EP
 binding specification:
 
-- [Checkout Capability — EP Binding](embedded-checkout.md)
-- [Cart Capability — EP Binding](embedded-cart.md)
+- [Checkout Capability — EP Binding](shopping/checkout/embedded.md)
+- [Cart Capability — EP Binding](shopping/cart/embedded.md)
 
 ## Terminology & Actors
 
@@ -128,7 +128,7 @@ Transport errors are protocol-level failures that prevent request processing.
 These are returned as JSON-RPC `error` using standard JSON-RPC error codes and
 indicate the message itself is invalid or could not be processed — not that
 executed business logic produced an error outcome. See the
-[Core Specification](overview.md#error-codes) for the complete error code
+[Core Specification](overview/index.md#error-codes) for the complete error code
 registry.
 
 For example, if a request cannot be processed (unknown method, malformed