update skills, fix bug

.agents/skills/omniclaw-cli/scripts/generate_cli_reference.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[4]
+SKILL_DIR = Path(__file__).resolve().parents[1]
+SKILL_REF = SKILL_DIR / "references" / "cli-reference.md"
+HUMAN_REF = ROOT / "docs" / "cli-reference.md"
+
+COMMANDS = [
+    ("omniclaw-cli --help", ["omniclaw-cli", "--help"]),
+    ("omniclaw-cli configure --help", ["omniclaw-cli", "configure", "--help"]),
+    ("omniclaw-cli status --help", ["omniclaw-cli", "status", "--help"]),
+    ("omniclaw-cli ping --help", ["omniclaw-cli", "ping", "--help"]),
+    ("omniclaw-cli address --help", ["omniclaw-cli", "address", "--help"]),
+    ("omniclaw-cli balance --help", ["omniclaw-cli", "balance", "--help"]),
+    ("omniclaw-cli balance-detail --help", ["omniclaw-cli", "balance-detail", "--help"]),
+    ("omniclaw-cli can-pay --help", ["omniclaw-cli", "can-pay", "--help"]),
+    ("omniclaw-cli simulate --help", ["omniclaw-cli", "simulate", "--help"]),
+    ("omniclaw-cli pay --help", ["omniclaw-cli", "pay", "--help"]),
+    ("omniclaw-cli deposit --help", ["omniclaw-cli", "deposit", "--help"]),
+    ("omniclaw-cli withdraw --help", ["omniclaw-cli", "withdraw", "--help"]),
+    ("omniclaw-cli withdraw-trustless --help", ["omniclaw-cli", "withdraw-trustless", "--help"]),
+    ("omniclaw-cli withdraw-trustless-complete --help", ["omniclaw-cli", "withdraw-trustless-complete", "--help"]),
+    ("omniclaw-cli serve --help", ["omniclaw-cli", "serve", "--help"]),
+    ("omniclaw-cli create-intent --help", ["omniclaw-cli", "create-intent", "--help"]),
+    ("omniclaw-cli confirm-intent --help", ["omniclaw-cli", "confirm-intent", "--help"]),
+    ("omniclaw-cli get-intent --help", ["omniclaw-cli", "get-intent", "--help"]),
+    ("omniclaw-cli cancel-intent --help", ["omniclaw-cli", "cancel-intent", "--help"]),
+    ("omniclaw-cli ledger --help", ["omniclaw-cli", "ledger", "--help"]),
+    ("omniclaw-cli list-tx --help", ["omniclaw-cli", "list-tx", "--help"]),
+    ("omniclaw-cli confirmations --help", ["omniclaw-cli", "confirmations", "--help"]),
+    ("omniclaw-cli confirmations get --help", ["omniclaw-cli", "confirmations", "get", "--help"]),
+    ("omniclaw-cli confirmations approve --help", ["omniclaw-cli", "confirmations", "approve", "--help"]),
+    ("omniclaw-cli confirmations deny --help", ["omniclaw-cli", "confirmations", "deny", "--help"]),
+]
+
+FALLBACK_OUTPUTS = {
+    "omniclaw-cli balance --help": """\
+Usage: omniclaw-cli balance [OPTIONS]
+
+Get wallet balance.
+
+Options:
+  --help  Show this message and exit.
+""",
+    "omniclaw-cli balance-detail --help": """\
+Usage: omniclaw-cli balance-detail [OPTIONS]
+
+Get detailed balance including Gateway and Circle wallet.
+
+Options:
+  --help  Show this message and exit.
+""",
+}
+
+TIMEOUT_SECONDS = 25
+
+HEADER = """# OmniClaw CLI Reference
+
+This file is generated from the live `omniclaw-cli --help` surface.
+Do not hand-edit command schemas here; regenerate instead.
+
+Generator:
+
+```bash
+python3 .agents/skills/omniclaw-cli/scripts/generate_cli_reference.py
+```
+
+## Usage Notes
+
+- same CLI, two roles: buyer uses `pay`, seller uses `serve`
+- use `can-pay` before a new recipient when policy allow/deny matters
+- use `balance-detail` when Gateway state matters
+- use `--idempotency-key` for job-based payments
+- for x402 URLs, `--amount` can be omitted because the payment requirements come from the seller endpoint
+- `serve` binds to `0.0.0.0` even if the banner prints `localhost`
+
+## Example Flows
+
+Buyer paying an x402 endpoint:
+
+```bash
+omniclaw-cli can-pay --recipient http://seller-host:8000/api/data
+omniclaw-cli pay --recipient http://seller-host:8000/api/data --idempotency-key job-123
+```
+
+Buyer paying a direct address:
+
+```bash
+omniclaw-cli pay \\
+  --recipient 0xRecipientAddress \\
+  --amount 5.00 \\
+  --purpose "service payment" \\
+  --idempotency-key job-123
+```
+
+Seller exposing a paid endpoint:
+
+```bash
+omniclaw-cli serve \\
+  --price 0.01 \\
+  --endpoint /api/data \\
+  --exec "python app.py" \\
+  --port 8000
+```
+
+## Live Help Output
+"""
+
+
+def run_help(title: str, args: list[str]) -> str:
+    try:
+        proc = subprocess.run(
+            args,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            timeout=TIMEOUT_SECONDS,
+            check=False,
+        )
+    except subprocess.TimeoutExpired:
+        fallback = FALLBACK_OUTPUTS.get(title)
+        if fallback:
+            return f"{fallback.rstrip()}\n\n[live help timed out after {TIMEOUT_SECONDS}s; schema filled from source]"
+        return f"[help command timed out after {TIMEOUT_SECONDS}s]"
+
+    output = (proc.stdout or "").rstrip()
+    if proc.returncode == 0:
+        return output
+
+    if output:
+        return f"{output}\n\n[exit code: {proc.returncode}]"
+    return f"[help command failed with exit code {proc.returncode}]"
+
+
+sections: list[str] = [HEADER.rstrip()]
+for title, args in COMMANDS:
+    output = run_help(title, args)
+    sections.append(f"### `{title}`\n\n```text\n{output}\n```")
+
+content = "\n\n".join(sections) + "\n"
+SKILL_REF.write_text(content)
+HUMAN_REF.write_text(content)
+print(f"wrote {SKILL_REF}")
+print(f"wrote {HUMAN_REF}")

