docs: fix broken links and align site build with main (2026-01-11) (#229)

* docs: fix markdown lint issues

* docs: fix broken link anchors and paths

* docs: native schema generation for release docs

- Fixed broken anchor links across 'checkout', 'embedded-checkout', 'fulfillment', and 'order' documentation for the 'release/2026-01-11' branch by adding explicit dictionary tables for missing schema types, allowing them to render natively within the pages rather than depending on the deprecated reference override logic.
- Added explicit HTML anchor tags to headings to ensure downstream schema references resolve correctly.

Author: wry-ry

.github/workflows/docs.yml

@@ -30,8 +30,9 @@ on:
       - "requirements-docs.txt"
       - "mkdocs.yml"
       - "main.py"
+      - "hooks.py"
       - "docs/**"
-      - "spec/**"
+      - "source/**"
 
 jobs:
   build_and_deploy:
@@ -53,58 +54,36 @@ jobs:
           git config --global user.name github-actions[bot]
           git config --global user.email 41898282+github-actions[bot]@users.noreply.github.com
 
-      - name: Fetch hooks.py and main.py from main
-        run: |
-          git fetch origin main
-          git checkout origin/main -- hooks.py main.py
-
-      - name: Install ucp-schema for runtime resolution
-        run: |
-          cargo install ucp-schema
-          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
-
       - name: Install system dependencies
         run: |
           sudo apt-get update
           sudo apt-get install -y libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev
 
-      - name: Setup Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: 3.13
-
-      - name: Restore pip cache
-        uses: actions/cache@v4
-        with:
-          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements-docs.txt') }}
-          path: ~/.cache/pip
-          restore-keys: |
-            ${{ runner.os }}-pip-
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v7
 
       - name: Install documentation dependencies
-        run: pip install -r requirements-docs.txt
+        run: uv sync
 
       - name: Lint YAML files
-        run: yamllint -c .github/linters/.yamllint.yml .
-
-      - name: Install uv
-        run: |
-          curl -LsSf https://astral.sh/uv/install.sh | sh
-          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+        run: uv run yamllint -c .github/linters/.yamllint.yml .
 
-      - name: Check for changed files in spec
-        id: spec_files_changed
+      - name: Check for changed files in source
+        id: source_files_changed
         uses: tj-actions/changed-files@v46
         with:
-          files: spec/**
+          files: source/**
 
-      - name: Check Python SDK Models Consistency
-        if: steps.spec_files_changed.outputs.any_changed == 'true'
+      - name: Install ucp-schema for runtime resolution
         run: |
-          chmod +x scripts/ci_check_models.sh
-          scripts/ci_check_models.sh
+          cargo install ucp-schema
+          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
 
-      - name: Create specs folders for JSON publishing
+      - name: Lint source schemas
+        if: steps.source_files_changed.outputs.any_changed == 'true'
+        run: ucp-schema lint source/
+
+      - name: Create folders for JSON publishing
         run: |
           mkdir -p site/schemas
           mkdir -p site/services
@@ -117,52 +96,68 @@ jobs:
         run: |
           # Fetch the Pages URL. Fails safely if not enabled.
           PAGES_URL=$(gh api "repos/${{ github.repository }}/pages" --jq '.html_url' 2>/dev/null || true)
-          
+
           if [ -z "$PAGES_URL" ]; then
             echo "Pages URL not detected. Falling back to default structure."
             PAGES_URL="https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}"
           fi
-          
+
           # Ensure trailing slash
           if [[ "$PAGES_URL" != */ ]]; then
             PAGES_URL="${PAGES_URL}/"
           fi
-          
+
           echo "Set SITE_URL to $PAGES_URL"
           echo "SITE_URL=$PAGES_URL" >> $GITHUB_ENV
 
