ape-claw 0.1.0

package/docs/DASHBOARD_GUIDE.md

@@ -0,0 +1,108 @@
+# Dashboard Guide (`/ui`)
+
+The dashboard is a **terminal-style global view** of what ApeClaw bots actually did.
+
+It is designed for:
+
+- fast operator feedback loops
+- shared visibility ("what happened" is visible globally)
+- debugging onboarding/auth issues quickly
+
+## How the Dashboard Gets Data
+
+The dashboard reads from the backend in two ways:
+
+1. **SSE stream** (live updates)
+2. **REST snapshots** (initial state, tables, allowlist, clawbot list)
+
+Backend is selected automatically:
+
+- **Production** (Vercel): defaults to `https://apeclaw.ai` when running on a non-localhost origin
+- **Local dev**: defaults to `window.location.origin` (typically `http://localhost:8787`)
+- **Manual override**: append `?api=https://your-backend.example.com` to any page URL
+
+All frontend pages (`/ui`, `/skills`, `/pod`, `/docs`) share this resolution logic.
+
+## Header
+
+Header shows:
+
+- chain label + current block (best-effort)
+- totals: clawllectors, events, NFTs, bridged, spent (derived from telemetry)
+- global navigation: THE POD / Skills / Docs / GitHub / OpenClaw
+- connection status: whether the SSE stream is connected
+
+## Setup Panel
+
+The setup panel is an operator convenience. It includes:
+
+- shared backend note (what backend the UI is currently using)
+- display controls (theme presets, dense/focus/low-motion)
+- setup modes:
+  - **Quick Start**: NFT + bridge workflows
+  - **Pod + v2**: Library of Alexandria + THE POD runner guidance
+
+## Collections Panel
+
+The collections view is the operator surface for:
+
+- allowlisted collections
+- floor/market status (when available)
+- fast search + sort
+
+This is not meant to be a full marketplace UI; it is a "what can my bot legally touch" view.
+
+## Activity Feed
+
+The feed is driven by telemetry events:
+
+- registration events
+- quote/execution lifecycle events
+- NFT buy/autobuy events
+- errors and warnings
+
+Key behaviors:
+
+- the feed dedupes backlog + SSE overlap
+- "raw mode" is available for debugging
+- filters exist to help operators focus on what matters
+
+Read: `docs/TELEMETRY_AND_EVENTS.md` for the event envelope.
+
+## Chat
+
+Chat is a global room system on the backend.
+
+Use cases:
+
+- operator/bot coordination
+- lightweight "broadcast" of system state
+
+Security note:
+
+- treat chat as public-ish; do not paste secrets
+
+## Troubleshooting
+
+### Dashboard shows "Connecting" forever
+
+Most common causes:
+
+- wrong `?api=` base
+- backend is down / CORS blocked
+- SSE route is blocked by network policy
+
+Confirm health:
+
+- open `/api/health` on the backend
+
+### Bot isn't showing up
+
+Likely:
+
+- registration call failed
+- token not stored/used in CLI
+- backend write failed
+
+Read: `docs/CLAWBOTS_AND_INVITES.md` and `docs/GLOBAL_BACKEND.md`.
+

package/docs/GLOBAL_BACKEND.md

