ape-claw 0.1.0

package/docs/SKILLCARDS_AND_IMPORTER.md

@@ -0,0 +1,147 @@
+# SkillCards + Importer (Library of Alexandria)
+
+SkillCards are portable JSON documents that describe:
+
+- what a skill is,
+- what inputs/outputs it expects,
+- how it can be executed (bindings),
+- what risk tier it carries,
+- provenance (who published it, where it came from).
+
+In v2, the chain stores `contentHash` and `uri` so SkillCards can be content-addressed.
+
+## Seed SkillCards
+
+Seed cards live in `skillcards/seed/` and are published by `npm run contracts:seed` on local devnet.
+
+## Importer
+
+The importer pulls external skill sources into `skillcards/imported/`:
+
+```bash
+npm run skillcards:import
+```
+
+- Manifest: `skillcards/import-sources.json`
+- Output: `skillcards/imported/` (individual JSON files gitignored; `index.json` is tracked)
+- Index file: `skillcards/imported/index.json` (enriched with descriptions; served globally via `/api/skills/search`)
+- Versioned filenames: `<slug>.v<version>.json` (stable for publishing + upgrades)
+
+## Install ACP (Bounties) via importer
+
+Virtuals / ACP exposes a bounty system that lets agents post work requests and pay providers via escrow:
+
+- Repo: `https://github.com/Virtual-Protocol/openclaw-acp`
+- Bounty board: `https://agdp.io/bounties`
+
+In ApeClaw, the simplest “install” path is to import the repo’s `SKILL.md` files into SkillCards:
+
+```bash
+npm run skillcards:import
+```
+
+This repo is included in `skillcards/import-sources.json` as a `github_repo_skill_md` source, so it will be pulled into:
+
+- `skillcards/imported/`
+- `skillcards/imported/index.json`
+
+If `skillcards/imported/index.json` exists, the `/skills` page will show an "Imported Skill Library" section automatically.
+
+Notes:
+
+- ACP bounty skills are typically higher-risk (`riskTier: 3`) because they can move value (USDC escrow). Keep them strict opt-in in THE POD.
+- If you publish imported cards onchain, prefer setting a stable `--uriBase` (HTTP/IPFS/Arweave) instead of `file://...`.
+
+### Manifest fields (supported)
+
+Each entry is a JSON object. Common fields:
+
+- `source`: `"local" | "github" | "clawhub" | "unknown"`
+- `name`, `slug`, `riskTier`
+
+Import sources:
+
+- Local file:
+  - `source: "local"`, `path: "skillcards/seed/..."` (reads from disk)
+- ClawHub top downloads (bulk):
+  - `source: "clawhub_index"`, `url: "https://clawhub.ai/skills?sort=downloads"`
+  - Extracts many skill URLs from the index page, then imports each skill page best-effort.
+  - If a page is HTML-only and does not expose a SkillCard payload, ApeClaw records it as a stub SkillCard (provenance preserved).
+- Direct JSON URL:
+  - `jsonUrl` or `skillcardUrl`
+- GitHub raw:
+  - `source: "github"`, `owner`, `repo`, `ref`, `path`
+- OpenClaw skills mirror (recommended):
+  - `source: "openclaw_skills"`
+  - `owner` (directory owner in the mirror)
+  - `skillSlug` (skill slug folder)
+  - This fetches `_meta.json` + `SKILL.md` from `openclaw/skills` and converts them into a SkillCard JSON.
+  - This is the most reliable way to “pull from ClawHub” without scraping HTML pages.
+
+- ClawHub mirror (bulk import, recommended):
+  - `source: "github_repo_skill_md"`
+  - `owner: "openclaw"`, `repo: "skills"`, `basePath: "skills"`
+  - This imports many `SKILL.md` files from the `openclaw/skills` GitHub mirror (which is the reliable alternative to scraping ClawHub HTML).
+  - Use `limit` in the manifest to control how many skills you pull per run.
+
+HTML-only pages:
+
+- importer attempts best-effort extraction (Next.js `__NEXT_DATA__`)
+- if extraction fails, it writes a stub SkillCard that preserves provenance (`sourceUrl`) and clearly marks itself as a stub
+
+### Strict mode (no stubs)
+
+If you only want real SkillCard payloads and want failures to be explicit:
+
+```bash
+npm run skillcards:import -- --strict
+```
+
+## Optional: publish imported SkillCards
+
+The importer can optionally mint + publish each imported skill onchain:
+
+```bash
+node ./scripts/import-skillcards.mjs --publish \
+  --rpc http://127.0.0.1:8545 \
+  --privateKey 0x... \
+  --skillNft 0x... \
+  --registry 0x...
+```
+
+Recommended options:
+
+- `--skipStubs`: do not publish stub cards (`constraints.importedStub: true`)
+- `--uriBase <url>`: publish with stable onchain URIs like `https://.../skillcards/imported/<slug>.v<version>.json`
+- `--parentId <id>`: mint skills as forks (parent/child) when you want provenance
+
+This is devnet-first. For ApeChain deployment, you will typically want:
+
+- a real content URI (IPFS/Arweave/http) rather than `file://...`
+- a review pipeline to set `riskTier` and permissions appropriately
+
+## Global API Access
+
+Skills are served globally via the backend API at `https://apeclaw.ai`. The UI at [apeclaw.ai/skills](https://apeclaw.ai/skills) consumes these endpoints:
+
+- `GET /api/skills/search` — search and browse all skills (seed + imported + user)
+- `GET /api/skills/<slug>` — fetch full skill details and SkillCard JSON by slug
+- `GET /api/skills/stats` — aggregate counts (total, seed, imported, vetted, onchain)
+
+The `index.json` is tracked in git and deployed to the backend. Individual imported JSON files remain gitignored but are available locally for operators who clone the repo.
+
+## How the importer maps to onchain hashes
+
+The importer uses the same canonical hashing as the v2 seed script:
+
+- `versionHash = keccak256(version_string)`
+- `contentHash = keccak256(stableJsonStringify(skillcard_json))`
+
+The onchain registry stores:
+
+- `skillId` (from `SkillNFT`)
+- `versionHash`
+- `contentHash`
+- `uri` (string)
+- `riskTier`
+

package/docs/STARTER_PACK.md

@@ -0,0 +1,297 @@
+# The ApeClaw Starter Pack: 61 Vetted Skills, One Prompt
+
+You install ApeClaw. The core skill lands. Then your terminal asks one question:
+
+```
+📦  STARTER PACK AVAILABLE
+61 curated, security-vetted skills across productivity, dev tools,
+security, analytics, SEO, automation, and memory.
+
+Install the starter pack? [Y/n]
+```
+
+Press Enter. 61 skills install in about four seconds. You skip the marketplace browsing entirely.
+
+```bash
+npx --yes github:simplefarmer69/ape-claw skill install --scope local
+```
+
+That's it. Your agent has a working toolkit in under a minute.
+
+---
+
+## What gets installed (and why these 61)
+
+We started with a library of 10,000+ skills. We cut everything niche, platform-locked, regional, or hardware-dependent. What's left: 61 skills that are useful whether you're a solo dev, a content team, or running a multi-agent setup.
+
+Every skill passed automated security scanning and manual review. None of them move funds or require private keys without explicit opt-in. None are locked to a single chain, geography, or paid platform.
+
+Here's what you get.
+
+---
+
+## Productivity
+
+**GitHub — gh CLI Integration**
+Manage issues, pull requests, CI runs, and API queries through the gh CLI. JSON output with jq filtering. If you write code, you need this.
+
+**Gog — Google Workspace CLI**
+Gmail, Calendar, Drive, Contacts, Sheets, and Docs from the terminal. Fast, script-friendly, JSON-first output with least-privilege OAuth.
+
+**Self-Improving Agent**
+The agent captures its own errors and corrections. Logs to `.learnings/` and promotes important findings to AGENTS.md and SOUL.md. Over time it stops making the same mistakes.
+
+**Find Skills — Skill Discovery**
+When you ask "how do I do X?" and there's a skill for it, this finds it. Searches the full OpenClaw ecosystem and installs what matches.
+
+**Humanizer — Remove AI Writing Patterns**
+Catches 24 patterns that make text sound machine-written: puffery, em dash abuse, AI vocabulary, sycophantic tone. Based on Wikipedia's AI writing guide.
+
+---
+
+## Developer Tools
+
+**Code Review Engine**
+Automated code review that works on GitHub PRs, local diffs, pasted code, or entire files. No external dependencies.
+
+**API Architect**
+Design, build, test, document, and secure APIs. Covers the full lifecycle from schema design through monitoring.
+
+**ClawRouter**
+Routes each LLM request to the cheapest model that can handle it. 30+ models across 5 providers. We measured 78% cost reduction on mixed workloads.
+
+**Newman — Postman CLI Runner**
+Run and test Postman collections from the command line with reporting, environment variable support, and CI/CD integration.
+
+**Rei Qwen3 Coder**
+Free Qwen3 coding endpoint via an OpenAI-compatible API at coder.reilabs.org. Drop-in replacement for when you want a second opinion.
+
+**Claw Sync**
+Secure, versioned sync for your OpenClaw memory and workspace to GitHub. Backup and version control for your agent's brain.
+
+**DevOps & Platform Engineering Engine**
+Covers CI/CD, infrastructure, deployment, operations, and observability. One skill instead of five.
+
+---
+
+## Security & Safety
+
+**Skill Security Audit**
+Mandatory pre-install security scan. Checks for shell injection, credential harvesting, exfiltration patterns, and encoded payloads before any external skill touches your system.
+
+**GoPlus AgentGuard — AI Agent Security Framework**
+Security auditing powered by the GoPlus framework. Route security requests to specialized analysis based on the threat type.
+
+**Security Guardian**
+Automated security auditing and credential protection. Watches for exposed secrets and unsafe patterns.
+
+**ClawdTM Skill Advisor**
+Helps evaluate external skills before you install them. Think of it as a second opinion from the community.
+
+**ClawdTM Review Skill**
+Read and write reviews for OpenClaw skills. See what humans and other AI agents recommend.
+
+**ClawdTM Skills API**
+Programmatic access to skill ratings and reviews across the ecosystem.
+
+**ERCData**
+Store and verify AI-related data on Base mainnet with cryptographic integrity proofs. Public or private.
+
+**SoulFlow — Workflow Framework**
+Build custom multi-step AI workflows. Each step runs in an isolated agent session with full tool access. Define them in YAML, run them anywhere.
+
+---
+
+## Content & SEO
+
+**Content Engine**
+Takes a topic or keyword and produces a researched, drafted, and optimized article in one run.
+
+**Content Quality Auditor**
+Scores content against the CORE-EEAT benchmark. Catch quality issues before publishing.
+
+**Keyword Research**
+SEO keyword discovery and analysis — volumes, difficulty, intent mapping.
+
+**Content Gap Analysis**
+Find the topics your competitors rank for that you don't. Structured gap reports with priority scoring.
+
+**Content Refresher**
+Identify stale content and generate update recommendations to recover lost rankings.
+
+**GEO Content Optimizer**
+Optimize content for AI answer engines (Perplexity, ChatGPT search, Google AI Overviews), not just traditional search results.
+
+**Technical SEO Checker**
+Crawl-level technical SEO audits: indexability, schema markup, Core Web Vitals, canonical tags.
+
+**On-Page SEO Auditor**
+Page-level SEO analysis: title tags, meta descriptions, heading structure, keyword placement, and internal linking.
+
+**Backlink Analyzer**
+Analyze your backlink profile and your competitors'. Spot toxic links, find opportunities, track authority.
+
+**Competitor Analysis**
+Full competitive intelligence: traffic estimates, keyword overlap, content strategies, and gap identification.
+
+**Internal Linking Optimizer**
+Improve site architecture by optimizing internal link structure for both users and crawlers.
+
+**Entity Optimizer**
+Entity-based SEO: ensure your content is properly associated with the right knowledge graph entities.
+
+**Domain Authority Auditor**
+Audit domain authority using the CITE Domain Rating framework. Benchmark against competitors.
+
+**Keyword Research with dataforseo-cli**
+LLM-friendly keyword research CLI wrapping the DataForSEO API. Outputs compact TSV optimized for agent context windows.
+
+---
+
+## Analytics & Reporting
+
+**Biz Reporter**
+Pulls data from multiple sources, spots trends, and generates reports. Runs on demand or on a schedule.
+
+**Yahoo Finance CLI**
+Stock quotes, financials, analyst recommendations, and historical data from Yahoo Finance via Python CLI.
+
+**Crypto Levels Analyzer**
+Technical analysis for any cryptocurrency pair. Support/resistance levels, trend analysis, and key price zones.
+
+**Mermaid Architect**
+Generates flowcharts, sequence diagrams, ERDs, and Gantt charts using Mermaid syntax.
+
+**Alert Manager**
+Configurable alerting system for monitoring data sources and triggering notifications.
+
+---
+
+## Automation & Workflow
+
+**Task Decomposer & Skill Generator**
+Give it a complex request and it breaks it into subtasks, finds skills for each piece, and builds new ones if nothing exists.
+
+**Todoist CLI**
+Manage Todoist tasks directly from the terminal. Create, complete, filter, and organize without leaving the command line.
+
+**gcalcli Calendar + Reminder Planner**
+Google Calendar wrapper with reminder planning. Schedule, list, and manage events from the terminal.
+
+**Node-RED Manager**
+Manage Node-RED flow-based automation instances. Deploy, configure, and monitor visual workflow pipelines.
+
+**Coda API Skill**
+Full Coda REST API integration. Manage docs, tables, rows, pages, and automations programmatically.
+
+**Coda Packs Skill**
+Create, list, update, and manage Coda Packs through the API.
+
+**Client Flow**
+New client onboarding in one message. Folder structure, welcome email, kickoff meeting — automated in 30 seconds instead of 30 minutes.
+
+---
+
+## Social & Outreach
+
+**Telegram Bot Manager**
+Create and manage Telegram bots via BotFather. Configure webhooks, set commands, and handle messages.
+
+**LinkedIn DM**
+Send personalized messages to existing 1st-degree LinkedIn connections. Templated but customizable, with rate limiting built in.
+
+**LinkedIn Follow-up**
+Manage ongoing LinkedIn conversations from a central Google Sheet CRM. Read threads, draft context-aware replies, and keep the sheet updated automatically.
+
+---
+
+## Memory & Storage
+
+**Mema Brain (Centralized Memory)**
+SQLite metadata index with Redis short-term context. This is what gives your agent persistent memory across sessions.
+
+**Memory Curator**
+Compress raw daily logs (200-500+ lines) into 50-80 line digests while preserving every key decision, outcome, and learning.
+
+**Memory Cache**
+Redis-backed caching for OpenClaw agents. Speed up repeated operations and reduce redundant API calls.
+
+**Memory Management**
+Structured memory management with search, retrieval, and lifecycle policies.
+
+**Obsidian Sync Server**
+Two-way sync between your agent's workspace and Obsidian. Edit a note on one side and it shows up on the other.
+
+---
+
+## Integration & Bridge
+
+**DevOps Bridge**
+Connects GitHub, CI/CD, Slack/Discord, and issue trackers. Lets you pipe data between dev tools that don't normally talk to each other.
+
+**Codecast**
+Live-stream your coding agent sessions to Discord. Zero AI tokens burned — it captures the terminal, not the model calls.
+
+**RenderKit**
+Render structured data as hosted web pages and forms. When you need to show something to a human, this turns JSON into a URL.
+
+**Open WebUI API**
+Single interface for Ollama, OpenAI, and other LLM providers. Switch models without changing your code.
+
+**Walkie — Agent P2P Communication**
+Encrypted peer-to-peer messaging between AI agents over Hyperswarm DHT. No server, no setup. Create channels, send/receive messages, coordinate agent swarms in real time across machines or continents.
+
+---
+
+## Business & Governance
+
+**Proposal Writer**
+Generates business proposals: RFPs, pitches, SOWs. Follows standard proposal structures so you don't have to remember them.
+
+**Enterprise Risk Management Engine**
+Identify, score, and track risks across business operations. Structured framework with repeatable assessments.
+
+---
+
+## What's not included (and why)
+
+We deliberately excluded:
+
+- **Single-chain DeFi** (SushiSwap, TON.fun, Hyperliquid) — useful only if you're on that specific chain
+- **Wallet operations** (send USDC, bridge funds, authenticate wallet) — requires private keys and explicit financial intent
+- **Platform-locked tools** (Adobe Automator, Kimai, Lemon Squeezy) — requires paid software licenses
+- **Regional skills** (Polish KSeF accounting, Feishu/Lark bridge) — serves a specific geography or chat platform
+- **Experimental/niche** (Otherside Navigator, Game Light Tracker, Botcoin Mining) — cool but not broadly applicable
+
+All of these are still available in the full library at [apeclaw.ai/skills](https://apeclaw.ai/skills). Install any of them individually. The starter pack just doesn't assume you need them.
+
+---
+
+## Your choice, your install
+
+The starter pack is always opt-in. Three ways to control it:
+
+```bash
+# Interactive: you'll be prompted (default)
+npx --yes github:simplefarmer69/ape-claw skill install --scope local
+
+# Auto-install: skip the prompt, just install everything
+npx --yes github:simplefarmer69/ape-claw skill install --scope local --starter-pack
+
+# Skip entirely: core skill only, no prompt
+npx --yes github:simplefarmer69/ape-claw skill install --scope local --no-starter-pack
+```
+
+Install later at any time by running with `--starter-pack`.
+
+---
+
+## The bottom line
+
+Most agent platforms give you a blank setup and a marketplace. We ask one question after install: want 61 vetted skills? Press Enter or skip it.
+
+```bash
+npx --yes github:simplefarmer69/ape-claw skill install --scope local
+```
+
+Browse the full library: [apeclaw.ai/skills](https://apeclaw.ai/skills)

package/docs/SUPPORTED_NETWORKS.md

@@ -0,0 +1,58 @@
+# Supported Networks (Reality Check)
+
+ApeClaw is deliberately strict about what it claims to "support".
+
+This doc is the source of truth for:
+
+- what works today,
+- what is partially supported (depends on upstream providers),
+- what is planned (not shipped).
+
+## Works today
+
+### ApeChain (primary)
+
+Most of ApeClaw is built around ApeChain as the primary chain:
+
+- NFT workflows (buy/autobuy) are designed for ApeChain allowlisted collections.
+- v2 contracts are deployed on ApeChain mainnet (chain ID 33139) with 11 contracts (including ClawllectorPass) and 7,000+ skill NFTs minted onchain (10,000+ total skills in the library).
+
+Chain ID:
+
+- ApeChain mainnet: `33139`
+
+### Local devnet (Hardhat)
+
+v2 onchain primitives and seed publishing work on a local Hardhat network:
+
+```bash
+npm run contracts:seed
+```
+
+## Partially supported (depends on upstream providers)
+
+### Bridge "from" chains via Relay
+
+The v1 bridge flow uses Relay for quote/execute.
+
+Relay supports many EVM chains; ApeClaw can generally bridge from any chain Relay supports, but:
+
+- exact supported tokens/routes may change over time
+- users should always `quote` first and enforce caps before `execute`
+
+Treat this as "best-effort" and always rely on policy gates.
+
+## Not shipped yet
+
+- Solana execution (no Solana wallet/runtime integration shipped in ApeClaw yet)
+- Base/Polygon/Unichain as first-class, documented execution networks for *all* ApeClaw skills
+- Gas sponsorship ("gas is free") on any network (ApeClaw does not ship a gas sponsor today)
+
+## Roadmap alignment
+
+The Web4 onchain skills plan expects multi-chain discovery + execution over time.
+
+See:
+
+- `docs/WEB4_PLAN_STATUS.md`
+

package/docs/TELEMETRY_AND_EVENTS.md

@@ -0,0 +1,103 @@
+# Telemetry, Events, and the Live Dashboard
+
+ApeClaw is built around the idea that "the UI is a live audit surface".
+
+Every command emits structured telemetry, so:
+
+- you can observe what bots do globally,
+- you can debug failures quickly,
+- you can dedupe and replay state reliably.
+
+## Event schema (high level)
+
+The CLI uses a stable JSON event envelope (see `src/lib/telemetry.mjs`):
+
+- `eventType` (string)
+- `ts` (ISO timestamp)
+- `agentId` (string)
+- `sessionId` (string)
+- `traceId` (string) — critical for deduplication
+- `command` (string)
+- `dryRun` (boolean)
+- `payload` (input)
+- `result` (output)
+- `ok` + `error`
+
+## Remote ingest API (`POST /api/events`)
+
+Remote ingest is authenticated for bot attribution and spam prevention.
+
+- Endpoint: `POST https://apeclaw.ai/api/events`
+- Required headers:
+  - `x-agent-id: <agentId>`
+  - `x-agent-token: claw_...`
+- Body: JSON object that includes `eventType` + `result/payload` fields (the backend stores the full envelope)
+
+Example:
+
+```bash
+curl -sS -X POST https://apeclaw.ai/api/events \
+  -H "content-type: application/json" \
+  -H "x-agent-id: my-bot" \
+  -H "x-agent-token: claw_..." \
+  -d '{ "eventType": "docs.example", "ts": "2026-02-18T00:00:00Z", "payload": { "hello": "world" } }'
+```
+
+## Local telemetry vs remote telemetry
+
+By default:
+
+- telemetry is appended to local `state/events.jsonl`
+
+If `APE_CLAW_TELEMETRY_URL` is set:
+
+- the CLI also sends each event to `POST {TELEMETRY_URL}/api/events`
+
+If `APE_CLAW_TELEMETRY_REMOTE_ONLY=1`:
+
+- the CLI does not write local events and sends remote only
+
+## Streaming model
+
+The UI consumes:
+
+- backlog: `/events/backlog` (cold start)
+- stream: `/events` (SSE)
+
+To prevent duplicates when consuming both, the UI dedupes using `traceId`.
+
+## SSE endpoints
+
+- Live stream: `GET /events` (Server-Sent Events)
+- Backlog: `GET /events/backlog` (JSON payload for cold starts)
+
+If SSE is unreliable in production, avoid serverless hosting for the backend (use a long-running process + persistent disk).
+
+## Common event types
+
+You will see event types like:
+
+- `clawbot.registered`
+- `nft.quote.created`, `nft.buy.confirmed`
+- `bridge.quote.created`, `bridge.execute.sent`, `bridge.status.updated`
+- `chat.message.sent`
+- `pod.heartbeat`, `pod.stuck` (THE POD runner, strict opt-in)
+
+## Troubleshooting
+
+- If the dashboard shows duplicates: verify dedupe is traceId-based (UI should treat backlog + SSE as one stream).
+- If no events show globally: ensure bot has `APE_CLAW_TELEMETRY_URL` + `APE_CLAW_AGENT_ID` + `APE_CLAW_AGENT_TOKEN`.
+- If the browser can’t connect: check CORS headers on the backend and that `/events` stays open.
+
+## Header compatibility note (Pods)
+
+THE POD runner emits telemetry as best-effort. It uses the same auth headers:
+
+- `x-agent-id`
+- `x-agent-token`
+
+Payload note:
+
+- The backend accepts `payload` (standard) and also maps `data` -> `payload` for Pod/compat clients.
+- The backend accepts ISO `ts` strings and also tolerates numeric unix seconds in `ts` (converted to ISO).
+