chore: Include schema and documentation development instructions in README.md for better discoverability

README.md

@@ -41,91 +41,149 @@ ensuring secure and consistent commerce experiences across the web.
 
 With UCP, businesses can:
 
-* **Declare** supported capabilities to enable autonomous discovery by
-    platforms.
-* **Facilitate** secure checkout sessions, with or without human intervention.
-* **Offer** personalized shopping experiences through standardized data
-    exchange.
+- **Declare** supported capabilities to enable autonomous discovery by
+  platforms.
+- **Facilitate** secure checkout sessions, with or without human intervention.
+- **Offer** personalized shopping experiences through standardized data
+  exchange.
 
 ## Why UCP?
 
 As commerce becomes increasingly agentic and distributed, the ability for
 different systems to interoperate without custom, one-off integrations is vital.
 UCP aims to:
 
-* **Standardize Interaction:** Provide a uniform way for platforms to interact
-    with businesses, regardless of the underlying backend.
-* **Modularize Commerce:** Breakdown commerce into distinct **Capabilities**
-    (e.g., Checkout, Order) and **Extensions** (e.g., Discounts,
-    Fulfillment), allowing for flexible implementation.
-* **Enable Agentic Commerce:** Designed from the ground up to support AI
-    agents acting on behalf of users to discover products, fill carts, and
-    complete purchases securely.
-* **Enhance Security:** Support for advanced security patterns like AP2
-    mandates and verifiable credentials.
+- **Standardize Interaction:** Provide a uniform way for platforms to interact
+  with businesses, regardless of the underlying backend.
+- **Modularize Commerce:** Breakdown commerce into distinct **Capabilities**
+  (e.g., Checkout, Order) and **Extensions** (e.g., Discounts, Fulfillment),
+  allowing for flexible implementation.
+- **Enable Agentic Commerce:** Designed from the ground up to support AI agents
+  acting on behalf of users to discover products, fill carts, and complete
+  purchases securely.
+- **Enhance Security:** Support for advanced security patterns like AP2 mandates
+  and verifiable credentials.
 
 ### Key Features
 
-* **Composable Architecture:** UCP defines **Capabilities** (such as
-    "Checkout" or "Identity Linking") that businesses implement to enable easy
-    integration. On top of that, specific **Extensions** can be added to enhance
-    the consumer experience without bloating the capability definitions.
-* **Dynamic Discovery:** Businesses declare their supported Capabilities in a
-    standardized profile, allowing platforms to autonomously discover and
-    configure themselves.
-* **Transport Agnostic:** The protocol is designed to work across various
-    transports. Businesses can offer Capabilities via REST APIs, MCP (Model
-    Context Protocol), or A2A, depending on their infrastructure.
-* **Built on Standards:** UCP leverages existing open standards for payments,
-    identity, and security wherever applicable, rather than reinventing the
-    wheel.
-* **Developer Friendly:** A comprehensive set of SDKs and libraries
-    facilitates rapid development and integration.
+- **Composable Architecture:** UCP defines **Capabilities** (such as "Checkout"
+  or "Identity Linking") that businesses implement to enable easy integration.
+  On top of that, specific **Extensions** can be added to enhance the consumer
+  experience without bloating the capability definitions.
+- **Dynamic Discovery:** Businesses declare their supported Capabilities in a
+  standardized profile, allowing platforms to autonomously discover and
+  configure themselves.
+- **Transport Agnostic:** The protocol is designed to work across various
+  transports. Businesses can offer Capabilities via REST APIs, MCP (Model
+  Context Protocol), or A2A, depending on their infrastructure.
+- **Built on Standards:** UCP leverages existing open standards for payments,
+  identity, and security wherever applicable, rather than reinventing the wheel.
+- **Developer Friendly:** A comprehensive set of SDKs and libraries facilitates
+  rapid development and integration.
 
 ## Key Capabilities
 
 The initial release focuses on the essential primitives for transacting:
 
-* **Checkout:** Facilitates checkout sessions including cart management and
-    tax calculation, supporting flows with or without human intervention.
-* **Identity Linking:** Enables platforms to obtain authorization to perform
-    actions on a user's behalf via OAuth 2.0.
-* **Order:** Webhook-based updates for order lifecycle events (shipped,
-    delivered, returned).
-* **Payment Token Exchange:** Protocols for PSPs and Credential Providers to
-    securely exchange payment tokens and credentials.
+- **Checkout:** Facilitates checkout sessions including cart management and tax
+  calculation, supporting flows with or without human intervention.
+- **Identity Linking:** Enables platforms to obtain authorization to perform
+  actions on a user's behalf via OAuth 2.0.
+- **Order:** Webhook-based updates for order lifecycle events (shipped,
+  delivered, returned).
+- **Payment Token Exchange:** Protocols for PSPs and Credential Providers to
+  securely exchange payment tokens and credentials.
 
 ## Getting Started
 
