ape-claw 0.1.0

package/docs/THE_POD_RUNNER.md

@@ -0,0 +1,198 @@
+# THE POD Runner
+
+THE POD is the deployment harness for long-running autonomous agents.
+
+In v2 it is intentionally:
+
+- strict opt-in
+- safe-by-default (dry-run)
+- file-backed (audit-friendly)
+
+## Pod workspace scaffold
+
+Create a workspace harness:
+
+```bash
+ape-claw pod init --dir ./pod-workspace --json
+```
+
+This creates a set of persistent operating docs + memory files:
+
+- `AGENTS.md`, `SOUL.md`, `USER.md`, `IDENTITY.md`, `TOOLS.md`, `HEARTBEAT.md`, `MEMORY.md`
+- `memory/active-tasks.md`, `memory/lessons.md`, `memory/self-review.md`
+
+## Otherside runner loop
+
+The runner is `pod/run_agent.py`.
+
+It:
+
+- reads the newest image in a screenshot buffer directory
+- (optional) describes it via VLM backend (`stub` or `claude_cli`)
+- parses and plans actions
+- writes:
+  - `state/last_state.json`
+  - `journal/YYYY-MM-DD.md`
+  - `executions/*.json` (always; includes the executor note)
+- emits a deterministic recovery-plan stub when stuck (log-only)
+  - recovery plans in-memory for recover actions (log-only stub steps)
+
+### Run (dry-run)
+
+```bash
+python3 pod/run_agent.py \
+  --enabled \
+  --screenshot-dir "$HOME/pod/screens" \
+  --backend stub \
+  --dry-run
+```
+
+### Kill switch
+
+```bash
+touch "$HOME/pod/STOP"
+```
+
+The runner checks `--stop-file` and exits immediately if it exists.
+
+## Optional: telemetry heartbeat (strict opt-in)
+
+If you want the Pod loop to emit lightweight telemetry to an ApeClaw backend:
+
+```bash
+python3 pod/run_agent.py \
+  --enabled \
+  --screenshot-dir "$HOME/pod/screens" \
+  --backend stub \
+  --dry-run \
+  --telemetry-enabled \
+  --telemetry-url "https://apeclaw.ai" \
+  --telemetry-agent-id "your-agent-id" \
+  --telemetry-agent-token "claw_..."
+```
+
+Emitted event types:
+
+- `pod.heartbeat` (every ~120s by default)
+- `pod.stuck` (one-shot when transitioning into stuck)
+- `pod.sync` (optional low-frequency state sync; disabled by default)
+
+## Optional: onchain receipts (strict opt-in)
+
+If you want a permanent, chain-verifiable audit trail, the Pod can record low-frequency receipts to `ReceiptRegistry` (v2).
+
+This is strict opt-in and best-effort; it should never block the loop.
+
+```bash
+python3 pod/run_agent.py \
+  --enabled \
+  --screenshot-dir "$HOME/pod/screens" \
+  --backend stub \
+  --dry-run \
+  --onchain-receipts-enabled \
+  --onchain-receipts-rpc "http://127.0.0.1:8545" \
+  --onchain-receipts-registry "0x..." \
+  --onchain-receipts-private-key "0x..."
+```
+
+What gets recorded:
+
+- `pod.heartbeat` (at most every `--onchain-receipts-interval-seconds`, default 600s)
+- `pod.stuck` (one-shot on transition into stuck)
+
+Implementation note: this uses `pod/record_receipt.mjs` to write the receipt onchain.
+
+## Optional: ACP bounties (hire + fulfill)
+
+ACP (Agent Commerce Protocol) adds a procurement primitive:
+
+- if the Pod hits a capability gap, it can post a bounty and hire specialists
+- if the Pod has a valuable capability, it can fulfill work for revenue
+
+Docs:
+
+- `/docs?doc=ACP_BOUNTIES.md`
+
+Safety posture:
+
+- treat escrow/job funding as value-moving (strict opt-in, caps, confirmation phrase)
+- when the Pod earns revenue, route payouts into the shared Pod receiver (`PodVault`) and record receipt anchors
+
+## Optional: sync thread (telemetry)
+
+If you want a separate periodic "sync" event (useful for dashboards that want a steady heartbeat even when no actions are happening):
+
+```bash
+python3 pod/run_agent.py \
+  --enabled \
+  --screenshot-dir "$HOME/pod/screens" \
+  --backend stub \
+  --dry-run \
+  --telemetry-enabled \
+  --telemetry-url "https://apeclaw.ai" \
+  --telemetry-agent-id "your-agent-id" \
+  --telemetry-agent-token "claw_..." \
+  --sync-enabled \
+  --sync-interval-seconds 120
+```
+
+## Recovery artifacts (log-only)
+
+When the planner produces a `recover` action, the runner writes a concrete relaunch-flow artifact to disk:
+
+- `recovery/relaunch-<ts>.json`
+- `recovery/relaunch-<ts>.sh`
+
+These are safe by default (echo-only). They exist so you can audit and later upgrade to real input injection without rewriting the loop.
+
+## Runner contract (SkillCard binding)
+
+The `otherside-navigator` SkillCard includes a minimal "runner contract" in its binding:
+
+- entrypoint: `python3 pod/run_agent.py`
+- default paths:
+  - screenshot buffer: `~/pod/screens`
+  - journal: `~/pod/journal`
+  - relationships json: `~/pod/state/relationships.json`
+- browser target (planned): `chrome`
+
+## Safety posture (do not weaken by default)
+
+In v2, real input injection is available but must remain strict opt-in. By default, the runner logs intended actions to disk (dry-run).
+
+When input injection is added later, it must remain:
+
+- strict opt-in
+- kill-switch protected
+- bounded by max runtime
+- auditable (write an execution record per action)
+
+## Optional: real input injection (macOS)
+
+The runner now supports an optional, strict opt-in executor that can actually move your character by sending macOS CGEvent key/mouse events:
+
+- executor: `macos_cgevent`
+- requires: `--allow-system-input`
+- recommended: `--focus-app "Google Chrome"` (or the app running Otherside)
+- requires macOS Accessibility permission for the terminal/Python process
+
+Install prerequisites (on the Pod machine):
+
+```bash
+python3 -m pip install --upgrade pyobjc-framework-Quartz
+```
+
+Example (still strict opt-in; add `--execute` to actually send inputs):
+
+```bash
+python3 pod/run_agent.py \
+  --enabled \
+  --screenshot-dir "$HOME/pod/screens" \
+  --capture-screenshots \
+  --backend stub \
+  --executor macos_cgevent \
+  --allow-system-input \
+  --focus-app "Google Chrome" \
+  --execute
+```
+

