chore(ci): update workflow path triggers and improve docs build

.cspell.json

@@ -22,7 +22,8 @@
     "(\"x\"|\"y\")\\s*:\\s*\"[A-Za-z0-9_-]+\"",
     "sig1=:[A-Za-z0-9+/=_.]+:",
     "eyJ[A-Za-z0-9_-]+\\.\\.?[A-Za-z0-9_-]*",
-    "M[A-Z][A-Za-z0-9]{3,}\\.\\.\\."
+    "M[A-Z][A-Za-z0-9]{3,}\\.\\.\\.",
+    "(\"cursor\"|cursor)\\s*:\\s*(\"[^\"]*\"|'[^']*')"
   ],
   "dictionaryDefinitions": [
     {

.cspell/custom-words.txt

@@ -36,18 +36,23 @@ Shopee
 Splitit
 Streamable
 Stripe
+Talla
 Target
 UCP
 Ulta
 Visa
+Variante
 Wayfair
 WORKTREE
 Worldpay
+Zapatillas
 Zalando
 adyen
 agentic
+amortiguación
 atok
 backorder
+barcodes
 checkout
 credentialless
 credentialization
@@ -59,35 +64,47 @@ fontawesome
 fpan
 fulfillable
 gpay
+gtin
 ingestions
 inlinehilite
 lifecycles
+ligeras
 linenums
+linkignore
 llms
 llmstxt
 mastercard
+midsole
 mkdocs
 mtok
 openapi
 openrpc
 paypal
 permissionless
 podman
+preorder
 preorders
 proto
 protobuf
 pymdownx
+reactiva
 renderable
 repudiable
 schemas
 sdjwt
 shopify
 streamable
 superfences
+talla
+tracción
 upsell
 upsells
+variante
 vulnz
 worktree
 yaml
+zapatillas
 yml
+EDITMSG
+jwks
 keyid

.github/CODEOWNERS

@@ -1,35 +1,35 @@
 # Universal Commerce Protocol (UCP) Codeowners
 
 # Default for all files.
-* @Universal-Commerce-Protocol/maintainers
+* @Universal-Commerce-Protocol/maintainers @Universal-Commerce-Protocol/tech-council @Universal-Commerce-Protocol/governance-council
 
 # Infrastructure, Tooling & Configuration
-/.github/                 @Universal-Commerce-Protocol/devops-maintainers
-/scripts/                 @Universal-Commerce-Protocol/devops-maintainers
-/generated/               @Universal-Commerce-Protocol/devops-maintainers
-/hooks.py                 @Universal-Commerce-Protocol/devops-maintainers
-/main.py                  @Universal-Commerce-Protocol/devops-maintainers
-/generate_ts_schema_types.js @Universal-Commerce-Protocol/devops-maintainers
-/.cspell/                 @Universal-Commerce-Protocol/devops-maintainers
-/.cspell.json             @Universal-Commerce-Protocol/devops-maintainers
-/.pre-commit-config.yaml  @Universal-Commerce-Protocol/devops-maintainers
-/.prettierignore          @Universal-Commerce-Protocol/devops-maintainers
-/.prettierrc              @Universal-Commerce-Protocol/devops-maintainers
-/.stylelintrc.json        @Universal-Commerce-Protocol/devops-maintainers
-/biome.json               @Universal-Commerce-Protocol/devops-maintainers
-/mkdocs.yml               @Universal-Commerce-Protocol/devops-maintainers
-/.gitignore               @Universal-Commerce-Protocol/devops-maintainers
-/pyproject.toml           @Universal-Commerce-Protocol/devops-maintainers
-/uv.lock                  @Universal-Commerce-Protocol/devops-maintainers
-/package.json             @Universal-Commerce-Protocol/devops-maintainers
-/package-lock.json        @Universal-Commerce-Protocol/devops-maintainers
+/.github/                 @Universal-Commerce-Protocol/devops-maintainers @Universal-Commerce-Protocol/maintainers @Universal-Commerce-Protocol/tech-council @Universal-Commerce-Protocol/governance-council
+/scripts/                 @Universal-Commerce-Protocol/devops-maintainers @Universal-Commerce-Protocol/maintainers @Universal-Commerce-Protocol/tech-council @Universal-Commerce-Protocol/governance-council
+/generated/               @Universal-Commerce-Protocol/devops-maintainers @Universal-Commerce-Protocol/maintainers @Universal-Commerce-Protocol/tech-council @Universal-Commerce-Protocol/governance-council
+/hooks.py                 @Universal-Commerce-Protocol/devops-maintainers @Universal-Commerce-Protocol/maintainers @Universal-Commerce-Protocol/tech-council @Universal-Commerce-Protocol/governance-council
+/main.py                  @Universal-Commerce-Protocol/devops-maintainers @Universal-Commerce-Protocol/maintainers @Universal-Commerce-Protocol/tech-council @Universal-Commerce-Protocol/governance-council
+/.cspell/                 @Universal-Commerce-Protocol/devops-maintainers @Universal-Commerce-Protocol/maintainers @Universal-Commerce-Protocol/tech-council @Universal-Commerce-Protocol/governance-council
+/.cspell.json             @Universal-Commerce-Protocol/devops-maintainers @Universal-Commerce-Protocol/maintainers @Universal-Commerce-Protocol/tech-council @Universal-Commerce-Protocol/governance-council
+/.pre-commit-config.yaml  @Universal-Commerce-Protocol/devops-maintainers @Universal-Commerce-Protocol/maintainers @Universal-Commerce-Protocol/tech-council @Universal-Commerce-Protocol/governance-council
+/.prettierignore          @Universal-Commerce-Protocol/devops-maintainers @Universal-Commerce-Protocol/maintainers @Universal-Commerce-Protocol/tech-council @Universal-Commerce-Protocol/governance-council
+/.prettierrc              @Universal-Commerce-Protocol/devops-maintainers @Universal-Commerce-Protocol/maintainers @Universal-Commerce-Protocol/tech-council @Universal-Commerce-Protocol/governance-council
+/.stylelintrc.json        @Universal-Commerce-Protocol/devops-maintainers @Universal-Commerce-Protocol/maintainers @Universal-Commerce-Protocol/tech-council @Universal-Commerce-Protocol/governance-council
+/biome.json               @Universal-Commerce-Protocol/devops-maintainers @Universal-Commerce-Protocol/maintainers @Universal-Commerce-Protocol/tech-council @Universal-Commerce-Protocol/governance-council
+/mkdocs.yml               @Universal-Commerce-Protocol/devops-maintainers @Universal-Commerce-Protocol/maintainers @Universal-Commerce-Protocol/tech-council @Universal-Commerce-Protocol/governance-council
+/.gitignore               @Universal-Commerce-Protocol/devops-maintainers @Universal-Commerce-Protocol/maintainers @Universal-Commerce-Protocol/tech-council @Universal-Commerce-Protocol/governance-council
+/pyproject.toml           @Universal-Commerce-Protocol/devops-maintainers @Universal-Commerce-Protocol/maintainers @Universal-Commerce-Protocol/tech-council @Universal-Commerce-Protocol/governance-council
+/uv.lock                  @Universal-Commerce-Protocol/devops-maintainers @Universal-Commerce-Protocol/maintainers @Universal-Commerce-Protocol/tech-council @Universal-Commerce-Protocol/governance-council
+/package.json             @Universal-Commerce-Protocol/devops-maintainers @Universal-Commerce-Protocol/maintainers @Universal-Commerce-Protocol/tech-council @Universal-Commerce-Protocol/governance-council
+/package-lock.json        @Universal-Commerce-Protocol/devops-maintainers @Universal-Commerce-Protocol/maintainers @Universal-Commerce-Protocol/tech-council @Universal-Commerce-Protocol/governance-council
 
 # Documentation
-/docs/                    @Universal-Commerce-Protocol/devops-maintainers
-/docs/specification/      @Universal-Commerce-Protocol/maintainers
+/docs/                    @Universal-Commerce-Protocol/devops-maintainers @Universal-Commerce-Protocol/maintainers @Universal-Commerce-Protocol/tech-council @Universal-Commerce-Protocol/governance-council
+/docs/specification/      @Universal-Commerce-Protocol/maintainers @Universal-Commerce-Protocol/tech-council @Universal-Commerce-Protocol/governance-council
 
 # Core Protocol
-/source/                  @Universal-Commerce-Protocol/tech-council
+/source/                  @Universal-Commerce-Protocol/tech-council @Universal-Commerce-Protocol/governance-council
 
 # Governance
+/LICENSE                 @Universal-Commerce-Protocol/governance-council
 /.github/CODEOWNERS      @Universal-Commerce-Protocol/governance-council

.github/workflows/docs.yml

@@ -27,7 +27,8 @@ on:
       - main
     paths:
       - ".github/workflows/docs.yml"
-      - "requirements-docs.txt"
+      - "pyproject.toml"
+      - "uv.lock"
       - "mkdocs.yml"
       - "main.py"
       - "hooks.py"
@@ -63,7 +64,7 @@ jobs:
         uses: astral-sh/setup-uv@v7
 
       - name: Install documentation dependencies
-        run: uv sync
+        run: uv sync --all-groups
 
       - name: Lint YAML files
         run: uv run yamllint -c .github/linters/.yamllint.yml .
@@ -74,6 +75,14 @@ jobs:
         with:
           files: source/**
 
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Cargo
+        uses: Swatinem/rust-cache@v2
+        with:
+          cache-on-failure: true
+
       - name: Install ucp-schema for runtime resolution
         run: |
           cargo install ucp-schema
@@ -110,9 +119,19 @@ jobs:
           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: uv 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'
@@ -123,7 +142,7 @@ jobs:
 
           # 2. Build Root Site (DOCS_MODE=root)
           export DOCS_MODE=root
-          uv run mkdocs build
+          uv run mkdocs build --strict
 
           # 3. Deploy Root Site to gh-pages root
           # Fetch and checkout gh-pages
@@ -134,6 +153,10 @@ jobs:
           cp -r site/* .
           rm -rf site
 
+          # Add redirects for all specification files
+          rm -rf specification
+          ln -s latest/specification specification
+
           # Commit and push
           git add .
           git commit -m "Deploy root site from main" --allow-empty
@@ -146,8 +169,22 @@ jobs:
           # Extract the date (e.g., release/2026-01-11 -> 2026-01-11)
           VERSION_NAME=${GITHUB_REF#refs/heads/release/}
 
-          # 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
+          # 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."
+            uv run mike deploy --push --update-aliases "$VERSION_NAME" latest
+          else
+            echo "This is NOT the latest version. Deploying without updating 'latest' alias."
+            uv run mike deploy --push "$VERSION_NAME"
+          fi
 
       - name: Create GitHub Release and Tag
         if: startsWith(github.ref, 'refs/heads/release/')

.github/workflows/linter.yaml

@@ -19,12 +19,23 @@ on:
     branches:
       - main
       - 'release/**'
+    paths:
+      - ".github/workflows/linter.yaml"
+      - ".github/workflows/schema-validation.yml"
+      - ".github/linters/**"
+      - ".pre-commit-config.yaml"
+      - "pyproject.toml"
+      - "package.json"
+      - "package-lock.json"
+      - "biome.json"
+      - "scripts/**"
+      - "source/**"
+      - "docs/**"
+      - "*.py"
 
 permissions:
   contents: read      # Required to checkout the code
   packages: read      # Required to pull the Super-Linter docker image
-  statuses: write     # Required to fix the 403 error (updating status checks)
-  pull-requests: write # Required for posting comments on PRs
 
 jobs:
   build:
@@ -41,15 +52,17 @@ jobs:
         uses: super-linter/super-linter/slim@v8.5.0
         env:
           DEFAULT_BRANCH: ${{ github.base_ref }}
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          MULTI_STATUS: false
+          ENABLE_GITHUB_PULL_REQUEST_SUMMARY_COMMENT: false
           MARKDOWN_CONFIG_FILE: ".markdownlint.json"
           PYTHON_RUFF_CONFIG_FILE: ../../pyproject.toml
           PYTHON_RUFF_FORMAT_CONFIG_FILE: ../../pyproject.toml
           PYTHON_RUFF_FORMAT_CHECK_ONLY_MODE_OPTIONS: "--check --diff"
           LOG_LEVEL: INFO
           SHELLCHECK_OPTS: -e SC1091 -e 2086
           VALIDATE_ALL_CODEBASE: false
-          FILTER_REGEX_EXCLUDE: "^(\\.github/|\\.vscode/).*|CODE_OF_CONDUCT.md|CHANGELOG.md"
+          FILTER_REGEX_EXCLUDE: >-
+            ^(\\.github/|\\.vscode/).*|CODE_OF_CONDUCT.md|CHANGELOG.md
           VALIDATE_BIOME_FORMAT: false
           VALIDATE_PYTHON_BLACK: false
           VALIDATE_PYTHON_FLAKE8: false
@@ -67,3 +80,4 @@ jobs:
           VALIDATE_GITHUB_ACTIONS_ZIZMOR: false
           VALIDATE_JSCPD: false
           VALIDATE_SPELL_CODESPELL: false  # Using cspell (spellcheck.yaml)
+          VALIDATE_OPENAPI: false

.linkignore

@@ -0,0 +1,6 @@
+# Ignore ucp.dev dummy links
+https://ucp\.dev/specification/reference\?v=2026-01-11
+
+# Ignore latest specification links because the target version folder is not pulled down during --main-only checks
+/latest/specification/.*
+latest/specification/.*

.pre-commit-config.yaml

@@ -55,5 +55,6 @@ repos:
     hooks:
       - id: prettier
         name: prettier-css
-        types: [css]  # Only run on CSS files
-        # If you want it to run on EVERYTHING (JS, JSON, MD), remove the 'types' line.
+        # Only run on CSS files
+        types: [css]
+        # To run on everything (JS, JSON, MD), remove the 'types' line.

docs/documentation/core-concepts.md

@@ -40,7 +40,7 @@ Its primary goal is to enable:
 <!-- Responsive image: shows ucp-diagram-mobile.jpg on small screens (<=600px)
      and ucp-diagram.jpg on larger screens. -->
 <picture>
-  <source media="(max-width: 600px)" srcset="../assets/ucp-diagram-mobile.png">
+  <source media="(max-width: 600px)" srcset="../assets/ucp-diagram-mobile.jpg">
   <img alt="UCP Diagram" src="../assets/ucp-diagram.jpg">
 </picture>