update readme , improve test examples

Author: Abiorh001

README.md

@@ -48,7 +48,7 @@ sim = await client.simulate(
 - Cross-chain flows depend on the source and destination networks being supported by the configured gateway/CCTP path.
 - Same-chain transfers should not specify a different `destination_chain`.
 - Use `wait_for_completion=True` only when the caller is prepared to block for provider-side polling.
-- For launch usage, verify network support with Circle’s current chain support before relying on a pair in production.
+- Before production use, verify network support with Circle’s current chain support before relying on a pair in production.
 
 ## Result Metadata
 

docs/CCTP_USAGE.md

@@ -78,9 +78,9 @@ Supported deployment modes:
 - Circle Gateway `GatewayWalletBatched` for gasless nanopayment settlement
 - self-hosted OmniClaw exact facilitator, started with `omniclaw facilitator exact`
 
-Thirdweb is a priority external integration path because it provides broad EVM facilitator coverage and gas-sponsored settlement. OmniClaw adds buyer-side policy, route selection, SDK/CLI execution surfaces, and operator visibility.
+Thirdweb is one supported external integration path for teams that want broad EVM facilitator coverage and gas-sponsored settlement. OmniClaw adds buyer-side policy, route selection, SDK and CLI execution surfaces, and payment visibility on top.
 
-OmniClaw added the self-hosted exact facilitator so teams can support networks and proof environments before they are available through their selected hosted facilitator. This is how Arc Testnet is handled: it remains standard x402 `exact` settlement, with OmniClaw providing the network profile, asset metadata, RPC, and facilitator runtime.
+The self-hosted exact facilitator exists so teams can support networks and deployments before they are available through a hosted provider. Arc Testnet is the clearest example: it remains standard x402 `exact` settlement, with OmniClaw providing the network profile, asset metadata, RPC, and facilitator runtime.
 
 See [facilitators.md](facilitators.md) for deployment details.
 
@@ -116,10 +116,10 @@ The ledger in [ledger/](../src/omniclaw/ledger) tracks payment records and statu
 
 Typical use cases:
 
-- internal observability
+- payment observability
 - transaction lookup
 - reconciliation
-- launch debugging
+- operational debugging
 
 ### Payment Intents
 

docs/FEATURES.md

@@ -53,9 +53,9 @@ OmniClaw is facilitator-agnostic. Production deployments should choose the settl
 - Thirdweb-backed x402 facilitator for managed gas-sponsored exact settlement across broad EVM coverage
 - Circle Gateway `GatewayWalletBatched` for gasless batched nanopayments
 - external standard x402 facilitator where the seller already uses one
-- self-hosted OmniClaw exact facilitator only when local proof, custom network support, or enterprise self-hosting is required
+- self-hosted OmniClaw exact facilitator when local proof, custom network support, or enterprise self-hosting is required
 
-Do not run a self-hosted facilitator by default if a managed facilitator already supports the target flow. The self-hosted path is operational infrastructure, not the primary product wedge.
+Use a self-hosted facilitator when it fits the network and operational model. Use a managed facilitator when it already cleanly supports the target flow.
 
 Before production traffic, validate the exact seller path with:
 

docs/PRODUCTION_HARDENING.md

@@ -11,8 +11,8 @@ Use this index to choose the right integration path.
 | Agent buyer | [Agent Getting Started](agent-getting-started.md) | An agent that pays through `omniclaw-cli` |
 | Python buyer | [Developer Guide](developer-guide.md) | A backend service that pays programmatically |
 | Vendor / enterprise seller | [Developer Guide](developer-guide.md) | A FastAPI service with paid endpoints through the SDK |
-| Operator | [Operator CLI](operator-cli.md) | Financial Policy Engine, policies, and facilitators |
-| Release owner | [Production Readiness](production-readiness.md) | Proof checklist and ship status |
+| Infrastructure team | [Operator CLI](operator-cli.md) | Financial Policy Engine, policies, and facilitators |
+| Maintainer | [Production Readiness](production-readiness.md) | Proof checklist and ship status |
 
 ## Buyer Guides
 
@@ -31,7 +31,7 @@ Use this index to choose the right integration path.
 | [B2B SDK Integration](../examples/b2b-sdk-integration/README.md) | Enterprise SDK deployment with Circle, Thirdweb, or self-hosted exact |
 | [Vendor Integration](../examples/vendor-integration/README.md) | Production-style vendor API integration |
 | [Business Compute](../examples/business-compute/README.md) | Payment-gated compute service |
-| [CLI Reference](cli-reference.md) | Agent-owned local service flow with `omniclaw-cli serve` |
+| [CLI Reference](cli-reference.md) | Agent-facing paid service flow with `omniclaw-cli serve` |
 
 ## Machine Payment Examples
 
@@ -45,6 +45,29 @@ Use this index to choose the right integration path.
 | [Thirdweb HTTP Facilitator](../examples/thirdweb-http-facilitator/README.md) | Thirdweb HTTP facilitator integration |
 | [Arc Marketplace Showcase](../examples/arc-marketplace-showcase/README.md) | Visual vendor kiosk with Arc Testnet x402 exact settlement |
 
+## Arc Testnet Quickstart
+
+Run the full Arc marketplace showcase with Docker-reachable service IPs:
+
+```bash
+bash scripts/start_arc_marketplace_showcase_docker.sh
+```
+
+The buyer key must hold Arc Testnet USDC for the selected paid product, and the seller/facilitator key must hold Arc Testnet gas. The launcher prints balances, product URLs, the exact OmniClaw config, and a lower-cost `$0.10` proof endpoint when the buyer wallet is not funded for the `$0.25` product.
+
+The showcase UI also has a built-in mini buyer agent, so the full demo can run directly from the browser. The kiosk backend proxies inspect/pay actions into the buyer Financial Policy Engine while keeping the policy token server-side.
+
+Defaults:
+
+| Service | URL |
+| --- | --- |
+| Browser UI | `http://127.0.0.1:8020` |
+| Vendor kiosk | `http://172.18.0.51:8020` |
+| Buyer policy engine | `http://172.18.0.52:8080` |
+| Exact facilitator | `http://172.18.0.50:4022` |
+
+For setup details and ArcLens submission notes, see [Arc Marketplace Showcase](../examples/arc-marketplace-showcase/README.md).
+
 ## Operator and Production Docs
 
 | Document | Covers |

docs/README.md

@@ -8,9 +8,9 @@ In that system:
 - the owner runs the **Financial Policy Engine**
 - the agent uses `omniclaw-cli` as the **zero-trust execution layer**
 - buyers pay with `omniclaw-cli pay`
-- agents can expose temporary local paid services with `omniclaw-cli serve`
+- agents can expose paid services for other agents or automation with `omniclaw-cli serve`
 
-For vendor, SaaS, or enterprise APIs, use the Python SDK seller middleware instead of `omniclaw-cli serve`. See the [Developer Guide](developer-guide.md).
+For vendor, SaaS, or enterprise APIs embedded directly in an application, use the Python SDK seller middleware instead of `omniclaw-cli serve`. See the [Developer Guide](developer-guide.md).
 
 ---
 
@@ -218,7 +218,7 @@ omniclaw-cli serve \
 
 This opens `http://localhost:8000/api/data` that requires a USDC payment to execute `my_service.py` and return its output.
 
-> **Web developer or vendor:** For real API or SaaS products, use the Python SDK inside your FastAPI application instead of `omniclaw-cli serve`. See the [Developer Guide](developer-guide.md).
+> **Web developer or vendor:** If the paid route lives inside your application, use the Python SDK inside your FastAPI application instead of `omniclaw-cli serve`. Use `serve` when the seller surface itself is agent-run. See the [Developer Guide](developer-guide.md).
 
 ---
 

docs/agent-getting-started.md

@@ -19,7 +19,7 @@ That full system is larger than the CLI alone:
 It is the same CLI for agent-side economic execution:
 
 - buyer side: `omniclaw-cli pay`
-- temporary/local seller side: `omniclaw-cli serve`
+- seller side for agent-run paid endpoints: `omniclaw-cli serve`
 
 Vendor and enterprise seller APIs should use the Python SDK with `client.sell(...)`.
 

docs/agent-skills.md

@@ -1,39 +1,39 @@
 # ERC-8004 Trust Notes
 
-This file is a historical design note for OmniClaw's trust-layer direction. It is not the canonical API reference and should not be treated as a precise description of the current Financial Policy Engine implementation.
+This document explains how ERC-8004 concepts show up in OmniClaw today.
 
-Use these docs for the current product surface instead:
+It is a trust-layer overview, not the canonical SDK or API reference. For the main product surface, use:
 
 - [README](../README.md)
-- [Developer Guide (SDK)](developer-guide.md)
+- [Developer Guide](developer-guide.md)
 - [API Reference](API_REFERENCE.md)
 - [Architecture and Features](FEATURES.md)
 
-## Current Reality
+## How OmniClaw Uses ERC-8004
 
-OmniClaw already exposes a trust layer through the Financial Policy Engine:
+OmniClaw exposes trust evaluation through the Financial Policy Engine:
 
 - trust checks can run during `pay()` and `simulate()`
 - trust behavior is controlled by `check_trust`
 - explicit trust checks require a real `OMNICLAW_RPC_URL`
 - trust evaluation can approve, hold, or block payment execution
 
-## What This Note Represents
+## What The Trust Layer Covers
 
-The earlier internal design work explored:
+The trust system is built around:
 
 - ERC-8004 identity lookup
 - reputation scoring and weighted trust signals
 - policy-based approval, hold, and block behavior
 - trust-aware payment execution
 - auditability of trust decisions
 
-Those themes still matter, but the exact content of the original internal draft no longer maps cleanly to the current codebase.
+## Practical Guidance
 
-## Recommendation
+Treat this file as conceptual background.
 
-If this repo keeps evolving quickly, treat trust docs the same way as the rest of the Financial Policy Engine docs:
+Use:
 
-- keep implementation details in code and tests
-- keep user-facing behavior in the API reference and usage guide
-- keep speculative product thinking in the roadmap, not in protocol documentation
+- the SDK and API docs for integration details
+- the code and tests for implementation behavior
+- the roadmap for future trust-layer expansion

docs/erc_804_spec.md

@@ -48,7 +48,7 @@ OmniClaw's product responsibility:
 - enforce buyer policy before money moves
 - choose a fundable route
 - sign only the allowed action
-- preserve logs, limits, and operator visibility
+- preserve logs, limits, and payment visibility
 
 That means a seller can use managed facilitator coverage, while the buyer still uses OmniClaw as the policy-controlled execution layer.
 
@@ -120,6 +120,7 @@ Current route priority:
 - use `exact` when the seller supports standard x402 exact settlement
 - if the seller supports both and Gateway is not ready, use `exact`
 - if no supported route is available, fail clearly before spending
+- for direct exact payments, inspect checks the buyer's direct-wallet token balance when the selected EVM network and RPC are known
 
 ## Self-Host An Exact Facilitator
 
@@ -298,14 +299,74 @@ So the operational requirement for an already configured profile is only:
 
 That is a deployment requirement, not a missing architecture requirement.
 
+For Arc Testnet, the buyer key must hold Arc Testnet USDC. The seller/facilitator key must hold Arc Testnet gas because it submits the x402 exact settlement transaction to the USDC contract.
+
+To run only the Arc self-hosted exact facilitator:
+
+```bash
+export OMNICLAW_X402_FACILITATOR_PRIVATE_KEY="0xFacilitatorKeyWithArcGas"
+bash scripts/start_arc_exact_facilitator.sh
+```
+
+Equivalent installed CLI:
+
+```bash
+omniclaw facilitator exact \
+  --network-profile ARC-TESTNET \
+  --network eip155:5042002 \
+  --rpc-url https://rpc.testnet.arc.network \
+  --port 4022
+```
+
+The facilitator exposes:
+
+| Endpoint | Purpose |
+| --- | --- |
+| `GET /supported` | Advertise supported x402 schemes and networks |
+| `POST /verify` | Verify a signed x402 payment payload |
+| `POST /settle` | Submit settlement on Arc Testnet |
+
 For a visual Arc vendor demo, use the Arc marketplace showcase:
 
 ```bash
-bash scripts/start_arc_marketplace_showcase.sh
+bash scripts/start_arc_marketplace_showcase_docker.sh
 ```
 
 Runbook: [../examples/arc-marketplace-showcase/README.md](../examples/arc-marketplace-showcase/README.md).
 
+The showcase includes a browser mini buyer agent. It calls the kiosk backend, and the kiosk backend calls the buyer Financial Policy Engine using `ARC_MARKETPLACE_BUYER_ENGINE_URL` and `ARC_MARKETPLACE_BUYER_TOKEN`. This keeps the browser flow simple while the Financial Policy Engine remains the payment authority boundary.
+
+The Docker launcher starts:
+
+| Service | URL |
+| --- | --- |
+| Browser UI | `http://127.0.0.1:8020` |
+| Vendor kiosk | `http://172.18.0.51:8020` |
+| Buyer policy engine | `http://172.18.0.52:8080` |
+| Exact facilitator | `http://172.18.0.50:4022` |
+
+It also prints the buyer Arc USDC balance, seller Arc gas balance, and the paid product URLs:
+
+| Product | Price | URL |
+| --- | --- | --- |
+| Prime Market Scan | `$0.25` | `http://172.18.0.51:8020/buy/prime-market-scan` |
+| Risk Oracle Brief | `$0.15` | `http://172.18.0.51:8020/buy/risk-oracle-brief` |
+| Settlement Receipt Kit | `$0.10` | `http://172.18.0.51:8020/buy/settlement-receipt-kit` |
+
+For ecosystem forms that require a contract address, use the Arc Testnet USDC contract used by x402 exact settlement:
+
+```text
+0x3600000000000000000000000000000000000000
+```
+
+OmniClaw does not require a custom application contract for this flow. The settlement transaction calls `transferWithAuthorization` on Arc Testnet USDC.
+
+Latest public proof transaction:
+
+```text
+https://testnet.arcscan.app/tx/0xd40dc800a54bee4ff80da4709e65cfd3d0346eb1995ebc34fba433a6306b9219
+```
+
 ## External Facilitators
 
 External facilitators remain first-class. If a seller advertises an `exact` payment requirement using another facilitator, OmniClaw's buyer flow can still pay through the standard x402 SDK path as long as:

docs/facilitators.md

@@ -3,7 +3,7 @@ name: omniclaw
 description: >
   Use this skill whenever an agent needs to pay for an x402 URL, transfer USDC
   to an address, inspect OmniClaw balances or ledger entries, or expose a
-  temporary agent-owned paid service with omniclaw-cli serve. OmniClaw is the
+  paid endpoint for other agents or automation with omniclaw-cli serve. OmniClaw is the
   Economic Execution and Control Layer for Agentic Systems. The CLI is the
   zero-trust execution layer for agents. Use this skill for the CLI execution
   path only, not for vendor SDK integration, owner setup, policy editing, wallet
@@ -31,7 +31,7 @@ Use `omniclaw-cli` only when the task is directly about one of these actions:
 - transfer USDC to an address
 - inspect wallet, Gateway, or Circle balances
 - inspect transaction history
-- expose a temporary agent-owned paid endpoint with `serve`
+- expose a paid endpoint for other agents or automation with `serve`
 
 Do not use this skill for:
 
@@ -55,7 +55,7 @@ This skill is specifically about the CLI execution surface.
 The same CLI has two agent-side economic roles:
 
 - buyer role: `omniclaw-cli pay`
-- temporary/local seller role: `omniclaw-cli serve`
+- seller role for agent-run paid endpoints: `omniclaw-cli serve`
 
 Vendor and enterprise seller APIs should use the Python SDK with `client.sell(...)`, not this CLI skill.
 
@@ -105,7 +105,7 @@ Do not invent or search for them yourself.
 1. Use `omniclaw-cli pay --recipient <0xaddress> --amount <usdc>`.
 2. Always include `--purpose`.
 
-### For agent-owned local seller tasks
+### For agent-run seller tasks
 
 1. Inspect current state with `balance-detail`.
 2. Start the paid endpoint with `omniclaw-cli serve`.