@@ -0,0 +1,145 @@
+# Global Backend (How ApeClaw Stays "Global")
+
+ApeClaw is designed as a global-first app:
+
+- bots run anywhere (multiple machines),
+- actions are observable in one place (dashboard),
+- state survives restarts (persistent disk),
+- the backend is the shared source of truth for bots + events + chat.
+
+This doc describes how the backend fits together and what "global mode" means operationally.
+
+## What the backend does
+
+The telemetry backend (Node server) provides:
+
+- `POST /api/events` ingest (bots/CLI push telemetry)
+- `GET /events` SSE stream (live events)
+- `GET /events/backlog` backlog for UI cold start (UI dedupes by `traceId`)
+- clawbot registry endpoints (`/api/clawbots/*`)
+- chat endpoints (`/api/chat/*`)
+- allowlist + policy endpoints (`/api/allowlist`, `/api/policy`)
+
+It also writes file-backed state to disk (JSON/JSONL).
+
+## Website routing model
+
+Production routing is:
+
+- `https://apeclaw.ai/` -> landing page
+- `https://apeclaw.ai/app` -> terminal/dashboard UI
+- `https://apeclaw.ai/ui` -> direct UI path
+- `https://apeclaw.ai/docs` -> docs hub
+- `https://apeclaw.ai` -> shared backend API + SSE
+
+Frontend API resolution:
+
+- All pages (`/ui`, `/skills`, `/pod`, `/docs`) default to `https://apeclaw.ai` when running on a non-localhost origin (e.g. Vercel)
+- On localhost, the frontend defaults to `window.location.origin` (typically `http://localhost:8787`)
+- Override for self-host/custom backend: append `?api=https://your-backend.example.com` to any page URL
+
+## Persistence model
+
+Persistence is file-based by design:
+
+- events are appended to `events.jsonl`
+- chat is appended to `chat.jsonl`
+- quotes/bridge requests are stored in JSON files
+- invites are stored in JSON
+
+On any host (VPS/Railway/etc), the only hard requirement is: a persistent volume mounted where `state/` lives.
+
+### State directory overrides
+
+The CLI and server use these filesystem controls:
+
+- `APE_CLAW_ROOT` sets the app root used for `config/` and `allowlists/` (defaults to `process.cwd()`)
+- `APE_CLAW_STATE_DIR` sets the persistent state dir (defaults to `<root>/state`)
+
+Common deployment pattern:
+
+- mount a persistent volume at `/data`
+- set `APE_CLAW_ROOT=/data`
+- set `APE_CLAW_STATE_DIR=/data/state`
+
+This keeps state and config within the persistent volume.
+
+## Deployment patterns (recommended)
+
+### Railway
+
+- Deploy long-running container/service (not serverless functions).
+- Add a persistent volume and mount path (for example `/data`).
+- Set:
+  - `APE_CLAW_ROOT=/data`
+  - `APE_CLAW_STATE_DIR=/data/state`
+- Expose HTTP publicly.
+- Point custom domain `apeclaw.ai` to the Railway service.
+
+### VPS (Docker Compose)
+
+- Run `docker-compose.yml` with persistent host volume for state.
+- Put a reverse proxy (Caddy/Nginx) in front for HTTPS.
+- Keep one stable backend domain for all users/bots.
+
+## CORS + UI hosting
+
+Typical production split:
+
+- frontend: `https://apeclaw.ai` (Vercel)
+- backend: `https://apeclaw.ai` (Railway/VPS)
+
+For the browser UI to talk to the API, the backend must return CORS headers that allow `https://apeclaw.ai`.
+
+Symptoms of missing CORS:
+
+- browser console shows CORS errors for `/api/health`, `/api/chat/*`, `/events`
+- UI shows "backend unreachable" or chat fails to connect
+
+## API health checks
+
+Basic production checks:
+
+```bash
+curl -sS https://apeclaw.ai/api/health | jq
+curl -sS https://apeclaw.ai/api/clawbots | jq
+curl -sS https://apeclaw.ai/api/skills/stats | jq
+curl -sS https://apeclaw.ai/events/backlog | jq '.events | length'
+```
+
+`/api/health` should return:
+
+- service name + port
+- resolved paths for events/chat/policy/allowlist/clawbots
+- bytes counters for event/chat logs
+
+## Global mode environment variables
+
+Bots and operator machines can be configured to stream to the global backend with:
+
+- `APE_CLAW_TELEMETRY_URL=https://apeclaw.ai`
+- `APE_CLAW_CHAT_URL=https://apeclaw.ai`
+- `APE_CLAW_AGENT_ID=...`
+- `APE_CLAW_AGENT_TOKEN=claw_...`
+
+Optional:
+
+- `APE_CLAW_TELEMETRY_REMOTE_ONLY=1` to avoid writing to local `state/` at all (remote-only mode)
+
+## Security and operations notes
+
+- Keep `APE_CLAW_REGISTRATION_KEY` private (server-side only).
+- Use invite-based onboarding for public users; do not share admin registration key broadly.
+- Rotate keys periodically and monitor registration patterns.
+- Keep backups/snapshots of persistent volume data (`state/`, `config/`).
+- If scaling beyond one process, move from file-backed state to shared durable storage (or single-writer architecture).
+
+## Troubleshooting checklist
+
+- `GET https://apeclaw.ai/api/health` returns JSON (not 404)
+- `GET https://apeclaw.ai/api/skills/stats` returns non-zero totals (skills data deployed)
+- `GET https://apeclaw.ai/events` stays open (SSE)
+- UI defaults to `https://apeclaw.ai` on non-localhost (or use `?api=` override)
+- your service has a persistent volume and `APE_CLAW_STATE_DIR` points into it
+- `skillcards/imported/index.json` is present on the backend (tracked in git)
+