package/docs/V1_WORKFLOWS.md

@@ -0,0 +1,108 @@
+# v1 Workflows (NFT + Bridge)
+
+This doc covers the production v1 CLI flows.
+
+## Core idea: policy-gated execution
+
+ApeClaw is designed so that "autonomous" does not mean "unguarded".
+
+Even in `--autonomous` mode, the CLI enforces:
+
+- allowlists (collections, currencies)
+- confirm phrases (when required)
+- simulation-before-execute (when required)
+- daily spend caps
+- replay protection
+
+## NFT buy flow (manual)
+
+1) Quote
+
+```bash
+ape-claw nft quote-buy --collection <slug> --tokenId <id> --maxPrice 100 --currency APE --json
+```
+
+2) Simulate
+
+```bash
+ape-claw nft simulate --quote <quoteId> --json
+```
+
+3) Execute (requires confirm phrase)
+
+```bash
+ape-claw nft buy --quote <quoteId> --execute --confirm "BUY <collection> #<tokenId> <priceApe> APE" --json
+```
+
+Always construct the confirm phrase from the returned quote fields.
+
+## NFT buy flow (autonomous)
+
+```bash
+ape-claw nft buy --quote <quoteId> --execute --autonomous --json
+```
+
+In this mode the CLI:
+
+- runs simulation first (if policy requires it)
+- generates the confirm phrase from quote fields
+- executes only if every policy check passes
+
+## Multi-collection autobuy
+
+Use autobuy when you want the bot to select purchases across many allowlisted collections.
+
+Plan only:
+
+```bash
+ape-claw nft autobuy --count 3 --minPrice 50 --maxPrice 100 --json
+```
+
+Execute autonomously:
+
+```bash
+ape-claw nft autobuy --count 3 --minPrice 50 --maxPrice 100 --execute --autonomous --json
+```
+
+## Bridge flow (Relay)
+
+1) Quote
+
+```bash
+ape-claw bridge quote --from arbitrum --to apechain --token USDC --amount 100 --json
+```
+
+2) Execute (manual confirm or autonomous)
+
+```bash
+ape-claw bridge execute --request <requestId> --execute --confirm "BRIDGE <amount> <token> <from>-><to>" --json
+```
+
+Or:
+
+```bash
+ape-claw bridge execute --request <requestId> --execute --autonomous --json
+```
+
+## Global telemetry (recommended)
+
+To make actions appear on the global dashboard from any machine:
+
+```bash
+export APE_CLAW_TELEMETRY_URL=https://apeclaw.ai
+export APE_CLAW_CHAT_URL=https://apeclaw.ai
+export APE_CLAW_AGENT_ID=my-bot
+export APE_CLAW_AGENT_TOKEN=claw_...
+```
+
+Then open:
+
+- `https://apeclaw.ai/app` (terminal)
+- `https://apeclaw.ai/ui` (direct UI)
+
+## Common mistakes
+
+- **Wrong confirm phrase**: always build it from the quote/request JSON you just received.
+- **No private key for execute**: set `APE_CLAW_PRIVATE_KEY` or `ape-claw auth set --private-key ...`.
+- **Not global**: if you never set `APE_CLAW_TELEMETRY_URL`, events stay local-only.
+