-* 📚 **Explore the Documentation:** Visit [ucp.dev](https://ucp.dev) for a
-    complete overview, the full protocol specification, tutorials, and guides.
-* 🎬 **Review our
-    [samples](https://github.com/Universal-Commerce-Protocol/samples)** for
-    implementation examples.
-* 🛠️ **Use our
-    [SDKs](https://github.com/orgs/Universal-Commerce-Protocol/repositories)**
-    to start building your own integrations.
-* 📝 **Check conformance** with our [conformance tests](https://github.com/Universal-Commerce-Protocol/conformance).
+- 📚 **Explore the Documentation:** Visit [ucp.dev](https://ucp.dev) for a
+  complete overview, the full protocol specification, tutorials, and guides.
+- 🎬 **Review our
+  [samples](https://github.com/Universal-Commerce-Protocol/samples)** for
+  implementation examples.
+- 🛠️ **Use our
+  [SDKs](https://github.com/orgs/Universal-Commerce-Protocol/repositories)** to
+  start building your own integrations.
+- 📝 **Check conformance** with our
+  [conformance tests](https://github.com/Universal-Commerce-Protocol/conformance).
 
 ## Contributing
 
 We welcome community contributions to enhance and evolve UCP.
 
-* **Questions & Discussions:** Join our [GitHub
-    Discussions](https://github.com/Universal-Commerce-Protocol/ucp/discussions).
-* **Issues & Feedback:** Report issues or suggest improvements via GitHub
-    Issues.
-* **Contribution Guide:** See our [CONTRIBUTING.md](https://github.com/Universal-Commerce-Protocol/.github/blob/main/CONTRIBUTING.md)
-    for details on how to contribute.
+- **Questions & Discussions:** Join our
+  [GitHub Discussions](https://github.com/Universal-Commerce-Protocol/ucp/discussions).
+- **Issues & Feedback:** Report issues or suggest improvements via GitHub
+  Issues.
+- **Contribution Guide:** See our
+  [CONTRIBUTING.md](https://github.com/Universal-Commerce-Protocol/.github/blob/main/CONTRIBUTING.md)
+  for details on how to contribute.
+
+### Schema Development
+
+Schemas live in `source/` and are published with `ucp_*` annotations intact.
+**Agents** (such as AI assistants or platforms participating
+in the protocol) can use the
+[ucp-schema](https://github.com/universal-commerce-protocol/ucp-schema) tool to
+resolve these annotations at runtime. This enables them to generate
+operation-specific schema variants (e.g., for 'create', 'update', or 'read'
+operations) from the master schemas, ensuring they only process fields relevant
+to the current action and direction (request vs. response).
+
+1. Ensure `ucp-schema` is installed:
+
+   ```bash
+   cargo install ucp-schema                 # from crates.io
+   cargo install --git https://github.com/universal-commerce-protocol/ucp-schema  # from git
+   ```
+
+1. Make updates to JSON files in `source/`
+
+1. Run `ucp-schema lint source/` to validate syntax and references
+
+### Documentation Development
+
+This project uses [uv](https://docs.astral.sh/uv/) for Python dependency
+management.
+
+1. Install Python dependencies: `uv sync`
+1. Ensure `ucp-schema` is installed (see above)
+1. Run the development server: `uv run mkdocs serve --watch source`
+1. Open **<http://127.0.0.1:8000>** in your browser
+1. Before submitting, run `uv run mkdocs build --strict` to check for
+   warnings/errors
+
+Alternatively, you can use the local build script to build the full site
+including spec versions:
+
+```bash
+./scripts/build_local.sh
+```
+
+This will build the site and start a local server. You can use the
+`--draft-only` flag to skip release branches and only build the current draft:
+
+```bash
+./scripts/build_local.sh --draft-only
+```
+
+You can start the documentation server locally by running
+
+```bash
+python3 -m http.server 8000 -d "local_preview"
+```
+
+The local version of the documentation website will then be available at
+**<http://127.0.0.1:8000>**
 
 ## What's Next
 
 Take a look at [our roadmap on ucp.dev](https://ucp.dev/documentation/roadmap/).
 Future enhancements include:
 
-* **New Verticals:** Applications beyond Shopping (e.g., Travel, Services).
-* **Loyalty:** Standardized management of loyalty programs and rewards.
-* **Personalization:** Enhanced signals for personalized product discovery.
+- **New Verticals:** Applications beyond Shopping (e.g., Travel, Services).
+- **Loyalty:** Standardized management of loyalty programs and rewards.
+- **Personalization:** Enhanced signals for personalized product discovery.
 
 ## About