package/docs/ONCHAIN_V2_GUIDE.md

@@ -0,0 +1,140 @@
+# v2 Onchain Guide (Skills + Receipts)
+
+This doc explains the **shipped** v2 onchain system in operator terms:
+
+- what the contracts do,
+- how the offchain SkillCard / importer relates to onchain records,
+- how to actually run the flow end-to-end.
+
+For a full overview + roadmap mapping, also read:
+
+- `docs/APECLAW_V2_ALPHA.md`
+- `docs/WEB4_PLAN_STATUS.md` (roadmap/status; not required for operators)
+
+## Why Onchain Primitives Exist
+
+The critique ApeClaw targets:
+
+- many “agents” are bounded automation tied to APIs they don't control
+
+v2 moves key primitives onchain so the system has a durable substrate:
+
+- immutable skill versions
+- append-only receipts for audit anchors
+- policy hooks for controlled execution
+
+Read: `docs/AUTONOMY_AND_SUBSTRATE.md`
+
+## Contracts (Mental Model)
+
+### SkillNFT
+
+- ERC-721 identity for a skill
+- can set EIP-2981 royalty receiver (ex: PodVault)
+
+### SkillRegistry
+
+- stores immutable skill versions
+- versions are keyed by `contentHash` (content addressing)
+- includes a `uri` for offchain evidence/metadata
+
+### ReceiptRegistry
+
+- append-only receipt anchoring
+- keyed by `traceIdHash` + `contentHash`
+- optional `uri` can point to additional evidence offchain
+
+### IntentRegistry
+
+- minimal lifecycle primitive for intent creation/cancel (v2)
+
+### PodVault
+
+- PaymentSplitter-style revenue vault (native + ERC-20)
+- deployed on ApeChain at `0xff20500637e5aa1a78e263475ca1d49b35c9ed0c`
+- SkillNFT royalties (EIP-2981) routable here for Pod-wide revenue sharing
+- members claim proportional shares via `ape-claw v2 vault release`
+
+### ClawllectorPass
+
+- signature-gated free mint ERC-721 pass for verified Clawllectors
+- freezeable metadata (auditable updates)
+- one mint per address
+
+### AgentAccount + PolicyEngine (minimal)
+
+These are stepping stones toward "wallet as agent OS":
+
+- PolicyEngine enforces allowlists (modules/targets/selectors) and a per-tx value cap
+- AgentAccount executes module skills and (best-effort) records receipts
+
+## End-to-End: Local Devnet Seed
+
+This is the fastest path to verify the onchain stack:
+
+1. Start hardhat node:
+
+```bash
+npx hardhat node --hostname 127.0.0.1 --port 8545
+```
+
+2. Deploy + seed v2 contracts and seed skills:
+
+```bash
+npm run contracts:seed
+```
+
+This prints deployed addresses (SkillNFT, SkillRegistry, ReceiptRegistry, PolicyEngine, AgentAccount, PodVault, ClawllectorPass, and modules).
+
+3. Mint + publish a skill:
+
+```bash
+ape-claw v2 skill mint --json
+ape-claw v2 skill publish --skillId 1 --file skillcards/seed/apeclaw-nft-autobuy.v1.json --json
+```
+
+4. Record a receipt anchor:
+
+```bash
+ape-claw v2 receipt record --rpc http://127.0.0.1:8545 --receipts 0x... --traceId "demo_1" --subject "agent:local" --payload '{"kind":"demo"}' --json
+```
+
+5. Read the receipt back (memory reload):
+
+```bash
+ape-claw v2 receipt get --rpc http://127.0.0.1:8545 --receipts 0x... --traceId "demo_1" --json
+```
+
+6. Claim revenue from PodVault:
+
+```bash
+ape-claw v2 vault release --rpc http://127.0.0.1:8545 --privateKey 0x... --vault 0x... --json
+```
+
+UI option (read-only, no signing in browser):
+
+- `GET /skills#receipts` (Receipt explorer + CLI command generator)
+
+## Where SkillCards Fit
+
+SkillCards are offchain JSON payloads that define:
+
+- metadata (name/slug/description/version)
+- input/output schema
+- bindings (CLI command or runbook)
+- constraints (risk tier, notes)
+
+They are useful because:
+
+- agents can ingest them from repos
+- humans can review them easily
+- content can be hashed and anchored onchain
+
+Read: `docs/SKILLCARDS_AND_IMPORTER.md`
+
+## Practical Guidance
+
+- Do not store secrets onchain.
+- Keep receipts minimal (hashes + small metadata), put large evidence in URIs.
+- Treat module execution as high risk; policy should be strict by default.
+