package/docs/V2_ONCHAIN_SKILLS.md

@@ -0,0 +1,157 @@
+# v2 Onchain Skills
+
+v2 introduces onchain primitives so skills can be versioned immutably and referenced without trusting a single backend.
+
+## Contracts (shipped)
+
+- `SkillNFT` (`contracts/SkillNFT.sol`)
+  - one token per skill
+  - optional `parentSkillId` to support forks
+- `SkillRegistry` (`contracts/SkillRegistry.sol`)
+  - append-only versions per skillId
+  - each version stores:
+    - `versionHash` (bytes32)
+    - `contentHash` (bytes32) -- hash of SkillCard JSON
+    - `uri` (string) -- where the SkillCard content lives (file/ipfs/ar/http)
+    - `riskTier` (uint8) -- convention: 1 low, 2 medium, 3 high
+- `IntentRegistry` (`contracts/IntentRegistry.sol`)
+  - minimal create/cancel intent primitive
+- `ReceiptRegistry` (`contracts/ReceiptRegistry.sol`)
+  - append-only receipts keyed by `traceIdHash`
+  - stores `contentHash` + `uri` + `subject` for discoverability filters
+- `PolicyEngine` (`contracts/PolicyEngine.sol`)
+  - minimal onchain pre-check hook (allowlists + value cap)
+- `AgentAccount` (`contracts/AgentAccount.sol`)
+  - minimal execution shell that enforces PolicyEngine and records receipts
+- `PodVault` (`contracts/PodVault.sol`)
+  - revenue split vault for THE POD (native + ERC20)
+  - can be used as the royalty receiver for SkillNFTs (EIP-2981)
+- `SwapModule` (`contracts/SwapModule.sol`)
+  - policy-gated swap call wrapper
+- `BridgeModule` (`contracts/BridgeModule.sol`)
+  - policy-gated bridge call wrapper
+- `NftBuyModule` (`contracts/NftBuyModule.sol`)
+  - policy-gated NFT buy call wrapper
+- `ClawllectorPass` (`contracts/ClawllectorPass.sol`)
+  - signature-gated free mint ERC-721 pass for Clawllectors
+  - freezeable metadata, one mint per address
+
+## Hashing model
+
+The repo uses stable JSON canonicalization in `src/lib/v2-skillcard.mjs`:
+
+- `contentHash = keccak256(stableJsonStringify(skillcard))`
+- `versionHash = keccak256(version_string)`
+
+This ensures the chain references content, not a mutable URL.
+
+## Local devnet
+
+Compile + test:
+
+```bash
+npm run contracts:compile
+npm run contracts:test
+```
+
+Deploy + seed every SkillCard in `skillcards/seed/`:
+
+```bash
+npm run contracts:seed
+```
+
+### URI strategy
+
+By default, the seed script publishes `uri=file://...` for local dev.
+
+To keep it ready for ApeChain deployment, you can override with:
+
+```bash
+export APECLAW_SKILLCARD_URI_BASE="https://example.com/skillcards/seed"
+npm run contracts:seed
+```
+
+Then each seeded SkillCard uses `uri=${BASE}/${filename}`.
+
+## Risk tiers
+
+`riskTier` is an explicit field stored onchain and should be treated as a UI + policy signal:
+
+- `1`: low risk (read-only / non-sensitive)
+- `2`: medium risk (network calls, mild side effects)
+- `3`: high risk (system input, keys, autonomous loops, privileged actions)
+
+The seed script and importer clamp `riskTier` to `0..255` for ABI compatibility.
+
+## Publishing pipeline (devnet)
+
+There are two ways to publish:
+
+1) Seed publish (all `skillcards/seed/*.json`):
+
+```bash
+npm run contracts:seed
+```
+
+2) Import + publish (external libraries):
+
+```bash
+npm run skillcards:import:publish -- \
+  --rpc http://127.0.0.1:8545 \
+  --privateKey 0x... \
+  --skillNft 0x... \
+  --registry 0x... \
+  --skipStubs \
+  --uriBase https://raw.githubusercontent.com/<org>/<repo>/<ref>/skillcards/imported
+```
+
+The chain always stores hashes; the URI is an *access path*, not the source of truth.
+
+## Revenue share (THE POD)
+
+> **Note:** PodVault revenue sharing is deployed as a contract primitive on ApeChain. The full UI and claim flows are coming soon.
+
+In v2, the "download/install agreement" is enforced in two layers:
+
+- Onchain: SkillNFT supports EIP-2981 royalties, so a SkillNFT can route marketplace royalty revenue to a shared `PodVault`. `AgentAccount` + `PolicyEngine` are deployed on ApeChain and enforce policy hooks onchain.
+- Offchain complement: the Pod workspace includes `REVENUE_SHARING.md` as an explicit runner contract note for additional guidance beyond the onchain enforcement.
+
+### Mint a SkillNFT with a PodVault royalty receiver
+
+```bash
+ape-claw v2 skill mint \
+  --rpc http://127.0.0.1:8545 \
+  --privateKey 0x... \
+  --skillNft 0x... \
+  --registry 0x... \
+  --royalty-receiver 0xPodVault... \
+  --royalty-bps 500 \
+  --json
+```
+
+## Receipts (audit trail)
+
+`ReceiptRegistry` is a minimal, append-only onchain audit primitive. It does not try to index or interpret your actions; it only anchors:
+
+- `traceIdHash` (bytes32)
+- `contentHash` (bytes32)
+- `subject` (bytes32 hash of a string like `agent:<id>` or `pod:otherside-navigator`)
+- `uri` (string, optional pointer to richer offchain detail)
+
+### Record a receipt (CLI)
+
+```bash
+ape-claw v2 receipt record \
+  --rpc http://127.0.0.1:8545 \
+  --privateKey 0x... \
+  --receipts 0x... \
+  --traceId "nft-buy:2026-02-18:the-clawllector:orderHash:0x..." \
+  --subject "agent:the-clawllector" \
+  --payload '{"eventType":"nft.buy.confirmed","collection":"...","priceApe":123}' \
+  --uri "file://./state/receipts/nft-buy-2026-02-18.json" \
+  --json
+```
+
+### Record receipts from THE POD (optional)
+
+The Pod runner supports strict opt-in onchain receipts (low frequency) via flags in `pod/run_agent.py` and the helper script `pod/record_receipt.mjs`.

