docs: reorganize structure with conceptual bridge

doc/architecture/MPCP_IMPLEMENTATION_ROADMAP.md

@@ -837,6 +837,42 @@ Implemented: `docs/` with overview (what-is-mpcp, problem, comparison-with-agent
 
 ⸻
 
+### PR18A — Protocol Chain Hero Diagram
+
+Add a canonical **MPCP Authorization Chain diagram** to the documentation homepage and architecture section.
+
+Diagram structure:
+
+PolicyGrant  
+→ SignedBudgetAuthorization  
+→ SignedPaymentAuthorization  
+→ Settlement
+
+Each layer visually represents how MPCP **progressively constrains machine spending authority**.
+
+Recommended labeling:
+
+• PolicyGrant — defines where and how a machine may pay  
+• SignedBudgetAuthorization — enforces session spending limits  
+• SignedPaymentAuthorization — authorizes a specific payment  
+• Settlement — records what actually happened
+
+Purpose:
+
+• give developers an immediate mental model of MPCP  
+• visually communicate the protocol’s constrained authorization chain  
+• establish a recognizable visual identity for MPCP documentation
+
+Deliverables:
+
+• SVG diagram included in docs/diagrams/  
+• diagram embedded on the docs homepage  
+• diagram referenced in protocol overview pages
+
+This diagram becomes the **primary visual explanation of the MPCP protocol** and should appear early in the documentation to help new readers understand the authorization model quickly.
+
+⸻
+
 PR19 — Documentation Site Deployment ✓
 
 Deploy the docs site so it is publicly accessible (e.g., GitHub Pages). Implemented: `mkdocs.yml`, `docs-requirements.txt`, `.github/workflows/deploy-docs.yml`. Enable GitHub Pages (Settings → Pages → Source: GitHub Actions) to publish.
@@ -848,6 +884,24 @@ Purpose:
 
 ⸻
 
+PR20 — Golden Protocol Vectors ✓
+
+Freeze a set of canonical MPCP test vectors for interoperability and regression testing. Implemented: `vectors/` (manifest.json, valid-settlement.json, expired-grant.json, budget-exceeded.json, intent-hash-mismatch.json, settlement-mismatch.json), `test/vectors/goldenVectors.test.ts`.
+
+Vectors:
+	•	valid settlement (with intent hash)
+	•	expired grant
+	•	budget exceeded
+	•	intent hash mismatch
+	•	settlement mismatch (payment auth)
+
+Purpose:
+	•	let other implementations validate compatibility
+	•	prevent regressions
+	•	create a real interoperability target
+
+⸻
+
 ---
 
 # Phase 6 — Adoption Acceleration
@@ -1001,6 +1055,7 @@ Deliverables:
 	•	basic badge / claim format
 	•	documentation for how external implementations validate compatibility
 
+⸻
 
 # Expected Outcome
 

doc/protocol/FleetPolicyAuthorization.md

@@ -29,6 +29,8 @@ Fleet operators must ensure that vehicles only spend funds **within fleet‑defi
 
 FPA enables this capability by allowing fleets to issue **signed policy artifacts** that constrain all MPCP spending decisions.
 
+> **Optional extension:** FleetPolicyAuthorization (FPA) is an optional MPCP artifact used by fleet operators to express higher-level fleet governance constraints. Base MPCP flows do not require FPA.
+
 ---
 
 # 2. Problem Statement

docs/animation/MPCP_ANIMATION_PACK.md

@@ -27,11 +27,15 @@ Narration:
 ## Scene 3 — Introducing MPCP
 Visual stack:
 
+Fleet Policy
+↓
 PolicyGrant
 ↓
-BudgetAuthorization
+SignedBudgetAuthorization (SBA)
+↓
+SignedPaymentAuthorization (SPA)
 ↓
-PaymentAuthorization
+SettlementIntent
 ↓
 Settlement
 
@@ -46,8 +50,8 @@ Narration:
 Visual sequence:
 1. Autonomous vehicle enters parking garage
 2. PolicyGrant appears
-3. BudgetAuthorization appears
-4. PaymentAuthorization triggers
+3. SignedBudgetAuthorization (SBA) appears
+4. SignedPaymentAuthorization (SPA) triggers
 5. Settlement confirmation
 
 Narration:
@@ -130,7 +134,7 @@ Protocol comparison diagram
 "clean animated diagram showing protocols MCP A2A ACP communicating between agents and tools, arrows moving between nodes, modern developer diagram style"
 
 ## Prompt 3 — MPCP Authorization Chain
-"layered protocol diagram animation PolicyGrant BudgetAuthorization PaymentAuthorization Settlement blocks stacking vertically with glowing arrows"
+"layered protocol diagram animation PolicyGrant SignedBudgetAuthorization SignedPaymentAuthorization SettlementIntent Settlement blocks stacking vertically with glowing arrows"
 
 ## Prompt 4 — Autonomous Parking Payment
 "autonomous car entering smart parking garage, digital authorization layers appearing around vehicle, futuristic payment confirmation animation"
@@ -153,9 +157,11 @@ Icons
 - blockchain ledger
 
 Protocol blocks
+- Fleet Policy
 - PolicyGrant
-- BudgetAuthorization
-- PaymentAuthorization
+- SignedBudgetAuthorization (SBA)
+- SignedPaymentAuthorization (SPA)
+- SettlementIntent
 - Settlement
 
 Animation style

docs/architecture/actors.md

@@ -0,0 +1,76 @@
+# Actors
+
+MPCP defines several actor types that participate in machine payment flows.
+
+## Fleet Operator
+
+Owns and manages the autonomous fleet (vehicles, robots, agents).
+
+**Responsibilities:**
+
+- Defines vehicle payment policies
+- Sets spending limits
+- Restricts allowed vendors and locations
+- Issues PolicyGrant artifacts
+
+**Examples:** Robotaxi fleet, delivery fleet, autonomous logistics fleet.
+
+## Vehicle Wallet (Machine Wallet)
+
+Resides in each machine (EV, robot, IoT device) and enforces MPCP constraints.
+
+**Responsibilities:**
+
+- Enforces policy constraints
+- Manages charging/payment budgets
+- Issues SignedBudgetAuthorization and SignedPaymentAuthorization
+- Executes settlement transactions
+
+The wallet is the MPCP actor that signs SignedBudgetAuthorization and SignedPaymentAuthorization.
+
+## Service Provider
+
+The entity that receives payment for a service (parking, charging, tolls).
+
+**Responsibilities:**
+
+- Requests payment authorization
+- Verifies MPCP artifact chain
+- Provides or denies service based on verification
+
+**Examples:** Charging network operator, parking operator, toll system.
+
+## Route / Dispatch System
+
+(Optional) Determines routing and service requirements.
+
+**Responsibilities:**
+
+- Determines charging/parking locations along route
+- Identifies approved service networks
+- Provides trip metadata to the vehicle
+
+May influence PolicyGrant constraints.
+
+## MPCP Verifier
+
+Validates the full authorization chain.
+
+**Verification may occur:**
+
+- Inside the service provider backend
+- Inside a dedicated MPCP verification service
+- During post-transaction auditing
+
+## Settlement Rail
+
+Executes the actual payment.
+
+**Examples:** XRPL + RLUSD, EVM stablecoins, Stripe, hosted providers.
+
+MPCP does not replace settlement systems—it **controls authorization above them**.
+
+## See Also
+
+- [Reference Flow](reference-flow.md) — Full actor interaction in EV charging scenario
+- [System Model](system-model.md)

docs/architecture/artifact-lifecycle.md

@@ -0,0 +1,55 @@
+# Artifact Lifecycle
+
+MPCP artifacts flow through a defined lifecycle from policy evaluation to settlement verification.
+
+## Pipeline
+
+```
+Fleet Policy
+↓
+PolicyGrant
+↓
+SignedBudgetAuthorization
+↓
+SignedPaymentAuthorization
+↓
+SettlementIntent
+↓
+Settlement
+```
+
+Each artifact constrains the next. Downstream artifacts must be subsets of upstream constraints.
+
+## Artifact Roles
+
+| Artifact | Issued By | Purpose |
+|----------|-----------|---------|
+| **PolicyGrant** | Fleet/service policy | Initial permission envelope; rails, assets, caps |
+| **SBA** | Vehicle wallet | Session-level spending envelope |
+| **SPA** | Vehicle wallet | Binds specific payment to quote and policy |
+| **SettlementIntent** | Vehicle wallet | Canonical settlement description (optional hash in SPA) |
+| **Settlement Result** | Settlement rail | Confirms execution |
+
+## Typical Lifecycle
+
+1. **Pre-session** — PolicyGrant issued and stored (fleet backend, vehicle wallet)
+2. **Session entry** — Vehicle loads PolicyGrant, may issue SBA
+3. **Payment request** — Service requests payment; vehicle validates policy and budget
+4. **Authorization** — Vehicle creates SettlementIntent, signs SPA
+5. **Verification** — Service verifies MPCP chain
+6. **Settlement** — Payment executes on rail
+7. **Reconciliation** — Settlement verified against authorization
+
+## Storage
+
+Artifacts may be stored in:
+
+- **Fleet backend** — Authoritative PolicyGrant; audit logs
+- **Vehicle wallet** — Operational PolicyGrant, SBA, SPA, receipts
+- **Service provider** — Received authorizations, verification results, receipts
+- **Settlement rail** — Transaction record (authoritative)
+
+## See Also
+
+- [Reference Flow](reference-flow.md) — End-to-end EV charging scenario with timeline
+- [Protocol specs](protocol/mpcp.md) — Full artifact specifications

docs/architecture/authorization-chain.md

@@ -0,0 +1,53 @@
+# MPCP Authorization Chain
+
+The **authorization chain** is the core visual model for MPCP. Each step produces a verifiable artifact that constrains the next. Machines spend within bounds established upstream—no per-transaction approval required.
+
+```
+PolicyGrant
+↓
+SignedBudgetAuthorization
+↓
+SignedPaymentAuthorization
+↓
+SettlementIntent
+↓
+Settlement
+```
+
+In fleet deployments, an optional FleetPolicyAuthorization (FPA) layer may sit above PolicyGrant.
+
+```
+Fleet Policy
+↓
+PolicyGrant
+↓
+SignedBudgetAuthorization
+↓
+SignedPaymentAuthorization
+↓
+SettlementIntent
+↓
+Settlement
+```
+
+## What Each Step Does
+
+| Step | Artifact | Purpose |
+|------|-----------|---------|
+| **Fleet Policy** | Policy definition | Rules: rails, assets, vendors, caps |
+| **PolicyGrant** | Session entry | "This machine may initiate payment under these constraints" |
+| **SignedBudgetAuthorization** | Spending envelope | "Up to X, on these rails, to these destinations" |
+| **SignedPaymentAuthorization** | Payment binding | "This exact payment was authorized" |
+| **SettlementIntent** | Canonical description | Deterministic settlement parameters (optional hash binding) |
+| **Settlement** | Executed transaction | Rail executes payment; verifier checks chain |
+
+## Key Idea
+
+Approval moves **upstream**. The human or policy administrator grants a **session** and **budget**. The machine spends within that budget using pre-authorized intents. Settlement becomes a background operation.
+
+## See Also
+
+- [System Model](system-model.md) — How the chain fits in the overall architecture
+- [Artifact Lifecycle](artifact-lifecycle.md) — When each artifact is created
+- [Reference Flow](reference-flow.md) — Full EV charging walkthrough
+- [Protocol: Artifacts](protocol/artifacts.md) — Detailed artifact specs