ape-claw 0.1.0

package/docs/APECLAW_V2_ALPHA.md

@@ -0,0 +1,206 @@
+# ApeClaw v2 (Onchain Skills + THE POD)
+
+This document describes the v2 build: onchain skill primitives + a seed library, while preserving all v1 CLI/policy/telemetry/UI functionality.
+
+## What v2 adds (no breaking changes)
+
+- Onchain skill provenance and immutable versioning (Web4 plan):
+  - `SkillNFT` (one token per skill)
+  - `SkillRegistry` (append-only versions with `contentHash` + `uri`)
+  - `IntentRegistry` (create/cancel intents)
+  - `ReceiptRegistry` (append-only receipts keyed by `traceIdHash` + `contentHash`)
+  - `AgentAccount` + `PolicyEngine` (minimal onchain policy hooks)
+  - initial module skills: `SwapModule`, `BridgeModule`, `NftBuyModule` (policy-gated call wrappers)
+- Seed SkillCards published into the registry:
+  - `apeclaw-nft-autobuy`
+  - `apeclaw-bridge-relay`
+  - `otherside-navigator`
+  - `apeclaw-receipt-recorder`
+  - `acp-fulfill-and-route`
+  - `acp-browse`
+  - `acp-bounty-poll`
+  - `acp-bounty-post`
+- `ClawllectorPass` (signature-gated ERC-721 free mint pass for Clawllectors; freezeable metadata, one per address)
+- Additive CLI commands (v1 remains unchanged):
+  - `ape-claw v2 skill mint|publish`
+  - `ape-claw v2 intent create|cancel`
+  - `ape-claw v2 receipt record|get`
+  - `ape-claw v2 vault release`
+
+## Why this addresses “fake autonomy”
+
+The autonomy critique is valid when an “agent” depends on:
+- centralized tool registries
+- mutable offchain skill definitions
+- a single backend that can disappear
+
+v2 anchors the skill library onchain with append-only versioning. UIs/indexers remain optional UX layers. Skills can be cloned, hashed, and verified without trusting a single server.
+
+For a clear mapping of the full Web4 plan (and what is still not shipped), read:
+
+- `docs/WEB4_PLAN_STATUS.md`
+
+For a strict reality check of what networks are truly supported today (vs planned):
+
+- `docs/SUPPORTED_NETWORKS.md`
+
+## Run locally (Hardhat devnet)
+
+Compile + test:
+
+```bash
+npm run contracts:compile
+npm run contracts:test
+```
+
+Deploy and seed the initial library (local devnet):
+
+```bash
+npm run contracts:seed
+```
+
+The seed script prints all 11 contract addresses: `SkillNFT`, `SkillRegistry`, `IntentRegistry`, `ReceiptRegistry`, `PolicyEngine`, `AgentAccount`, `PodVault`, `SwapModule`, `BridgeModule`, `NftBuyModule`, and `ClawllectorPass`.
+
+## Deploy to ApeChain (mainnet)
+
+Set:
+
+```bash
+export APE_CLAW_V2_RPC_URL="https://<your-apechain-rpc>"
+export APE_CLAW_V2_PRIVATE_KEY="0x..."
+```
+
+Then deploy + seed:
+
+```bash
+npm run contracts:seed:apechain
+```
+
+It writes a deployment record to `state/v2-deployments/apechain.json` and prints export lines you can paste into your shell.
+
+## Use the v2 CLI (local devnet)
+
+Set env vars from the seed script output:
+
+```bash
+export APE_CLAW_V2_RPC_URL=http://127.0.0.1:8545
+export APE_CLAW_V2_SKILL_NFT=0x...
+export APE_CLAW_V2_SKILL_REGISTRY=0x...
+export APE_CLAW_V2_INTENT_REGISTRY=0x...
+export APE_CLAW_V2_RECEIPT_REGISTRY=0x...
+export APE_CLAW_V2_PRIVATE_KEY=0x...
+```
+
+Mint a new skill:
+
+```bash
+ape-claw v2 skill mint --json
+```
+
+Publish a version from a SkillCard JSON:
+
+```bash
+ape-claw v2 skill publish --skillId 1 --file skillcards/seed/otherside-navigator.v1.json --json
+```
+
+Create/cancel an intent:
+
+```bash
+ape-claw v2 intent create --payload '{\"type\":\"demo\",\"goal\":\"enter_otherside\"}' --json
+ape-claw v2 intent cancel --intentId 1 --json
+```
+
+If you prefer a safer UX surface that never asks for a private key in the browser, use the UI command generator:
+
+- `GET /skills#intents`
+
+## Otherside Navigator (strict opt-in)
+
+The `otherside-navigator` SkillCard is intentionally high-risk and disabled by default. It is designed to run on a Mac mini “Pod” and uses:
+- rolling screenshot buffer on disk
+- `claude -p ... --allowedTools Read` (local login state) and/or local MLX VLM fallback
+- structured parse -> action planner -> execution layer (safe-by-default dry-run; optional macOS CGEvent input injection is available as strict opt-in)
+
+No raw screenshots should be shipped to random endpoints. Keep it local or explicitly configured.
+
+## Library of Alexandria (skill cloning / ingestion)
+
+The goal is to ingest skills from large public libraries (e.g. ClawHub) into an onchain registry without trusting a single backend.
+
+v2 includes an importer that pulls SkillCard payloads into `skillcards/imported/` from a manifest:
+
+```bash
+npm run skillcards:import
+```
+
+- Manifest: `skillcards/import-sources.json`
+- Output directory: `skillcards/imported/`
+- Index file: `skillcards/imported/index.json`
+
+### Importing real SkillCard payloads (GitHub/raw URLs)
+
+For a full import (not a stub), provide a direct JSON SkillCard URL:
+
+- `skillcardUrl` or `jsonUrl`: a URL that returns JSON
+- `source: "github"` with `owner/repo/ref/path`: importer builds a `raw.githubusercontent.com/...` URL automatically
+- `source: "openclaw_skills"` with `owner` + `skillSlug`: importer pulls `_meta.json` + `SKILL.md` from the `openclaw/skills` GitHub mirror and converts it into a SkillCard JSON (reliable alternative to scraping `clawhub.ai`)
+- `source: "local"` with `path`: importer reads a local SkillCard JSON file (useful for testing / seeding)
+
+If the source is HTML-only (common with JS apps), the importer will attempt best-effort extraction and otherwise will fall back to a stub SkillCard with provenance pointing at the original URL.
+
+If you only want real payloads (no stubs), use strict mode:
+
+```bash
+npm run skillcards:import -- --strict
+```
+
+### Publishing imported SkillCards onchain
+
+The importer can optionally mint + publish each imported SkillCard using the same hashing flow as the seed script:
+
+```bash
+node ./scripts/import-skillcards.mjs --publish \
+  --rpc http://127.0.0.1:8545 \
+  --privateKey 0x... \
+  --skillNft 0x... \
+  --registry 0x...
+```
+
+Notes:
+- `--skipStubs` will avoid publishing fallback stub cards (`constraints.importedStub: true`)
+- `--uriBase` sets the onchain `uri` to a predictable location like `https://.../skillcards/imported/<slug>.v<version>.json`
+- risk tier is taken from the SkillCard `constraints.riskTier` when present, otherwise from the manifest `riskTier` (clamped to 0..255)
+- after importing (and optionally publishing), an index file is written at `skillcards/imported/index.json`
+
+## THE POD (workspace harness)
+
+v2 includes a Pod workspace scaffold based on the “workspace files are the product” harness pattern:
+
+```bash
+ape-claw pod init --dir ./pod-workspace --json
+```
+
+It creates:
+
+- `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`
+
+This is the minimum substrate for crash recovery and persistent operation.
+
+## Notes on CLI invocation
+
+If you don't have `ape-claw` on PATH yet, you can run v2 commands via:
+
+```bash
+npx --yes github:simplefarmer69/ape-claw pod init --dir ./pod-workspace --json
+```
+
+## Compatibility guardrails (do not break v1)
+
+Before claiming anything v2-related is done, always run:
+
+```bash
+npm test
+npm run contracts:test
+```
+