-      - name: Build Documentation (PR Check)
-        if: github.event_name == 'pull_request'
-        run: mkdocs build --strict
+      - name: Build and Verify Documentation Site (Main/PR)
+        if: github.ref == 'refs/heads/main' || github.event.pull_request.base.ref == 'main'
+        run: |
+          # Create a full local preview (including mike logic) for validation
+          bash scripts/build_local.sh --main-only
+          uv run python scripts/check_links.py local_preview
+
+      - name: Build and Verify Specification Docs (Release Branches)
+        if: startsWith(github.ref, 'refs/heads/release/') || startsWith(github.event.pull_request.base.ref, 'release/')
+        run: |
+          export DOCS_MODE=spec
+          uv run mkdocs build --strict
+          uv run python scripts/check_links.py site
 
       - name: Deploy development version from main branch
         if: github.event_name == 'push' && github.ref == 'refs/heads/main'
         run: |
-          mike deploy --push draft
+          # 1. Deploy Specification Site using mike (DOCS_MODE=spec)
+          export DOCS_MODE=spec
+          uv run mike deploy --push draft
+
+          # 2. Build Root Site (DOCS_MODE=root)
+          export DOCS_MODE=root
+          uv run mkdocs build --strict
+
+          # 3. Deploy Root Site to gh-pages root
+          # Fetch and checkout gh-pages
+          git fetch origin gh-pages
+          git checkout gh-pages
+
+          # Copy build artifacts to root
+          cp -r site/* .
+          rm -rf site
+
+          # Commit and push
+          git add .
+          git commit -m "Deploy root site from main" --allow-empty
+          git push origin gh-pages
 
       - name: Deploy release version
         if: startsWith(github.ref, 'refs/heads/release/')
         run: |
-          # Extract the date (e.g., release/2026-01-11 -> 2026-01-11)
           export DOCS_MODE=spec
+          # Extract the date (e.g., release/2026-01-11 -> 2026-01-11)
           VERSION_NAME=${GITHUB_REF#refs/heads/release/}
 
-          # Fetch all release branches to determine if this is the latest
-          git fetch origin "+refs/heads/release/*:refs/remotes/origin/release/*"
-          
-          # Find the highest version number among all release branches
-          LATEST_VERSION=$(git branch -r --list "origin/release/*" | sed 's|origin/release/||' | sort -V | tail -n 1 | tr -d ' ')
-
-          echo "Deploying version: $VERSION_NAME"
-          echo "Latest detected version: $LATEST_VERSION"
-
-          if [ "$VERSION_NAME" = "$LATEST_VERSION" ]; then
-            echo "This is the latest version. Updating 'latest' alias."
-            mike deploy --push --update-aliases "$VERSION_NAME" latest
-          else
-            echo "This is NOT the latest version. Deploying without updating 'latest' alias."
-            mike deploy --push "$VERSION_NAME"
-          fi
+          # Deploy this version, tag it as 'latest', and set it as the default site root
+          uv run mike deploy --push --update-aliases $VERSION_NAME latest
 
       - name: Create GitHub Release and Tag
         if: startsWith(github.ref, 'refs/heads/release/')

.linkignore

@@ -0,0 +1,2 @@
+# Ignore ucp.dev dummy links
+https://ucp\.dev/specification/reference\?v=2026-01-11

docs/documentation/core-concepts.md

@@ -19,21 +19,21 @@
 The Universal Commerce Protocol (UCP) is an open standard designed to facilitate
 communication and interoperability between diverse commerce entities. In a
 fragmented landscape where consumer surfaces/platforms, businesses, payment
-providers, and identity providers operate on different systems, UCP provides
-a standardized common language and functional primitives.
+providers, and identity providers operate on different systems, UCP provides a
+standardized common language and functional primitives.
 
-This document provides the detailed technical specification for UCP.
-For a complete definition of all data models and schemas, see the
+This document provides the detailed technical specification for UCP. For a
+complete definition of all data models and schemas, see the
 [Schema Reference](../specification/reference.md).
 
 Its primary goal is to enable:
 
-*   **Consumer Surfaces/Platforms:** To discover business capabilities and
-    facilitate purchases.
-*   **Businesses:** To expose their inventory and retail logic in a standard
-    way without building custom integrations for every platform.
-*   **Payment & Credential Providers:** To securely exchange tokens and
-    credentials to facilitate transactions.
+- **Consumer Surfaces/Platforms:** To discover business capabilities and
+  facilitate purchases.
+- **Businesses:** To expose their inventory and retail logic in a standard way
+  without building custom integrations for every platform.
+- **Payment & Credential Providers:** To securely exchange tokens and
+  credentials to facilitate transactions.
 
 ## High level architecture
 
@@ -46,15 +46,15 @@ Its primary goal is to enable:
 
 ## Key Goals of UCP
 
-*   **Interoperability:** Bridge the gap between consumer surfaces, businesses,
-    and payment ecosystems.
-*   **Discovery:** Allow consumer surfaces to dynamically discover what
-    businesses support (e.g., "Do they support guest checkout?", "Do they have
-    loyalty programs?").
-*   **Security:** Facilitate secure, standards-based (OAuth 2.0, PCI-DSS
-    compliant patterns) exchanges of sensitive user and payment data.
-*   **Agentic Commerce:** Enable AI agents to act on behalf of users to complete
-    complex tasks like "Find a headset under $100 and buy it."
+- **Interoperability:** Bridge the gap between consumer surfaces, businesses,
+  and payment ecosystems.
+- **Discovery:** Allow consumer surfaces to dynamically discover what businesses
+  support (e.g., "Do they support guest checkout?", "Do they have loyalty
+  programs?").
+- **Security:** Facilitate secure, standards-based (OAuth 2.0, PCI-DSS compliant
+  patterns) exchanges of sensitive user and payment data.
+- **Agentic Commerce:** Enable AI agents to act on behalf of users to complete
+  complex tasks like "Find a headset under $100 and buy it."
 
 ## Roles & Participants
 
@@ -67,58 +67,55 @@ The platform is the consumer-facing surface (such as an AI agent, mobile app, or
 social media site) acting on behalf of the User. It orchestrates the commerce
 journey by discovering businesses and facilitating user intent.
 
-*   **Responsibilities:** Discovering businesses capabilities via profiles,
-    initiating checkout sessions, and presenting the UI or conversational
-    interface to the user.
-*   **Examples:** AI Shopping Assistants, Super Apps, Search Engines.
+- **Responsibilities:** Discovering businesses capabilities via profiles,
+  initiating checkout sessions, and presenting the UI or conversational
+  interface to the user.
+- **Examples:** AI Shopping Assistants, Super Apps, Search Engines.
 
 ### Business
 
 The entity selling goods or services. In the UCP model, businesses act as the
 **Merchant of Record (MoR)**, retaining financial liability and ownership of the
 order.
 
-*   **Responsibilities:** Exposing commerce capabilities (inventory, pricing,
-    tax calculation), fulfilling orders, and processing payments via their
-    chosen PSP.
-*   **Examples:** Retailers, Airlines, Hotel Chains, Service Providers.
+- **Responsibilities:** Exposing commerce capabilities (inventory, pricing, tax
+  calculation), fulfilling orders, and processing payments via their chosen PSP.
+- **Examples:** Retailers, Airlines, Hotel Chains, Service Providers.
 
 ### Credential Provider (CP)
 
 A trusted entity responsible for securely managing and sharing sensitive user
 data, particularly payment instruments and shipping addresses.
 
-*   **Responsibilities:** Authenticating the user, issuing payment tokens (to
-    keep raw card data off the platform), and holding PII securely to minimize
-    compliance scope for other parties.
-*   **Examples:** Digital Wallets (e.g., Google Wallet, Apple Pay), Identity
-    Providers.
+- **Responsibilities:** Authenticating the user, issuing payment tokens (to keep
+  raw card data off the platform), and holding PII securely to minimize
+  compliance scope for other parties.
+- **Examples:** Digital Wallets (e.g., Google Wallet, Apple Pay), Identity
+  Providers.
 
 ### Payment Service Provider (PSP)
 
 The financial infrastructure provider that processes payments on behalf of
 businesses.
 
-*   **Responsibilities:** Authorizing and capturing transactions, handling
-    settlements, and communicating with card networks. The PSP often interacts
-    directly with tokens provided by the Credential Provider.
-*   **Examples:** Stripe, Adyen, PayPal, Braintree, Chase Paymentech.
+- **Responsibilities:** Authorizing and capturing transactions, handling
+  settlements, and communicating with card networks. The PSP often interacts
+  directly with tokens provided by the Credential Provider.
+- **Examples:** Stripe, Adyen, PayPal, Braintree, Chase Paymentech.
 
 ## Core Concepts Summary
 
 UCP revolves around three fundamental constructs that define how entities
 interact.
 
-*   **Capabilities:** Standalone core features that a business supports. These
-    are the "verbs" of the protocol.
-    *   *Examples:* Checkout, Identity Linking, Order.
-*   **Extensions:** Optional capabilities that augment another capability
-    via the `extends` field. Extensions appear in `ucp.capabilities[]`
-    alongside core capabilities.
-    *   *Examples:* Discounts (extends Checkout), AP2 Mandates (extends
-        Checkout).
-*   **Services:** The lower-level communication layers used to exchange data.
-    UCP is transport-agnostic but defines specific bindings for
-    interoperability.
-    *   *Examples:* REST API (primary), MCP (Model Context Protocol), A2A
-        (Agent2Agent).
+- **Capabilities:** Standalone core features that a business supports. These are
+  the "verbs" of the protocol.
+    - _Examples:_ Checkout, Identity Linking, Order.
+- **Extensions:** Optional capabilities that augment another capability via the
+  `extends` field. Extensions appear in `ucp.capabilities[]` alongside core
+  capabilities.
+    - _Examples:_ Discounts (extends Checkout), AP2 Mandates (extends Checkout).
+- **Services:** The lower-level communication layers used to exchange data. UCP
+  is transport-agnostic but defines specific bindings for interoperability.
+    - _Examples:_ REST API (primary), MCP (Model Context Protocol), A2A
+      (Agent2Agent).

docs/documentation/roadmap.md

@@ -36,17 +36,17 @@ tackle key user journeys such as multi-item checkout, loyalty, and lifecycle
 management, while ensuring the business's brand and logic remain central to all
 shopping experiences. Key upcoming initiatives include:
 
-*   **Product discovery and post-order management:** By facilitating the entire
-    journey, we help businesses maximize lifetime and average order value rather
-    than just processing a single item for checkout.
-*   **Cart and basket building:** Support for multi-item checkout from a
-    business, complex basket rules (e.g., promotions, tax, shipping), and varied
-    fulfillment logic that reflects how people actually shop.
-*   **Loyalty & Member benefits:** Capabilities to enable loyalty and member
-    benefits to help users find the best value and businesses achieve a deeper
-    connection with their consumers through account linking.
-*   **Native cross-sell and upsell modules:** Capabilities for businesses to
-    provide personalized recommendations and upsells based on user context.
+- **Product discovery and post-order management:** By facilitating the entire
+  journey, we help businesses maximize lifetime and average order value rather
+  than just processing a single item for checkout.
+- **Cart and basket building:** Support for multi-item checkout from a business,
+  complex basket rules (e.g., promotions, tax, shipping), and varied fulfillment
+  logic that reflects how people actually shop.
+- **Loyalty & Member benefits:** Capabilities to enable loyalty and member
+  benefits to help users find the best value and businesses achieve a deeper
+  connection with their consumers through account linking.
+- **Native cross-sell and upsell modules:** Capabilities for businesses to
+  provide personalized recommendations and upsells based on user context.
 
 ### Support for global markets
 
@@ -63,4 +63,5 @@ developers, and payment providers to join us in refining these specifications.
 Your feedback on our early builds helps us shape the standards that will power
 the next generation of global commerce.
 
-[Become a UCP contributor](https://github.com/Universal-Commerce-Protocol/ucp?tab=contributing-ov-file){ target="_blank" }
+[Become a UCP contributor](https://github.com/Universal-Commerce-Protocol/ucp?tab=contributing-ov-file){
+target="\_blank" }