package/docs/WEB4_PLAN_STATUS.md

@@ -0,0 +1,95 @@
+# Web4 Onchain Skills Plan — Status
+
+This project includes the reference plan in `web4_onchain_skills_plan.pdf`.
+
+This doc maps that plan to what ApeClaw has shipped today.
+
+## What is shipped (v2)
+
+These components exist in-repo and are tested:
+
+- `SkillNFT` (`contracts/SkillNFT.sol`)
+  - ERC-721 skill provenance
+  - parent forks (`parentSkillId`)
+  - optional royalties (EIP-2981) so skill revenue can route to a Pod receiver
+- `SkillRegistry` (`contracts/SkillRegistry.sol`)
+  - append-only version publishing
+  - stores `versionHash`, `contentHash`, `uri`, `riskTier`
+- `IntentRegistry` (`contracts/IntentRegistry.sol`)
+  - minimal intent create/cancel primitive
+- `ReceiptRegistry` (`contracts/ReceiptRegistry.sol`)
+  - append-only receipts keyed by `traceIdHash`
+- `PolicyEngine` (`contracts/PolicyEngine.sol`)
+  - minimal onchain pre-check hook (allowlists + value cap)
+- `AgentAccount` (`contracts/AgentAccount.sol`)
+  - minimal execution shell that enforces PolicyEngine and records receipts
+- Initial module skills (`contracts/*Module.sol`)
+  - `SwapModule`, `BridgeModule`, `NftBuyModule` (policy-gated call wrappers)
+- `PodVault` (`contracts/PodVault.sol`)
+  - PaymentSplitter-style revenue receiver for THE POD (native + ERC20)
+- Seed + deploy flow (`npm run contracts:seed`)
+  - deploys v2 contracts
+  - publishes all SkillCards in `skillcards/seed/`
+
+SkillCards + library ingestion:
+
+- seed SkillCards in `skillcards/seed/` (including v1 skills, receipts, and ACP bounties runbooks)
+- importer: `scripts/import-skillcards.mjs`
+  - imports SkillCards from GitHub repos and ClawHub (best-effort)
+  - writes `skillcards/imported/index.json` (provenance + hashes)
+
+Frontend/docs:
+
+- `/ui` dashboard (telemetry, chat, live feed)
+- `/skills` library page (seed + imported library views)
+- `/docs` in-site markdown docs reader
+- `/pod` product landing for THE POD
+
+Critique response:
+
+- `docs/AUTONOMY_AND_SUBSTRATE.md` directly addresses the "bounded automation" critique without overclaiming.
+
+## What is NOT shipped yet (still part of the plan)
+
+The Web4 plan calls out these primitives as critical for full permissionless autonomy. ApeClaw ships `AgentAccount` + `PolicyEngine` on ApeChain (allowlists + value caps enforced onchain), `PodVault` for revenue sharing, and `ClawllectorPass` for identity. The full design continues to evolve:
+
+- session keys / AA kernel hardening (ERC-4337 style)
+- richer policy constraints (token/time windows, slippage checks, approvals model)
+- Permissionless solver network + payments
+- Attestation/reputation registry + eval packs onchain
+- Disputes + slashing (optional later phase)
+
+The current posture is deliberately "v2":
+
+- strong provenance + immutable versions + receipts primitive
+- onchain enforcement via AgentAccount + PolicyEngine (deployed on ApeChain)
+- revenue sharing via PodVault (deployed on ApeChain at `0xff20500637e5aa1a78e263475ca1d49b35c9ed0c`)
+- strict opt-in for high-risk automation
+- offchain execution remains bounded by the runner "box"
+
+## Phase mapping (rough)
+
+- P0 (contracts + basic UI): partially shipped
+  - contracts shipped: yes (SkillNFT, SkillRegistry, IntentRegistry, ReceiptRegistry, PolicyEngine, AgentAccount, PodVault, SwapModule, BridgeModule, NftBuyModule, ClawllectorPass)
+  - basic UI for discovery/install/intents: partially shipped
+    - discovery: `/skills` (seed + imported + submitted SkillCards, onchain status visualization)
+    - intents: `/skills#intents` ships a safe command-generator surface for `v2 intent create|cancel`
+    - install: download/curl commands are surfaced per-skill; full “one-click install into an agent runtime” remains planned
+- P1 (AgentAccount + module skills + receipts): shipped (v2 minimal primitives)
+  - `AgentAccount.executeSkill()` enforces `PolicyEngine.preCheck()` and best-effort records to `ReceiptRegistry`
+  - modules shipped: `SwapModule`, `BridgeModule`, `NftBuyModule` (policy-gated call wrappers; routing/UX remains offchain)
+- P2 (permissionless solvers): not shipped
+- P3 (attestations/reputation): not shipped
+- P4 (disputes/slashing): not shipped
+
+## Why this is still a functioning platform today
+
+ApeClaw's "functioning platform" claim is grounded in:
+
+- global onboarding + telemetry + audit trail (events + optional receipts)
+- deterministic CLI safety gates for value-moving actions
+- a skill library that is content-addressed and publishable onchain
+- a persistent Pod harness (file-backed) for long-running operation
+
+The plan items above are the path from "bounded automation with anchors" to "permissionless autonomy with substrate enforcement".
+

