docs: add discovery rules and agent checkout flow

CONTRIBUTING.md

@@ -130,6 +130,9 @@ models run `bash sdk/python/generate_models.sh`. Our CI system runs
 `scripts/ci_check_models.sh` to verify that models can be generated
 successfully from the schemas.
 
+If you want a single command that regenerates schemas and SDK artifacts, run
+`bash scripts/regenerate_artifacts.sh`.
+
 It is also important to go through documentation locally whenever spec files
 are updated to ensure there are no broken references or stale/missing contents.
 

docs/specification/checkout-rest.md

@@ -49,6 +49,54 @@ All REST endpoints **MUST** be served over HTTPS with minimum TLS version
 | [Complete Checkout](checkout.md#complete-checkout) | `POST` | `/checkout-sessions/{id}/complete` | Place the order. |
 | [Cancel Checkout](checkout.md#cancel-checkout) | `POST` | `/checkout-sessions/{id}/cancel` | Cancel a checkout session. |
 
+## Agent Checkout Reference Flow
+
+This sequence shows a canonical REST flow for an agent completing checkout.
+
+```mermaid
+sequenceDiagram
+  participant Platform
+  participant Business
+  Platform->>Business: POST /checkout-sessions (create checkout)
+  Business-->>Platform: 201 checkout (status=incomplete)
+  Platform->>Business: PUT /checkout-sessions/{id} (add buyer/fulfillment)
+  Business-->>Platform: 200 checkout (status=ready_for_complete)
+  Platform->>Business: POST /checkout-sessions/{id}/complete
+  Business-->>Platform: 200 checkout (status=completed, order)
+```
+
+### Minimal Payloads
+
+**Create checkout (request)**
+
+```json
+{
+  "line_items": [
+    {
+      "item": { "id": "item_123", "title": "Red T-Shirt", "price": 2500 },
+      "quantity": 1
+    }
+  ]
+}
+```
+
+**Complete checkout (request)**
+
+```json
+{
+  "id": "chk_1234567890",
+  "payment": {
+    "handlers": [
+      {
+        "id": "business_tokenizer",
+        "type": "token",
+        "credential": { "token": "tok_visa_123" }
+      }
+    ]
+  }
+}
+```
+
 ## Examples
 
 ### Create Checkout
@@ -1346,4 +1394,4 @@ authentication is required, the REST transport **MAY** use:
 4.  **Mutual TLS**: For high-security environments.
 
 Businesses **MAY** require authentication for some operations while leaving
-others open (e.g., public checkout without authentication).
+others open (e.g., public checkout without authentication).

docs/specification/overview.md

@@ -330,6 +330,19 @@ capabilities. Payment configuration is a sibling—see
 contains public keys (JWK format) used to verify signatures on webhooks and
 other authenticated messages from the business.
 
+#### Profile Validation Rules
+
+Profiles **MUST** conform to the discovery schema and follow these rules:
+
+- `ucp.version` **MUST** be a valid `YYYY-MM-DD` version string.
+- `ucp.services` **MUST** include a `dev.ucp.shopping` entry for Shopping use
+  cases.
+- Service `endpoint` values **MUST NOT** include a trailing slash.
+- If `rest` is present, both `schema` and `endpoint` **MUST** be provided.
+- Capability `spec` and `schema` URLs **MUST** be absolute and HTTPS.
+- Capabilities that declare `extends` **MUST** reference a capability present
+  in the same profile.
+
 #### Platform Profile
 
 Platform profiles are similar and include signing keys for capabilities
@@ -1168,4 +1181,4 @@ Vendors control their own release schedules and versioning strategy.
 | **Payment Service Provider**      | PSP     | The financial infrastructure provider that processes payments, authorizations, and settlements on behalf of the business.               |
 | **Platform**                      | -       | The consumer-facing surface (AI agent, app, website) acting on behalf of the user to discover businesses and facilitate commerce.                              |
 | **Verifiable Digital Credential** | VDC     | An Issuer-signed credential (set of claims) whose authenticity can be verified cryptographically. Used in UCP for secure payment authorizations.              |
-| **Verifiable Presentation**       | VP      | A presentation of one or more VDCs that includes a cryptographic proof of binding, used to prove authorization to a business or PSP.                          |
+| **Verifiable Presentation**       | VP      | A presentation of one or more VDCs that includes a cryptographic proof of binding, used to prove authorization to a business or PSP.                          |

scripts/regenerate_artifacts.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+# Regenerates spec outputs and SDK models in one command.
+
+set -e
+
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+
+cd "$ROOT_DIR"
+
+python generate_schemas.py
+
+SDK_SCRIPT="$ROOT_DIR/sdk/python/generate_models.sh"
+if [ -f "$SDK_SCRIPT" ]; then
+  bash "$SDK_SCRIPT"
+else
+  echo "SDK generator not found at $SDK_SCRIPT. Skipping SDK regeneration."
+fi