Merge pull request #550 from accordproject/docs/h2-agentic-commerce-revamp

Author: dselman

docs/accordproject-agentic-commerce.md

@@ -0,0 +1,109 @@
+---
+id: accordproject-agentic-commerce
+title: Agentic Commerce
+---
+
+## The enforceable-terms layer for autonomous commerce
+
+As AI agents begin to transact on people's behalf, the ecosystem is converging on a layered architecture. Each layer solves a distinct problem, and no single layer solves them all:
+
+- **Identity & trust** — who is this agent, and is it legitimate?
+- **Authorization proof** — what did the user authorize the agent to do, and can we prove the agent stayed within those bounds? *(Verifiable Intent, AP2 credentials.)*
+- **Payment & checkout transport** — how does the agent create a checkout session and move payment credentials? *(UCP, ACP, Mastercard Agent Pay.)*
+- **The agreement** — what are the enforceable terms of the deal, and how do the obligations execute over its lifetime? *(Accord Project.)*
+
+Accord Project is the **agreement** layer. The others authorize and route a transaction; Accord Project defines the contract that transaction rests on — its terms, its computable obligations, and its remedies — in a form that is both machine-executable and legally interpretable.
+
+> **Verifiable Intent proves what an agent was *authorized* to do. Accord Project defines and executes the *agreement* it was authorized to enter.**
+
+```
+┌───────────────────────────────────────────────────────────────┐
+│  IDENTITY & TRUST        who is the agent?                    │
+├───────────────────────────────────────────────────────────────┤
+│  AUTHORIZATION PROOF     what was authorized? did the agent   │
+│  Verifiable Intent, AP2  stay in bounds? (cryptographic proof)│
+├───────────────────────────────────────────────────────────────┤
+│  PAYMENT & CHECKOUT      how is the transaction routed and    │
+│  UCP, ACP, Agent Pay     settled?                             │
+├───────────────────────────────────────────────────────────────┤
+│  THE AGREEMENT           what are the enforceable terms, and  │
+│  ▶ Accord Project        how do obligations run over time?    │
+└───────────────────────────────────────────────────────────────┘
+```
+
+## What each layer does — and does not do
+
+Authorization protocols such as [Verifiable Intent](https://verifiableintent.dev/) (VI) are, by their own definition, a portable and independently verifiable record of *what a user authorized an agent to do* and proof that the agent stayed within those bounds. That is a different concern from the agreement itself. Reading the VI specification, its expressive vocabulary for "intent" is a set of transaction-scoped **constraints** — allowed merchants, allowed payees, an amount range, permitted line items, a spending budget, and recurrence limits. This is exactly what an authorization envelope needs, and deliberately no more.
+
+The substance of the deal lives outside that envelope — and inside an Accord Project contract:
+
+| Concern | Authorization layer (e.g. Verifiable Intent) | Accord Project |
+|---|---|---|
+| Proof an agent was authorized | ✅ Cryptographic delegation chain | — |
+| Key binding, selective disclosure | ✅ SD-JWT credential format | — |
+| Transaction-scoped spend/merchant limits | ✅ Signed constraints | Can model the same constraints as typed data |
+| Substantive terms (warranty, returns, SLA, delivery, liability, data use) | Treated as informational, not enforced | ✅ Typed model + court-readable text |
+| Obligations that run **after** settlement | Out of scope (flow ends at settlement) | ✅ Executable logic over the contract lifecycle |
+| Remedies and outcomes on breach | Audit *trail* only | ✅ Computable logic that determines the *outcome* |
+| Bilateral, negotiated agreement | Unilateral user→agent delegation | ✅ An agreement between parties |
+
+The clean division of labour: authorization proves the agent stayed in bounds; Accord Project defines what the deal *is* and enforces it over time.
+
+## How Accord Project plugs in
+
+Authorization frameworks are designed to be extensible, and they leave open exactly the slot Accord Project fills. AP2, for example, defines a Verifiable Digital Credential (VDC) trust mechanism but leaves the credential format open — which is the slot Verifiable Intent fills. The *enforceable-terms* slot is open in the same way. Three concrete integration patterns:
+
+### 1. A contract as the terms a mandate binds to
+
+Authorization credentials already bind to a checkout artifact by hash (for example, VI binds a `checkout_jwt` via a SHA-256 `checkout_hash`). An Accord Project contract — or its rendered [AgreementMark](markup-templatemark.md) form — can be bound the same way: the credential references the contract by hash, so the user is provably authorizing acceptance of **specific enforceable terms**, not just a list of line items and a merchant name. This gives the "what-you-see-is-what-you-sign" consent surface real legal substance, using the court-readable TemplateMark text as the human-facing artifact.
+
+### 2. Concerto as the schema language for the constraint registry
+
+Authorization constraints are, structurally, a typed-schema problem: dot-notation type discriminators, a versioned registry, namespaced extensibility, and validators that must run in every language a merchant, PSP, or payment network uses. [Concerto](https://concerto.accordproject.org/docs/intro) is built for exactly this. A constraint registry modelled in Concerto generates, from a single source of truth:
+
+| Target | Use case |
+|---|---|
+| **JSON Schema** | Validating credentials and constraint payloads |
+| **TypeScript** | Agent and verifier logic, frontend type safety |
+| **Java** | Enterprise backend / processor integration |
+| **Go** | High-performance network services |
+| **C#** | .NET integrations |
+
+Instead of hand-writing and re-validating constraint types per runtime, the polyglot verifiers a trust framework requires are generated and kept in lockstep.
+
+### 3. Contract logic for the terms authorization can't enforce
+
+Authorization layers explicitly treat descriptive fields (product description, brand, colour, size) and post-settlement behaviour as informational — not subject to automated verification. Accord Project [TypeScript logic](logic-typescript.md) can make many of these enforceable: delivery-date-within-window, total-including-tax-under-budget, warranty conditions, refund and return eligibility, milestone and SLA obligations. The compiler acts as a verification step between agent output and execution, so errors in agent-generated terms surface as compile failures rather than silent runtime bugs in a live contract.
+
+## Immediate vs. autonomous transactions
+
+Authorization frameworks distinguish **human-in-the-loop** transactions (the user confirms the final purchase) from **autonomous** ones (the user sets constraints and the agent acts independently). Accord Project is valuable in both:
+
+- **Human-in-the-loop** — the contract is the terms the user reviews and confirms; its logic computes the figures (totals, schedules, fees) shown at the point of consent.
+- **Autonomous** — the contract's typed model can express the same constraints the agent must honour, its logic can enforce the terms the authorization layer treats as informational, and its lifecycle obligations continue to execute long after the agent's authority to *initiate* the transaction has expired.
+
+## Relationship to agentic commerce protocols
+
+Accord Project is transport- and protocol-agnostic and complements, rather than competes with, the emerging protocol stack:
+
+- **[AP2](https://github.com/google-agentic-commerce/AP2)** (Agent Payments Protocol) — defines an abstract credential/mandate framework and leaves the credential format open. Accord Project supplies enforceable terms that a mandate can reference.
+- **[UCP](https://github.com/Universal-Commerce-Protocol/ucp)** (Universal Commerce Protocol) — a concrete checkout protocol aligned with AP2, with extension fields for mandate data. A contract reference can ride those fields without changes to core endpoints.
+- **[ACP](https://github.com/agentic-commerce-protocol/agentic-commerce-protocol)** (Agentic Commerce Protocol) — a REST checkout and payment-delegation protocol whose extension mechanism can carry a contract reference alongside standard checkout mechanics.
+
+## What Accord Project does not do
+
+To keep the boundary clear: Accord Project is **not** an identity, authorization, or payment layer. It does not issue credentials, perform key binding, or implement selective disclosure — those are the province of Verifiable Intent, AP2, and the payment networks. Accord Project provides the enforceable agreement those layers authorize and settle.
+
+## Status of these integration patterns
+
+The integration patterns above are illustrative of how Accord Project's format aligns with the agentic commerce stack; they describe technical fit, not partnerships or endorsements. Concrete adoption architecture for any specific protocol or trust framework should be developed in coordination with that project's maintainers. If you are working on agentic commerce and want to explore these patterns, [join the community](https://discord.com/invite/Zm99SKhhtA).
+
+## Further reading
+
+- [Overview](accordproject.md) — what Accord Project is
+- [AI & Agent Workflows](accordproject-ai.md) — computable contracts as agent infrastructure
+- [Smart Legal Contracts](accordproject-slc.md) — how machine-readable and machine-executable contracts work
+- [Concerto Documentation](https://concerto.accordproject.org/docs/intro) — the schema DSL and its code generators
+- [Template Logic in TypeScript](logic-typescript.md) — writing strongly-typed contract logic
+- [APAP Reference](ref-apap.md) — the agreement protocol API, including the MCP endpoint
+- [2024 Whitepaper: *An Introduction to Computable Contracts*](https://accordproject.org/whitepaper-2024/)

docs/accordproject-ai.md

@@ -13,6 +13,8 @@ The 2024 Accord Project whitepaper, [*An Introduction to Computable Contracts*](
 
 Accord Project's three-component template architecture — **Text**, **Model**, and **Logic** — maps directly onto how modern AI agents operate. Each component is a format that agents can reliably read, write, validate, and reason over.
 
+This guide covers how agents work *with the contract format* — drafting, validating, and executing templates. For how Accord Project fits the wider agentic commerce stack — where agents *transact* on a user's behalf and authorization layers like Verifiable Intent and AP2 come into play — see the [Agentic Commerce](accordproject-agentic-commerce.md) guide.
+
 ---
 
 ## Why Markdown?
@@ -129,6 +131,8 @@ POST /triggers/{templateId}
 }
 ```
 
+In an agentic commerce flow, APAP is the interface through which an agent enters and executes the *agreement* — the terms authorized and settled by layers such as Verifiable Intent, AP2, and the payment networks. See [Agentic Commerce](accordproject-agentic-commerce.md) for how these layers fit together.
+
 See the [APAP tutorial](tutorial-apap.md) and [APAP reference](ref-apap.md) for full documentation.
 
 ---
@@ -163,11 +167,10 @@ The Accord Project maintains a set of Agent Skills in the [`accordproject/skills
 | [`template-author`](https://github.com/accordproject/skills/tree/main/skills/template-author) | Scaffold and edit Accord Project smart legal contract templates. |
 | [`template-migrate`](https://github.com/accordproject/skills/tree/main/skills/template-migrate) | Migrate Cicero templates between major versions (e.g. 0.24/0.25 → 0.26). |
 
-To install a skill for Claude Code, copy its directory into your user-level skills folder:
+To install these skills for Claude Code, use the `skills` CLI:
 
 ```
-git clone https://github.com/accordproject/skills.git
-cp -r skills/skills/concerto-author ~/.claude/skills/
+npx skills add accordproject/skills
 ```
 
 Other agent harnesses load skills from their own configured locations — consult the harness documentation.
@@ -176,6 +179,7 @@ Other agent harnesses load skills from their own configured locations — consul
 
 ## Further Reading
 
+- [Agentic Commerce](accordproject-agentic-commerce.md) — how Accord Project is the enforceable-terms layer for autonomous commerce, alongside Verifiable Intent, AP2, UCP, and ACP
 - [2024 Whitepaper: *An Introduction to Computable Contracts*](https://accordproject.org/whitepaper-2024/) — the full case for computable contracts as agent infrastructure (also available as [Markdown on GitHub](https://github.com/accordproject/whitepaper-2024/blob/main/whitepaper.md))
 - [Smart Legal Contracts](accordproject-slc.md) — how machine-readable and machine-executable contracts work
 - [APAP Reference](ref-apap.md) — full API specification including MCP endpoint

docs/accordproject-faq.md

@@ -37,6 +37,18 @@ The result is a contract that is:
 
 Consequently, contracts are transformed from business liabilities in constant need of management to assets capable of providing real business intelligence and value. A Smart Contract contains a data model so that the data is part of the contract and not something held in an external system. The logical operations of the contract are also part of the contract. The contract can update itself and react to the outside world. Rather than being stored in filing cabinet it is a living breathing process.
 
+### Do I need to be a developer to use Accord Project?
+
+No. You can explore, edit, and test Accord Project contracts and data models entirely in your web browser — no installation and no coding required. The [Template Playground](https://playground.accordproject.org) lets you edit a contract's text, data, and logic and see the result update live, and the [Concerto Playground](https://concerto-playground.accordproject.org) lets you design and validate data models. See [Try It in Your Browser](started-playground.md) to get started. When you are ready to work locally or integrate templates into an application, developers can use the Cicero command-line tools and write contract logic in TypeScript.
+
+### How does Accord Project relate to AI and AI agents?
+
+Increasingly, AI tools and agents are used to draft, review, negotiate, and execute contracts. Accord Project gives them a structured, validated, and legally meaningful format to work with, rather than free-form documents they must interpret by guesswork. Template text is written in Markdown (which language models already understand well), the data model is a strongly-typed [Concerto](https://concerto.accordproject.org/docs/intro) schema that grounds AI output and reduces hallucination, and contract logic is TypeScript whose compiler catches errors before execution. Templates can also be called directly by agents over the [APAP REST API](ref-apap.md), including a Model Context Protocol (MCP) endpoint. See the [AI & Agent Workflows](accordproject-ai.md) guide for details.
+
+### What is Accord Project's role in AI agentic commerce?
+
+As AI agents begin to transact on people's behalf, new trust layers — such as Verifiable Intent, the Agent Payments Protocol (AP2), and agentic commerce protocols — provide cryptographic proof of *what a user authorized an agent to do*. They do not, by themselves, define the *agreement* behind a transaction: its enforceable terms, the obligations that continue after payment, and the remedies if something goes wrong. That is the layer Accord Project provides — terms that are both machine-executable and legally interpretable. In short: those layers prove what an agent was *authorized* to do, and Accord Project defines and executes the *agreement* it was authorized to enter. See [Agentic Commerce](accordproject-agentic-commerce.md) for how these layers fit together.
+
 ### What is the Accord Project and what is its purpose?
 
 The Accord Project is a non-profit, member-driven organization that builds open source code and documentation for smart legal contracts for use by transactional attorneys, business and finance professionals, and other contract users. Open source means that anyone can use and contribute to the code and documentation and use it in their own software applications and systems free of charge.

docs/accordproject-template.md

@@ -1,6 +1,6 @@
 ---
 id: accordproject-template
-title: Accord Project Templates
+title: Templates
 ---
 
 An Accord Project template ties legal text to computer code. It is composed of three elements: