Prepare OmniClaw SDK and facilitator release

.dockerignore

@@ -7,7 +7,8 @@ logs
 tmp
 .runtime
 output/doc
-docs/internal
+internal
+.agents
 dist
 build
 *.egg-info

.env.example

@@ -0,0 +1,130 @@
+# OmniClaw environment template
+#
+# Copy to `.env` for local development. Never commit real secrets.
+# Pick the sections that match your deployment role.
+
+# =============================================================================
+# Shared Network Configuration
+# =============================================================================
+
+# Supported examples: ETH-SEPOLIA, BASE-SEPOLIA, ARC-TESTNET
+OMNICLAW_NETWORK=BASE-SEPOLIA
+OMNICLAW_RPC_URL=https://sepolia.base.org
+
+# development, test, or production
+OMNICLAW_ENV=development
+
+# Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL
+OMNICLAW_LOG_LEVEL=INFO
+
+# =============================================================================
+# Buyer / Seller Signing Key
+# =============================================================================
+
+# Private key used by the SDK or Financial Policy Engine for allowed actions.
+# In production, use restricted infrastructure and secret management.
+OMNICLAW_PRIVATE_KEY=0x...
+
+# =============================================================================
+# Financial Policy Engine
+# =============================================================================
+
+# Use this when an agent, worker, or partner integration should not hold raw key
+# authority. The policy engine exposes the controlled payment API.
+OMNICLAW_AGENT_TOKEN=replace-with-agent-token
+OMNICLAW_AGENT_POLICY_PATH=./policy.json
+OMNICLAW_OWNER_TOKEN=replace-with-owner-token
+
+# Policy hot reload interval in seconds. Use a larger value or disable reload in
+# production if policies are deployed immutably.
+OMNICLAW_POLICY_RELOAD_INTERVAL=5
+
+# Optional persistence backend.
+# Values: memory, redis
+OMNICLAW_STORAGE_BACKEND=memory
+OMNICLAW_REDIS_URL=redis://localhost:6379/0
+
+# =============================================================================
+# Agent CLI Runtime
+# =============================================================================
+
+# Used by `omniclaw-cli` when acting as an agent execution layer.
+OMNICLAW_SERVER_URL=http://127.0.0.1:8080
+OMNICLAW_TOKEN=replace-with-agent-token
+
+# Optional human-readable CLI output. Default output is agent-friendly JSON.
+OMNICLAW_CLI_HUMAN=0
+
+# =============================================================================
+# Circle Gateway / Nanopayments
+# =============================================================================
+
+# Required for Circle Gateway nanopayments, Gateway balance, and Circle-backed
+# wallet operations.
+CIRCLE_API_KEY=replace-with-circle-api-key
+
+# Entity secret for Circle wallet encryption.
+# If your Circle account/API key already has an Entity Secret, set it here.
+# Circle only allows one active Entity Secret per account/API key, so OmniClaw
+# only auto-generates/registers a new one when no existing secret is provided or
+# found in the managed local credential store.
+ENTITY_SECRET=
+
+OMNICLAW_NANOPAYMENTS_ENABLED=true
+OMNICLAW_NANOPAYMENTS_ENV=testnet
+OMNICLAW_NANOPAYMENTS_AUTO_TOPUP=false
+OMNICLAW_NANOPAYMENTS_TOPUP_THRESHOLD=1.00
+OMNICLAW_NANOPAYMENTS_TOPUP_AMOUNT=10.00
+OMNICLAW_NANOPAYMENTS_MICRO_THRESHOLD=1.00
+
+# Optional Gateway contract override for seller GatewayWalletBatched metadata.
+CIRCLE_GATEWAY_CONTRACT=
+
+# =============================================================================
+# Vendor / Enterprise SDK Seller
+# =============================================================================
+
+# Vendor wallet that receives seller payments.
+SELLER_ADDRESS=0x...
+
+# Default Circle seller path:
+#   payment=client.sell("$0.25", seller_address=os.environ["SELLER_ADDRESS"])
+
+# Thirdweb managed x402 seller path:
+#   payment=client.sell("$0.25", seller_address=os.environ["SELLER_ADDRESS"], facilitator="thirdweb")
+THIRDWEB_SECRET_KEY=
+THIRDWEB_SERVER_WALLET_ADDRESS=
+THIRDWEB_X402_NETWORK=base-sepolia
+
+# OmniClaw self-hosted exact seller path:
+#   payment=client.sell("$0.25", seller_address=os.environ["SELLER_ADDRESS"], facilitator="omniclaw")
+OMNICLAW_X402_SELF_HOSTED_FACILITATOR_URL=http://127.0.0.1:4022
+OMNICLAW_X402_EXACT_NETWORK_PROFILE=ARC-TESTNET
+
+# =============================================================================
+# Self-Hosted Exact Facilitator
+# =============================================================================
+
+# Run with:
+#   omniclaw facilitator exact --network-profile ARC-TESTNET --port 4022
+OMNICLAW_X402_FACILITATOR_PRIVATE_KEY=0x...
+OMNICLAW_X402_FACILITATOR_NETWORK_PROFILE=ARC-TESTNET
+OMNICLAW_X402_FACILITATOR_RPC_URL=https://rpc.testnet.arc.network
+OMNICLAW_X402_FACILITATOR_NETWORKS=eip155:5042002
+OMNICLAW_X402_FACILITATOR_HOST=0.0.0.0
+OMNICLAW_X402_FACILITATOR_PORT=4022
+
+# =============================================================================
+# Production Hardening
+# =============================================================================
+
+# Required for production seller replay protection.
+OMNICLAW_SELLER_NONCE_REDIS_URL=redis://localhost:6379/1
+OMNICLAW_SELLER_REQUIRE_DISTRIBUTED_NONCE=true
+
+# Strict settlement should remain enabled for production payment gates.
+OMNICLAW_STRICT_SETTLEMENT=true
+
+# Webhook verification and deduplication.
+OMNICLAW_WEBHOOK_VERIFICATION_KEY=
+OMNICLAW_WEBHOOK_DEDUP_DB_PATH=/var/lib/omniclaw/webhook_dedup.sqlite3

.gitignore

@@ -3,6 +3,7 @@
 
 .env
 .env.*
+!.env.example
 .env.local
 *.pem
 *.key
@@ -46,8 +47,10 @@ tmp/
 .runtime/
 output/doc/
 
-# Internal docs / GTM materials
-docs/internal/
+# Private operating workspace
+# Keep the root internal workspace out of git.
+internal/
+.agents/
 
 # OS
 Thumbs.db

CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to OmniClaw are documented here.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- Added the owner/operator `omniclaw facilitator exact` command for self-hosted x402 exact settlement.
+- Added public facilitator documentation covering Circle Gateway, external facilitators, and OmniClaw self-hosted exact settlement.
+- Added Arc Testnet exact-settlement support documentation using CAIP-2 `eip155:5042002`.
+
+### Changed
+- Moved the owner/operator CLI entrypoint to `omniclaw.admin_cli:main` so it no longer conflicts with the `omniclaw.cli` agent CLI package.
+- Updated release artifact verification for the new admin CLI module and package layout.
+
 ## [0.0.5] - 2026-04-04
 
 ### Fixed