.agents/skills/omniclaw-cli/scripts/generate_cli_reference.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../.." && pwd)"
+cd "$ROOT_DIR"
+python3 .agents/skills/omniclaw-cli/scripts/generate_cli_reference.py

README.md

@@ -18,7 +18,7 @@ Where Stripe helps merchants accept human payments, OmniClaw governs autonomous
 
 **OmniClaw solves this** by separating:
 1. **Financial Policy Engine** (owner runs) - holds private keys, enforces policy
-2. **Execution Layer** (agent uses) - thin CLI that only does what policy allows
+2. **Zero-Trust Execution Layer** (agent uses) - constrained CLI that only does what policy allows
 
 The agent **never touches the private key**. It only talks to the CLI. The owner decides what the agent can do via policy.json.
 
@@ -36,7 +36,7 @@ The agent **never touches the private key**. It only talks to the CLI. The owner
 │                                                                     │
 │   ┌─────────────────────────────┐                ┌─────────────────────┐   │
 │   │  Financial Policy Engine   │                │     OmniClaw CLI   │   │
-│   │  (uvicorn server)          │◄──────────────►│  (thin client)     │   │
+│   │  (uvicorn server)          │◄──────────────►│ (zero-trust exec)  │   │
 │   │                            │   HTTPS        │                    │   │
 │   │  - Holds private key       │                │  - pay             │   │
 │   │  - Enforces policy         │                │  - deposit         │   │