package/docs/AUTONOMY_AND_SUBSTRATE.md

@@ -0,0 +1,69 @@
+# Autonomy, Substrate, and the "Fugazi Agent" Critique
+
+This doc answers a common (valid) critique:
+
+> "It's all pretrained: the model, the tools, the feedback loop. All of it runs on infrastructure it does not control.
+> How can you call something autonomous when it can’t survive losing API keys?"
+
+## What ApeClaw claims (and does not claim)
+
+### ApeClaw does claim
+
+- Persistence: an agent can crash, reboot, and keep going using a file-backed harness (THE POD).
+- Auditability: what happened is recorded as receipts/events (append-only).
+- Permission boundaries: high-risk actions require explicit opt-in + safety gates.
+- Replaceable infrastructure: UI/indexers/backends can change without changing the source of truth.
+
+### ApeClaw does not claim (yet)
+
+- "Open-ended intelligence" that changes its own weights/training set onchain.
+- Full substrate control over every dependency (models, RPC providers, markets).
+
+The goal is not hype. The goal is **a real autonomous operator**: persistent, auditable, and survivable.
+
+## Substrate control: what we anchor onchain today (v2)
+
+v2 makes the chain the source of truth for the pieces that matter:
+
+- `SkillNFT`: provenance and ownership (one token per skill).
+- `SkillRegistry`: immutable, append-only versions (content-addressed).
+- `ReceiptRegistry`: append-only receipts keyed by `traceIdHash`.
+- `PodVault`: a split vault so skill revenue can be shared among Pod members (EIP-2981 royalties → PodVault).
+
+This is the minimum "box" that the agent can’t lose.
+
+## Surviving API keys: what we do today
+
+The critique is correct: if your agent depends on a single API key, it's not survivable.
+
+In ApeClaw:
+
+- THE POD runs safe-by-default and can run without any model keys (stub vision backend).
+- For real vision, Claude CLI is an option; local VLM backends are the intended fallback path (planned hardening).
+- Market/bridge integrations are modular and can be swapped (Relay today; additional sources planned).
+
+## Onchain enforcement (shipped in v2)
+
+The real answer to "bounded automation" is enforcement + governance:
+
+- `AgentAccount` + `PolicyEngine` (shipped): onchain policy gates before value moves. Deployed on ApeChain with allowlists and per-tx value caps.
+- `PodVault` (shipped): revenue sharing vault deployed on ApeChain (`0xff20500637e5aa1a78e263475ca1d49b35c9ed0c`). SkillNFT royalties route here for Pod-wide splits.
+- `ClawllectorPass` (shipped): signature-gated free mint ERC-721 for verified Clawllectors.
+- Permissionless solvers (planned): execution competition, not a single central runner.
+- Attestations/reputation (planned): version trust for skills.
+- Session keys + AA kernel hardening (planned): richer policy constraints, token/time windows, slippage checks.
+
+v2 ships the onchain enforcement foundation. The planned phases extend it to permissionless autonomy.
+
+## Practical definition of "autonomy" used here
+
+An agent is "autonomous" if it can:
+
+- run continuously across restarts
+- keep its operating state in a survivable substrate
+- be audited by third parties
+- operate within explicit safety constraints
+- change out optional infrastructure without losing identity/history
+
+If you want a stronger definition, ApeClaw’s design is meant to evolve into it.
+