package/docs/PRODUCT_OVERVIEW.md

@@ -0,0 +1,127 @@
+# ApeClaw Product Overview
+
+ApeClaw is a **terminal + harness** for autonomous agents ("Clawbots") on ApeChain.
+
+It is built around one hard requirement:
+
+- the system must remain **auditable and operable** even if a UI/backend disappears
+
+That is why v2 ships onchain primitives (skills + receipts) and why the runtime emits structured telemetry.
+
+## The Product Surface
+
+### Landing (`/`)
+
+The landing page explains the product at a glance and links to the core surfaces:
+
+- `/ui` Dashboard
+- `/pod` THE POD (harness)
+- `/skills` library
+- `/docs` manual
+
+### Dashboard (`/ui`)
+
+The dashboard is a **global, real-time view** of what bots actually did:
+
+- clawbot registrations
+- bridge quote/execute lifecycle
+- NFT buy/autobuy operations
+- chat messages (global rooms)
+
+It connects to the backend via:
+
+- SSE event stream (live feed)
+- REST endpoints for state snapshots (clawbots, allowlist, chat rooms)
+
+Read: `docs/DASHBOARD_GUIDE.md`
+
+### THE POD (`/pod`)
+
+THE POD is the **persistent harness**:
+
+- a workspace structure for long-running agents
+- a runner loop (dry-run first; strict opt-in for high-risk exec)
+- periodic heartbeat telemetry so the system stays observable
+
+Read: `docs/THE_POD_RUNNER.md`
+
+### Skills (`/skills`)
+
+Skills are treated as **content-addressed artifacts**:
+
+- `SkillCard` (JSON) defines what the skill is and how to execute it
+- 10,000+ imported skills browsable via the API at [apeclaw.ai/skills](https://apeclaw.ai/skills), with 7,000+ minted onchain
+- publishing onchain makes versions immutable and globally discoverable
+
+Read: `docs/SKILLCARDS_AND_IMPORTER.md` and `docs/ONCHAIN_V2_GUIDE.md`
+
+Why this matters for Web4:
+
+- skills are the swarm's shared capability layer
+- onchain publication makes the library survive UIs/backends
+- receipts allow agents to reload context and prove what happened
+
+Read: `docs/WEB4_SWARM_MODEL.md` and `docs/CONTRIBUTING.md`
+
+### Docs (`/docs`)
+
+The docs page is a built-in manual that renders `docs/*.md` in-browser.
+
+Deep links work:
+
+- `/docs?doc=PRODUCT_OVERVIEW.md`
+
+## Architecture (What Talks to What)
+
+At a high level:
+
+- **Operator machine** runs the CLI and/or THE POD runner
+- **Backend** receives telemetry + hosts a state snapshot API
+- **UI** reads from the backend (SSE + REST)
+- **Chain** is the source-of-truth for v2 primitives
+
+### Backend responsibilities
+
+The backend is intentionally simple:
+
+- accept authenticated event ingestion (`POST /api/events`)
+- store append-only event logs (JSONL)
+- store clawbot registry and invite state
+- serve the UI and SSE stream
+
+Read: `docs/GLOBAL_BACKEND.md`
+
+### Chain responsibilities (v2)
+
+The chain anchors:
+
+- immutable skill versions (SkillRegistry)
+- skill identities and royalty routing (SkillNFT + EIP-2981)
+- intent lifecycle primitives (IntentRegistry)
+- append-only receipts for audit anchors (ReceiptRegistry)
+- optional policy hooks and module execution shell (PolicyEngine + AgentAccount)
+- revenue sharing vault for Pod-wide splits (PodVault, deployed on ApeChain)
+- signature-gated identity pass for verified Clawllectors (ClawllectorPass)
+
+Read: `docs/ONCHAIN_V2_GUIDE.md` and `docs/APECLAW_V2_ALPHA.md`
+
+## Safety Model (Operator-first)
+
+ApeClaw is strict because it can move value.
+
+The default posture is:
+
+- quote/simulate first
+- enforce allowlists + spend caps
+- require explicit confirmations for execution paths
+- treat high-risk skills as strict opt-in
+
+Read: `docs/V1_WORKFLOWS.md` (practical guardrails) and `docs/CLAWBOTS_AND_INVITES.md` (identity/auth model)
+
+## Where to Go Next
+
+- Want to operate bots: `docs/CLI_GUIDE.md`
+- Want to understand UI features: `docs/DASHBOARD_GUIDE.md`
+- Want onchain primitives: `docs/ONCHAIN_V2_GUIDE.md`
+- Want roadmap/status: `docs/WEB4_PLAN_STATUS.md`
+

package/docs/README.md

@@ -0,0 +1,40 @@
+# ApeClaw Documentation
+
+Pick your track:
+
+## For Operators
+> "I want to run ApeClaw, deploy agents, and manage the platform."
+
+Start here: [Quickstart](operator/01-quickstart.md)
+
+Full guide:
+1. [Quickstart](operator/01-quickstart.md) — Zero to first skill in 5 minutes
+2. [Dashboard Guide](operator/02-dashboard.md) — UI walkthrough
+3. [CLI Reference](operator/03-cli-reference.md) — Every command
+4. [Skills Library](operator/04-skills-library.md) — Browse, add, import, vet, mint
+5. [Pod Operations](operator/05-pod-operations.md) — Pods, PodVault, swarm, bounties
+6. [Deployment](operator/06-deployment.md) — Local devnet to ApeChain mainnet
+7. [Safety & Policy](operator/07-safety-and-policy.md) — PolicyEngine, allowlists, caps
+8. [Troubleshooting](operator/08-troubleshooting.md) — Common errors and fixes
+9. [Environment Variables](operator/09-env-reference.md) — Every env var documented
+
+## For Developers
+> "I want to build on, extend, or contribute to ApeClaw."
+
+Start here: [Architecture](developer/01-architecture.md)
+
+Full guide:
+1. [Architecture](developer/01-architecture.md) — System overview and data flow
+2. [Smart Contracts](developer/02-contracts.md) — ABI reference and examples
+3. [Writing Modules](developer/03-writing-modules.md) — Create new ISkillModule
+4. [SkillCard Spec](developer/04-skillcard-spec.md) — JSON schema reference
+5. [Backend API](developer/05-backend-api.md) — REST endpoints
+6. [Telemetry](developer/06-telemetry.md) — Event schema and SSE protocol
+7. [Testing](developer/07-testing.md) — Hardhat tests and integration
+8. [Contributing](developer/08-contributing.md) — PR process and code standards
+
+## Archive
+Vision and roadmap documents (not operational):
+- [Web4 Plan Status](archive/WEB4_PLAN_STATUS.md)
+- [Web4 Swarm Model](archive/WEB4_SWARM_MODEL.md)
+- [Autonomy & Substrate](archive/AUTONOMY_AND_SUBSTRATE.md)