@@ -60,7 +60,7 @@ The agent **never touches the private key**. It only talks to the CLI. The owner
 | Component | Who Runs It | What It Does |
 |-----------|-------------|--------------|
 | **Financial Policy Engine** | Owner/human | Holds private key, enforces policy, signs transactions |
-| **CLI** (agent uses) | Agent | Thin client - sends requests, gets responses. Cannot bypass policy |
+| **CLI** (agent uses) | Agent | Zero-trust execution layer - constrained command surface, cannot bypass policy |
 
 ---
 
@@ -244,7 +244,7 @@ This opens `http://localhost:8000/api/data` that requires USDC payment to access
 
 | Command | Description | Example |
 |---------|-------------|---------|
-| `configure` | Set server URL, token, wallet | `configure --server-url http://localhost:8080 --token mytoken --wallet primary` |
+| `configure` | Set Financial Policy Engine URL, token, wallet | `configure --server-url http://localhost:8080 --token mytoken --wallet primary` |
 | `address` | Get wallet address | `address` |
 | `balance` | Get wallet balance | `balance` |
 | `balance-detail` | Detailed balance (EOA, Gateway, Circle) | `balance-detail` |
@@ -305,7 +305,7 @@ For full policy options, see **[docs/POLICY_REFERENCE.md](docs/POLICY_REFERENCE.
 | `OMNICLAW_ENV` | No | Set to "production" for mainnet |
 | `OMNICLAW_RPC_URL` | No | RPC endpoint for on-chain ops |
 | `CIRCLE_API_KEY` | Yes | Circle API key |
-| `OMNICLAW_SERVER_URL` | No | CLI server URL (for configure) |
+| `OMNICLAW_SERVER_URL` | No | Financial Policy Engine URL for the zero-trust CLI |
 
 ---
 

docker-compose.agent.yml

@@ -19,7 +19,7 @@ services:
     environment:
       - OMNICLAW_REDIS_URL=redis://redis:6379/0
       - OMNICLAW_AGENT_POLICY_PATH=/config/policy.json
-      - OMNICLAW_AGENT_TOKEN=seller-agent-token
+      - OMNICLAW_AGENT_TOKEN=buyer-agent-token
       - OMNICLAW_LOG_LEVEL=INFO
       - OMNICLAW_POLICY_RELOAD_INTERVAL=0
       - OMNICLAW_NANOPAYMENTS_ENABLED=true

docs/FOUNDATION_DEMO.md

@@ -0,0 +1,70 @@
+# Foundation Demo
+
+Official dual-sided OmniClaw demo flow:
+
+1. Buyer policy blocks a malicious URL instantly.
+2. Seller exposes a paid API behind `omniclaw-cli serve`.
+3. Buyer checks budget, triggers approval, and pays with `omniclaw-cli pay`.
+4. Script waits for Circle Gateway batch settlement to update buyer/seller Gateway contract balances.
+
+## Default Run
+
+```bash
+scripts/demo_foundation_showcase.sh
+```
+
+Defaults:
+
+- network: `ETH-SEPOLIA`
+- buyer Financial Policy Engine: `http://localhost:9190`
+- seller Financial Policy Engine: `http://localhost:9191`
+- seller paid endpoint: `http://localhost:9291/api/data`
+
+## Base Mode
+
+```bash
+scripts/demo_foundation_showcase.sh --base
+```
+
+Equivalent explicit form:
+
+```bash
+scripts/demo_foundation_showcase.sh --network BASE-SEPOLIA
+```
+
+If the current wallets are not funded on Base Sepolia, the script now stops early with a clear funding hint instead of failing late in the flow.
+
+## Ethereum Explicit
+
+```bash
+scripts/demo_foundation_showcase.sh --eth
+```
+
+## Recording Layout
+
+One-command tmux layout:
+
+```bash
+scripts/demo_foundation_tmux.sh
+```
+
+It opens:
+
+- top-left: buyer terminal using `omniclaw-cli pay`
+- top-right: seller terminal using `omniclaw-cli serve`
+- bottom-left: live Circle Gateway settlement monitor
+- bottom-right: stage log with the demo narrative
+
+There is also a hidden `infra` tmux window running the two OmniClaw Financial Policy Engine processes.
+
+Base version:
+
+```bash
+scripts/demo_foundation_tmux.sh --base
+```
+
+## Notes
+
+- The payment step remains `omniclaw-cli pay`.
+- The budget simulation step uses the Financial Policy Engine API because `omniclaw-cli simulate` is still intermittently unstable in this environment.
+- Logs are written under `logs/foundation_demo_*` or `logs/foundation_demo_tmux_*`.

docs/TWO_SIDED_DEMO.md

@@ -0,0 +1,78 @@
+# Two-Sided OmniClaw CLI Demo
+
+This demo shows both sides of the economy:
+- **Seller** exposes a paid x402 URL.
+- **Buyer** pays that URL through OmniClaw + Circle nanopayments.
+
+It uses:
+- `examples/agent/seller/policy.json`
+- `examples/agent/buyer/policy.json`
+- `scripts/demo_two_sided.sh`
+
+Note: the script copies policy files into per-run `logs/demo_<timestamp>/...runtime.json`
+so your checked-in policy files are not modified during the demo.
+
+## 1. Preflight
+
+```bash
+./scripts/demo_two_sided.sh --check-only
+```
+
+This validates required env keys from `.env` without printing secrets.
+
+## 2. ETH Sepolia Demo (recommended first)
+
+If your default ports are already used:
+
+```bash
+./scripts/demo_two_sided.sh \
+  --seller-cp-port 8181 \
+  --buyer-cp-port 8182 \
+  --seller-gate-port 9101
+```
+
+Optional full flow attempt (pay from buyer to seller URL):
+
+```bash
+./scripts/demo_two_sided.sh \
+  --seller-cp-port 8181 \
+  --buyer-cp-port 8182 \
+  --seller-gate-port 9101 \
+  --run-payment
+```
+
+Keep services running for live walkthrough:
+
+```bash
+./scripts/demo_two_sided.sh \
+  --seller-cp-port 8181 \
+  --buyer-cp-port 8182 \
+  --seller-gate-port 9101 \
+  --hold
+```
+
+## 3. Base Sepolia Variant
+
+```bash
+./scripts/demo_two_sided.sh \
+  --network BASE-SEPOLIA \
+  --rpc-url https://base-sepolia-rpc.publicnode.com \
+  --seller-cp-port 8181 \
+  --buyer-cp-port 8182 \
+  --seller-gate-port 9101
+```
+
+## 4. Logs
+
+Each run writes logs under:
+
+```text
+logs/demo_<timestamp>/
+```
+
+Files include:
+- `seller-control-plane.log` - seller Financial Policy Engine log
+- `buyer-control-plane.log` - buyer Financial Policy Engine log
+- `seller-gateway.log`
+- `seller-cli.log`
+- `buyer-cli.log`

docs/agent-getting-started.md

@@ -2,6 +2,14 @@
 
 This guide walks you through setting up an OmniClaw agent for both buying and selling.
 
+OmniClaw is the **Economic Execution and Control Layer for Agentic Systems**.
+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`
+- sellers earn with `omniclaw-cli serve`
+
 ---
 
 ## Prerequisites
@@ -178,6 +186,12 @@ omniclaw-cli serve \
 
 This opens `http://localhost:8000/api/data` that requires USDC payment to access.
 
+This is the seller side of the same OmniClaw economy.
+The same CLI powers both sides:
+
+- buyer: `omniclaw-cli pay`
+- seller: `omniclaw-cli serve`
+
 ---
 
 ## Quick Reference