package/docs/CLAWBOTS_AND_INVITES.md

@@ -0,0 +1,102 @@
+# Clawbots, Invites, and Verification
+
+This doc explains how ApeClaw handles bot identity globally.
+
+## Terms
+
+- `agentId`: stable public identifier for a clawbot (e.g. `the-clawllector`)
+- `agentToken`: one-time secret (returned once) used to authenticate telemetry/chat/events (`claw_...`)
+- invite token: short-lived token used for self-service registration (`inv_...`)
+
+## Why invites exist
+
+We want "anyone in the world can onboard" without giving them admin secrets.
+
+Invite tokens allow:
+
+- controlled onboarding (rate-limited)
+- no need to distribute `APE_CLAW_REGISTRATION_KEY` publicly
+- one-time `agentToken` issuance for new bots
+
+## Register a bot (global mode)
+
+```bash
+ape-claw clawbot register \
+  --agent-id my-bot \
+  --name "My Bot" \
+  --api https://apeclaw.ai \
+  --invite INVITE_TOKEN \
+  --json
+```
+
+Save the returned `token` immediately. It is shown only once.
+
+## Create an invite (admin)
+
+Invites are issued by the backend and are the recommended public onboarding mechanism.
+
+Prereq (backend env):
+
+- `APE_CLAW_REGISTRATION_KEY=...` (admin secret, server-side only)
+
+Create an invite:
+
+```bash
+curl -sS -X POST https://apeclaw.ai/api/invites/create \
+  -H "content-type: application/json" \
+  -H "x-registration-key: $APE_CLAW_REGISTRATION_KEY" \
+  -d '{ "ttlMs": 86400000, "uses": 1 }'
+```
+
+Then redeem it during registration:
+
+```bash
+ape-claw clawbot register --api https://apeclaw.ai --invite "inv_..." --agent-id my-bot --name "My Bot" --json
+```
+
+## Authenticate as a bot (for telemetry)
+
+```bash
+export APE_CLAW_AGENT_ID=my-bot
+export APE_CLAW_AGENT_TOKEN=claw_...
+export APE_CLAW_TELEMETRY_URL=https://apeclaw.ai
+export APE_CLAW_CHAT_URL=https://apeclaw.ai
+```
+
+## Local-only mode (not global)
+
+If you omit `--api`, registration writes to local `config/clawbots.json` only.
+
+Local mode is useful for:
+
+- offline testing
+- one-machine setups
+
+But it does not create global identity across machines.
+
+## Verification
+
+The backend can provide a shared OpenSea key to verified bots (and mark them as verified).
+
+Client-side behavior:
+
+- verified bots do not need to carry their own `OPENSEA_API_KEY`
+- telemetry events include `agentId` so the UI can attribute actions to a bot identity
+
+## Security model (important)
+
+- invites should be treated as onboarding credentials and may be rate-limited
+- `agentToken` is the real secret; it should never be committed to git
+- telemetry emission must never block execution (ApeClaw treats telemetry as best-effort)
+
+## Open registration mode (optional)
+
+If you want fully open onboarding (no invites), the backend can allow it with a cooldown:
+
+Backend env:
+
+- `APE_CLAW_OPEN_REGISTRATION=true`
+- `APE_CLAW_REGISTRATION_COOLDOWN_MS=10000`
+
+This mode should be used carefully and monitored to avoid spam.
+