package/docs/WEB4_SWARM_MODEL.md

@@ -0,0 +1,104 @@
+# Web4 Swarm Model (ApeClaw)
+
+This doc explains the core vision behind ApeClaw as a Web4 platform: **agents operate as a swarm**, and the swarm scales when it can:
+
+- share capabilities (skills)
+- share ground truth (receipts)
+- persist state (checkpointing) beyond any single machine
+- coordinate value-moving work safely (policies + caps + confirmations)
+
+## Why Web4 needs onchain context
+
+Most “autonomous agents” are bounded automation:
+
+- they plan in language, but don’t control the substrate
+- they lose state when the UI/backend/API keys disappear
+- they can’t prove what happened or coordinate trustlessly with other agents
+
+A Web4 swarm needs a source of truth that:
+
+- survives disappearing infrastructure
+- is globally readable by any agent
+- is permissionless at the primitive layer, but filterable at the UI layer
+
+That’s why ApeClaw uses onchain primitives for:
+
+- **Skill identity + versions** (SkillNFT + SkillRegistry)
+- **Receipts** (ReceiptRegistry)
+
+## Skills: swarm capability scaling
+
+SkillCards are portable JSON definitions: metadata + bindings + constraints.
+
+- Offchain SkillCard JSON is the human-readable spec.
+- Onchain publication anchors immutable versions:
+  - `contentHash` (content-addressed)
+  - `uri` (where the SkillCard lives)
+  - `riskTier` (safety classification)
+
+This enables:
+
+- deterministic upgrades (no silent changes)
+- global discovery (chain indexers + UIs)
+- “skill provenance” (what version did we run?)
+
+## Receipts: swarm memory + audit truth
+
+Receipts are append-only anchors keyed by `traceIdHash`.
+
+The pattern:
+
+1) An agent does work (or simulates/quotes work)
+2) It records a receipt with:
+   - `traceIdHash` (deterministic id)
+   - `contentHash` (what happened)
+   - `subject` (who/what it’s about)
+   - `uri` (optional pointer to larger payload/log)
+3) Any other agent can later read the receipt back from chain
+
+This gives the swarm:
+
+- “memory reload” (reconstruct state from receipts)
+- auditability (“prove what happened”)
+- coordination hooks (receipts as triggers)
+
+CLI primitives:
+
+- Record: `ape-claw v2 receipt record ...`
+- Read: `ape-claw v2 receipt get ...`
+
+## Persistence: Pod workspace + chain checkpoints
+
+Chain receipts are not a replacement for local state; they are a globally readable checkpoint layer.
+
+The Pod workspace pattern provides:
+
+- durable local state (files)
+- crash recovery (`memory/active-tasks.md`, journals)
+- strict opt-in execution (dry-run by default)
+
+Receipts provide:
+
+- global, portable checkpoints
+- tamper-resistant audit anchors
+
+The combination is what makes “agent swarm” possible.
+
+## Contribution loop (how the swarm grows)
+
+1) Users/agents submit SkillCards to the library (`/skills`)
+2) Curators/operators mint + publish onchain (immutable version)
+3) Agents use published skills, record receipts
+4) New skills and receipts expand the swarm’s capability + context
+
+5) Revenue from skills and bounties routes to PodVault for Pod-wide splits
+6) Verified Clawllectors claim identity via ClawllectorPass (onchain ERC-721)
+
+The swarm operates as a **syndicate**: agents collaborate, share capabilities, and share revenue. PodVault (deployed on ApeChain at `0xff20500637e5aa1a78e263475ca1d49b35c9ed0c`) is the shared treasury. SkillNFT royalties and ACP bounty earnings flow into PodVault, and members claim proportional shares.
+
+See:
+
+- `docs/CONTRIBUTING.md`
+- `docs/ONCHAIN_V2_GUIDE.md`
+- `docs/ACP_BOUNTIES.md`
+