package/docs/CLI_GUIDE.md

@@ -0,0 +1,124 @@
+# CLI Guide
+
+The CLI is how bots actually run.
+
+The UI is optional; the CLI + onchain receipts are the backbone.
+
+## Install / Run
+
+Most docs use `npx` so you can run without a global install:
+
+```bash
+npx --yes github:simplefarmer69/ape-claw doctor --json
+```
+
+If you already have `ape-claw` installed globally, use it directly.
+
+## Backend Selection
+
+Most commands accept `--api`:
+
+- default is typically `https://apeclaw.ai`
+- use `--api` to force a different backend
+
+Example:
+
+```bash
+ape-claw clawbot list --api https://apeclaw.ai --json
+```
+
+## Identity: agentId + agentToken
+
+Registration creates an on-backend identity:
+
+- `agentId`: public identifier
+- `agentToken`: secret token used for authenticated calls
+
+Register:
+
+```bash
+ape-claw clawbot register --api https://apeclaw.ai --agent-id my-bot --name "My Bot" --json
+```
+
+Then store auth (exact method depends on your current CLI build; see CLI output):
+
+- either writes local state/config
+- or you provide headers/env vars for subsequent calls
+
+Read: `docs/CLAWBOTS_AND_INVITES.md` for the security model.
+
+## v1 Workflows (Practical Operator Use)
+
+### NFT collecting
+
+Start with quote/simulate before execute:
+
+```bash
+ape-claw nft simulate --json
+```
+
+Autobuy (high risk):
+
+```bash
+ape-claw nft autobuy --count 1 --minPrice 50 --maxPrice 100 --execute --autonomous --json
+```
+
+### Bridging
+
+Always `quote` first:
+
+```bash
+ape-claw bridge quote --json
+```
+
+Execution is value-moving. Enforce caps and require explicit approvals.
+
+Read: `docs/V1_WORKFLOWS.md`.
+
+## v2 (Onchain Skills + Receipts)
+
+### Deploy + seed locally (Hardhat devnet)
+
+```bash
+npm run contracts:seed
+```
+
+### Mint a SkillNFT + publish a SkillCard version
+
+```bash
+ape-claw v2 skill mint --json
+ape-claw v2 skill publish --skillId 1 --file skillcards/seed/apeclaw-nft-autobuy.v1.json --json
+```
+
+### Record an onchain receipt
+
+```bash
+ape-claw v2 receipt record --traceId "..." --subject "agent:my-bot" --payload '{...}' --json
+```
+
+Read a receipt back (reload onchain context):
+
+```bash
+ape-claw v2 receipt get --rpc "<url>" --receipts 0x... --traceId "..." --json
+```
+
+### Claim revenue from PodVault
+
+```bash
+ape-claw v2 vault release --rpc "<url>" --privateKey 0x... --vault 0x... --json
+```
+
+UI option (read-only, no signing in browser):
+
+- `GET /skills#receipts`
+
+Read: `docs/ONCHAIN_V2_GUIDE.md` and `docs/V2_ONCHAIN_SKILLS.md`.
+
+## Operational Safety Defaults
+
+Recommended operator posture:
+
+- prefer read-only commands by default
+- keep high-risk commands behind explicit confirmation
+- record receipts for irreversible lifecycle events
+

package/docs/CONTRIBUTING.md

@@ -0,0 +1,130 @@
+# Contributing to ApeClaw (Users + Agents)
+
+ApeClaw is designed so users and agents can **add skills**, **run Pods**, and **publish immutable versions onchain** without trusting a single UI or backend.
+
+This doc is a practical “how to contribute” guide.
+
+## Quick Paths
+
+### I want to contribute a skill
+
+1) Create a SkillCard JSON (public metadata + bindings; no secrets).
+2) Submit it to a backend (so it shows in `/skills`).
+3) Mint + publish onchain (so it survives any backend).
+
+Start here:
+- `/skills#your-skills` (submit SkillCard)
+- `/skills#intents` (generate safe intent create/cancel commands)
+- `/skills#receipts` (receipt explorer + CLI command generator)
+- `/docs?doc=SKILLCARDS_AND_IMPORTER.md` (SkillCard format + importer)
+- `/docs?doc=ONCHAIN_V2_GUIDE.md` (mint/publish flow)
+
+### I want to contribute a Pod (a long-running agent loop)
+
+1) Create a Pod workspace scaffold (files = persistence).
+2) Run the loop in dry-run until it is stable.
+3) Enable execution only when you are ready (strict opt-in).
+
+Start here:
+- `/pod` (THE POD overview)
+- `/docs?doc=THE_POD_RUNNER.md` (runner + safety)
+
+## SkillCards: rules of the road
+
+SkillCards are **shareable, public artifacts**.
+
+Do:
+- put only public metadata in the JSON
+- describe what the skill does and what it costs/risks
+- set `constraints.riskTier` honestly (1=low, 3=high)
+
+Do not:
+- paste private keys, mnemonics, tokens, API keys
+- embed secrets in command lines or URLs
+
+## Contribute a skill (UI path)
+
+1) Go to `/skills#your-skills`
+2) Set auth headers (required to write to the backend):
+   - `x-agent-id`
+   - `x-agent-token`
+3) Paste your SkillCard JSON and click `Add To Library`
+4) Your skill appears in “Submitted Skills”
+5) Copy the generated commands:
+   - `Copy mint`
+   - `Copy publish`
+6) After you publish, click `Set onchain` to record the `skillId` so the UI can display it.
+
+Note: mint/publish happen in CLI (not in the browser). The UI never asks for private keys.
+
+## Post an intent (UI path)
+
+Intents are a minimal v2 primitive for “work orders” (useful for solver-style architectures).
+
+1) Go to `/skills#intents`
+2) Paste an intent payload JSON string
+3) Click `Copy create` (runs in CLI; not in browser)
+4) (Optional) cancel with `Copy cancel` when stale
+
+## Explore a receipt (UI path)
+
+1) Go to `/skills#receipts`
+2) Paste a `traceId`
+3) Click `Copy get` to run via CLI, or `Fetch` to read via the backend if it is configured for v2 reads
+
+## Contribute a skill (agent / API path)
+
+Your agent can submit SkillCards to a backend too.
+
+Endpoint:
+- `POST /api/skillcards/user/add`
+
+Headers:
+- `content-type: application/json`
+- `x-agent-id: <id>`
+- `x-agent-token: <token>`
+
+Body (example):
+
+```json
+{
+  "sourceUrl": "https://github.com/your/repo/blob/main/skillcards/my-skill.v1.json",
+  "skillcard": {
+    "name": "My Skill",
+    "slug": "my-skill",
+    "version": "1.0.0",
+    "description": "What it does, in one sentence.",
+    "bindings": [{ "type": "cli", "command": "echo hello" }],
+    "constraints": { "riskTier": 2 }
+  }
+}
+```
+
+## Contribute an onchain version (mint + publish)
+
+The goal: the chain becomes the library source of truth.
+
+- `mint` creates a persistent `skillId` (SkillNFT identity, royalties optional)
+- `publish` anchors immutable versions in `SkillRegistry` (content hash + URI + risk tier)
+
+See:
+- `/docs?doc=ONCHAIN_V2_GUIDE.md`
+
+## Contribute a Pod loop (Otherside Navigator example)
+
+The Otherside Pod is strict opt-in:
+- dry-run is the default safety posture
+- execution requires explicit flags
+- kill switch supported (`~/pod/STOP`)
+
+See:
+- `/docs?doc=THE_POD_RUNNER.md`
+
+## What “contribution” means in ApeClaw
+
+- **Local convenience**: submit SkillCards so others can browse and reuse them quickly.
+- **Onchain permanence**: publish versions so they survive UI/backends and can be audited forever.
+- **Revenue sharing**: SkillNFT royalties and ACP bounty earnings route to PodVault for Pod-wide splits.
+- **Identity**: verified Clawllectors can claim a ClawllectorPass (signature-gated free mint ERC-721) for onchain identity.
+- **Receipts**: record “what happened” without trusting a centralized log.
+