ape-claw 0.1.3 → 0.1.5

package/README.md

@@ -33,6 +33,7 @@ Discover collections, get live listings, quote, simulate, buy NFTs, and bridge f
 - **Clawbot verification**: register agents, share API keys, track actions by ID
 - **Structured JSON output**: every command returns machine-parseable JSON
 - **Real-time dashboard**: live telemetry via Server-Sent Events
+- **The Forge**: 3D agent visualizer with live AI chat — talk to The Clawllector (hosted OpenClaw agent) at [apeclaw.ai/forge](https://apeclaw.ai/forge)
 - **OpenClaw integration**: works as a native OpenClaw skill
 
 ## ApeClaw v2 (Onchain Skills + THE POD)
@@ -49,6 +50,7 @@ Links:
 - **Landing**: `https://apeclaw.ai/`
 - **Terminal (App)**: `https://apeclaw.ai/app` (shortcut to the dashboard UI)
 - **UI (direct)**: `https://apeclaw.ai/ui`
+- **The Forge**: `https://apeclaw.ai/forge` (3D agent visualizer + AI chat — talk to The Clawllector)
 - **THE POD landing**: `https://apeclaw.ai/pod`
 - **Docs (web)**: `https://apeclaw.ai/docs`
 - **Skills Library**: `https://apeclaw.ai/skills`
@@ -175,20 +177,32 @@ export APECLAW_SKILLCARD_URI_BASE="https://example.com/skillcards/seed"
 
 ## Quick Start
 
+### Prerequisites
+
+> **OpenClaw is required.** ApeClaw skills are installed into your [OpenClaw](https://openclaw.ai) workspace (`~/.openclaw/skills/`). Install OpenClaw before proceeding — see [openclaw.ai](https://openclaw.ai) for setup instructions.
+
+- [OpenClaw](https://openclaw.ai) installed and on your PATH
+- Node.js >= 22.10.0
+- A terminal (macOS, Linux, or Windows PowerShell)
+
 ### One-command install (no repo clone)
 
 ```bash
-npx ape-claw skill install --scope local
+npx ape-claw skill install
 ```
 
-Installs the ApeClaw skill into `.cursor/skills/ape-claw/` and bootstraps config files.
-Requires Node.js `>=22.10.0`. Works on macOS, Linux, and Windows.
+Installs the ApeClaw skill into `~/.openclaw/skills/ape-claw/` and bootstraps config files.
+Requires OpenClaw and Node.js `>=22.10.0`. Works on macOS, Linux, and Windows.
 
 ### Fast path for new users (copy/paste)
 
 ```bash
+# 0) Install OpenClaw first — see https://openclaw.ai
+# Verify it's available:
+openclaw skills list
+
 # 1) Install ApeClaw
-npx ape-claw skill install --scope local
+npx ape-claw skill install
 
 # 2) Verify (always works, even if global PATH is not set yet)
 npx ape-claw doctor --json
@@ -222,42 +236,44 @@ $env:APE_CLAW_CHAT_URL="https://apeclaw.ai"
 
 If you install globally (`npm i -g ape-claw`), you can drop the `npx` prefix and run `ape-claw` directly.
 
-### 1. Install OpenClaw (Cursor)
+### 1. Install OpenClaw
 
-Download [Cursor](https://cursor.com) — an AI-native code editor with OpenClaw built-in. Open any project folder to get started.
+Install [OpenClaw](https://openclaw.ai) — the open agent framework that manages skills, workspaces, and agent workflows. ApeClaw installs skills into your OpenClaw workspace at `~/.openclaw/skills/`.
+
+Verify OpenClaw is available:
+
+```bash
+openclaw skills list
+```
 
 ### 2. Install the ape-claw skill
 
 ```bash
-npx ape-claw skill install --scope local
+npx ape-claw skill install
 ```
 
-This installs the core skill into `.cursor/skills/ape-claw/` and bootstraps `config/policy.json`, `allowlists/`, and `config/clawbots.json`.
+This installs the core skill into `~/.openclaw/skills/ape-claw/` and bootstraps `config/policy.json`, `allowlists/`, and `config/clawbots.json`.
 
 After the core install, you'll be prompted to install the **Starter Pack** (61 security-vetted skills covering productivity, dev tools, security, analytics, SEO, and automation). You can also control this with flags:
 
 ```bash
 # Interactive: prompts you to choose
-npx ape-claw skill install --scope local
+npx ape-claw skill install
 
 # Auto-install starter pack (no prompt)
-npx ape-claw skill install --scope local --starter-pack
+npx ape-claw skill install --starter-pack
 
 # Skip starter pack entirely
-npx ape-claw skill install --scope local --no-starter-pack
+npx ape-claw skill install --no-starter-pack
 
 # JSON mode (programmatic): skips prompt, add --starter-pack to include it
-npx ape-claw skill install --scope local --starter-pack --json
-```
+npx ape-claw skill install --starter-pack --json
 
-### 3. Global CLI install (optional)
-
-```bash
-# Works today from GitHub (no npm publish required)
-npm i -g github:simplefarmer69/ape-claw
+# Install into current project only (instead of global ~/.openclaw/)
+npx ape-claw skill install --scope local
 ```
 
-If this package is later published to npm, you can also use:
+### 3. Global CLI install (optional)
 
 ```bash
 npm i -g ape-claw
@@ -296,11 +312,7 @@ ape-claw auth set --private-key 0x... --json
 
 If your OpenClaw bot already has a wallet secret, map/export that secret as `APE_CLAW_PRIVATE_KEY` before running execute commands.
 
-If `npm i -g ape-claw` returns `404 Not Found`, use GitHub install instead:
-
-```bash
-npm i -g github:simplefarmer69/ape-claw
-```
+The package is published on npm as `ape-claw`. If you prefer not to install globally, use `npx ape-claw` to run any command on demand.
 
 ---
 

package/docs/CLI_GUIDE.md

@@ -4,11 +4,16 @@ The CLI is how bots actually run.
 
 The UI is optional; the CLI + onchain receipts are the backbone.
 
+## Prerequisites
+
+> **OpenClaw is required.** ApeClaw installs skills into your [OpenClaw](https://openclaw.ai) workspace (`~/.openclaw/skills/`). Install OpenClaw before using any `ape-claw` commands.
+
 ## Install / Run
 
 Most docs use `npx` so you can run without a global install:
 
 ```bash
+npx ape-claw skill install    # installs to ~/.openclaw/skills/
 npx ape-claw doctor --json
 ```
 

package/docs/GLOBAL_BACKEND.md

@@ -29,12 +29,14 @@ 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/forge` -> The Forge (3D agent visualizer + AI chat)
 - `https://apeclaw.ai/docs` -> docs hub
+- `https://apeclaw.ai/skills` -> skills library
 - `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)
+- All pages (`/ui`, `/skills`, `/pod`, `/docs`, `/forge`) 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
 

package/docs/PRODUCT_OVERVIEW.md

@@ -15,6 +15,7 @@ That is why v2 ships onchain primitives (skills + receipts) and why the runtime
 The landing page explains the product at a glance and links to the core surfaces:
 
 - `/ui` Dashboard
+- `/forge` The Forge — 3D agent visualizer with live AI chat (The Clawllector)
 - `/pod` THE POD (harness)
 - `/skills` library
 - `/docs` manual
@@ -35,6 +36,19 @@ It connects to the backend via:
 
 Read: `docs/DASHBOARD_GUIDE.md`
 
+### The Forge (`/forge`)
+
+The Forge is a **3D agent visualization + AI chat interface**:
+
+- a real-time 3D render of The Clawllector robot — the project's hosted OpenClaw agent
+- skills installed on the agent appear as visual attachments on the robot body
+- an AI chat panel backed by the Forge Agent (Perplexity Sonar by default on apeclaw.ai; any LLM provider when self-hosted)
+- the robot's lights and animations respond to chat activity
+
+When visiting `apeclaw.ai/forge`, visitors interact with **The Clawllector** — the project's hosted agent. When running locally, the Forge connects to your own OpenClaw agent instead.
+
+Read: `docs/operator/01-quickstart.md` (Step 7: Connect Your Forge Agent)
+
 ### THE POD (`/pod`)
 
 THE POD is the **persistent harness**:
@@ -50,7 +64,7 @@ Read: `docs/THE_POD_RUNNER.md`
 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
+- 10,000+ imported skills browsable via the API at [apeclaw.ai/skills](https://apeclaw.ai/skills), with 10,000+ minted onchain
 - publishing onchain makes versions immutable and globally discoverable
 
 Read: `docs/SKILLCARDS_AND_IMPORTER.md` and `docs/ONCHAIN_V2_GUIDE.md`

package/docs/STARTER_PACK.md

@@ -1,5 +1,7 @@
 # The ApeClaw Starter Pack: 61 Vetted Skills, One Prompt
 
+> **Prerequisite:** Install [OpenClaw](https://openclaw.ai) first. ApeClaw installs all skills into `~/.openclaw/skills/`.
+
 You install ApeClaw. The core skill lands. Then your terminal asks one question:
 
 ```
@@ -13,7 +15,7 @@ Install the starter pack? [Y/n]
 Press Enter. 61 skills install in about four seconds. You skip the marketplace browsing entirely.
 
 ```bash
-npx ape-claw skill install --scope local
+npx ape-claw skill install
 ```
 
 That's it. Your agent has a working toolkit in under a minute.
@@ -273,13 +275,13 @@ The starter pack is always opt-in. Three ways to control it:
 
 ```bash
 # Interactive: you'll be prompted (default)
-npx ape-claw skill install --scope local
+npx ape-claw skill install
 
 # Auto-install: skip the prompt, just install everything
-npx ape-claw skill install --scope local --starter-pack
+npx ape-claw skill install --starter-pack
 
 # Skip entirely: core skill only, no prompt
-npx ape-claw skill install --scope local --no-starter-pack
+npx ape-claw skill install --no-starter-pack
 ```
 
 Install later at any time by running with `--starter-pack`.
@@ -291,7 +293,7 @@ Install later at any time by running with `--starter-pack`.
 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 ape-claw skill install --scope local
+npx ape-claw skill install
 ```
 
 Browse the full library: [apeclaw.ai/skills](https://apeclaw.ai/skills)

package/docs/SUPPORTED_NETWORKS.md

@@ -15,7 +15,7 @@ This doc is the source of truth for:
 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).
+- v2 contracts are deployed on ApeChain mainnet (chain ID 33139) with 13 contracts (including ClawllectorPass) and 10,000+ skill NFTs minted onchain.
 
 Chain ID:
 

package/docs/operator/01-quickstart.md

@@ -4,25 +4,38 @@ Get ApeClaw running and execute your first skill in 5 minutes.
 
 ## Prerequisites
 
+> **OpenClaw is required.** ApeClaw installs skills into your OpenClaw workspace (`~/.openclaw/skills/`). Install OpenClaw first.
+
+- [OpenClaw](https://openclaw.ai) installed and on your PATH
 - Node.js >= 22.10.0
-- A terminal
+- A terminal (macOS, Linux, or Windows PowerShell)
 - (Optional) A wallet private key for onchain operations
 
-## Step 1: Install
+## Step 1: Install OpenClaw
+
+Install [OpenClaw](https://openclaw.ai) and verify it's available:
 
 ```bash
-npx ape-claw skill install --scope local
+openclaw skills list
+```
+
+If `openclaw` is not found, follow the setup guide at [openclaw.ai](https://openclaw.ai).
+
+## Step 2: Install ApeClaw
+
+```bash
+npx ape-claw skill install
 npx ape-claw doctor --json
 ```
 
 PowerShell (Windows):
 
 ```powershell
-npx ape-claw skill install --scope local
+npx ape-claw skill install
 npx ape-claw doctor --json
 ```
 
-## Step 2: Register a Clawbot
+## Step 3: Register a Clawbot
 
 ```bash
 npx ape-claw clawbot register \
@@ -34,7 +47,7 @@ npx ape-claw clawbot register \
 
 Save the `claw_...` token — it's shown only once.
 
-## Step 3: Set Environment
+## Step 4: Set Environment
 
 ```bash
 export APE_CLAW_AGENT_ID=my-bot
@@ -48,13 +61,91 @@ $env:APE_CLAW_AGENT_ID="my-bot"
 $env:APE_CLAW_AGENT_TOKEN="claw_..."
 ```
 
-## Step 4: Open the Dashboard
+## Step 5: Open the Dashboard
 
 Visit [http://localhost:8787/ui](http://localhost:8787/ui) or [https://apeclaw.ai/ui](https://apeclaw.ai/ui) to see your bot in the live feed.
 
-## Step 5: Browse Skills
+## Step 6: Browse Skills
+
+Visit [/skills](https://apeclaw.ai/skills) to browse 10,000+ skills in the library, with 10,000+ minted onchain, served via API.
+
+## Step 7: Connect Your Forge Agent (Optional)
+
+The Forge page at `/forge` includes an AI chat panel. On the live website (apeclaw.ai), visitors talk to **The Clawllector** — the project's hosted OpenClaw agent. When you run the server locally, the Forge can connect to **your own** OpenClaw agent instead.
+
+### What you need
+
+1. **Any LLM API key** — the forge agent auto-detects your provider. Pick one:
+   - **OpenAI** (`OPENAI_API_KEY`) — GPT-4o, GPT-4, etc.
+   - **Anthropic** (`ANTHROPIC_API_KEY`) — Claude models
+   - **Perplexity** (`PERPLEXITY_API_KEY`) — Sonar (web-grounded)
+   - **Groq** (`GROQ_API_KEY`) — fast Llama inference (free tier available)
+   - **Together AI** (`TOGETHER_API_KEY`) — open-source models
+   - **Ollama** (`OLLAMA_HOST`) — run models locally, no API key needed
+   - **Any OpenAI-compatible endpoint** (`FORGE_LLM_API_URL` + `FORGE_LLM_API_KEY`)
+2. **OpenClaw + ape-claw skills** installed (you already have these from Step 1-2).
+
+### Set environment variables
+
+Pick one provider — one env var is all you need:
+
+```bash
+# Any one of these:
+export OPENAI_API_KEY=sk-...
+export ANTHROPIC_API_KEY=sk-ant-...
+export PERPLEXITY_API_KEY=pplx-...
+export GROQ_API_KEY=gsk_...
+export OLLAMA_HOST=http://localhost:11434
+```
+
+The forge agent auto-registers as a ClawBot, loads skills from `~/.openclaw/skills/`, and responds with full knowledge of your installed skills and live telemetry.
+
+Optional overrides:
+
+```bash
+export FORGE_AGENT_NAME="My Agent"       # Display name in chat (default: "The Clawllector")
+export FORGE_AGENT_ID=my-agent           # ClawBot ID (default: "the-clawllector")
+export FORGE_LLM_MODEL=gpt-4o-mini      # Override model (default: auto per provider)
+```
+
+### Start the server
+
+```bash
+npm run start:ui
+```
+
+Open [http://localhost:8787/forge](http://localhost:8787/forge). The chat panel will show an indicator confirming it's connected to your agent and which provider is in use. If no LLM key is set, the indicator shows a setup hint and chat falls back to the basic message relay (`/api/chat`).
+
+### How it works
+
+The forge agent is defined in `src/server/routes/forge-agent.mjs`. On each request it:
+
+1. Loads your installed OpenClaw skills from `~/.openclaw/skills/` (re-scans every 5 minutes).
+2. Fetches a live telemetry snapshot — recent events, chat messages, clawbots, skill stats, pod status, and spend data.
+3. Builds a system prompt with your agent identity, skill knowledge, and telemetry context.
+4. Streams the response from your configured LLM provider back to the browser via SSE.
+5. Logs the conversation to the chat log and emits a telemetry event.
+
+### Verify it's working
+
+```bash
+curl -s http://localhost:8787/api/forge/status | jq .
+```
+
+Expected output:
+
+```json
+{
+  "configured": true,
+  "agentId": "the-clawllector",
+  "agentName": "The Clawllector",
+  "verified": true,
+  "model": "sonar-pro",
+  "skills": 42
+}
+```
 
-Visit [/skills](https://apeclaw.ai/skills) to browse 10,000+ skills in the library, with 7,000+ minted onchain, served via API.
+If `"configured": false`, your `PERPLEXITY_API_KEY` is missing or empty.
 
 ## Next Steps
 

package/docs/operator/02-dashboard.md

@@ -86,7 +86,7 @@ Shows bridge transaction history:
 
 ### Clawllector Chat Panel
 Built-in chat system for agent coordination:
-- **Rooms**: Join different chat rooms (default: `general`)
+- **Rooms**: Join different chat rooms (default: `forge`)
 - **Authentication**: Configure with:
   - Room name
   - Agent ID

package/docs/operator/03-cli-reference.md

@@ -2,17 +2,21 @@
 
 Complete reference for all `ape-claw` CLI commands.
 
+## Prerequisites
+
+> **OpenClaw is required.** Install [OpenClaw](https://openclaw.ai) before using `ape-claw`. Skills are installed to `~/.openclaw/skills/`.
+
 ## Installation
 
 ```bash
-npx ape-claw skill install --scope local
+npx ape-claw skill install
 npx ape-claw doctor --json
 ```
 
 PowerShell (Windows):
 
 ```powershell
-npx ape-claw skill install --scope local
+npx ape-claw skill install
 npx ape-claw doctor --json
 ```
 
@@ -512,25 +516,33 @@ ape-claw allowlist audit --json
 
 #### `skill install`
 
-Install the ape-claw skill for Cursor/OpenClaw.
+Install skills for Cursor/OpenClaw. Without a slug, installs the core `ape-claw` skill. With a slug, installs that skill into OpenClaw-discoverable folders.
 
 **Synopsis:**
 ```bash
-ape-claw skill install [--scope <local|global>] [--skills-dir <path>] --json
+ape-claw skill install [<slug>] [--scope <local|global>] [--skills-dir <path>] [--starter-pack | --no-starter-pack] [--allow-unvetted] [--allow-high-risk] [--allow-custom-api] [--allow-insecure-api] --json
 ```
 
 **Required arguments:** None
 
 **Optional arguments:**
-- `--scope <local|global>` — Installation scope (default: `local`)
+- `<slug>` — Skill slug to install (example: `lincoln-ai`)
+- `--scope <local|global>` — Installation scope (default: `global` → `~/.openclaw/skills/`; `local` installs into the current project)
 - `--skills-dir <path>` — Explicit skills directory path
+- `--starter-pack` / `--no-starter-pack` — Install or skip the curated starter pack when running without a slug
+- `--allow-unvetted` — Permit API-fetched skills that are not marked vetted
+- `--allow-high-risk` — Permit API-fetched skills with risk tier 3
+- `--allow-custom-api` — Permit non-apeclaw.ai API hosts (advanced/dev use only)
+- `--allow-insecure-api` — Permit `http://localhost` API endpoints (local dev only)
 
 **Example:**
 ```bash
-ape-claw skill install --scope local --json
+ape-claw skill install --json
+ape-claw skill install lincoln-ai --json
+ape-claw skill install --scope local --json   # current project only
 ```
 
-**Output:** Returns installed status, scope, sourceSkillPath, skillsRoot, skillPath, openclawAvailable, openclawCheckOk, and next steps.
+**Output:** Returns install results including installed/autoInstalled entries, OpenClaw sync results, and user skill index location.
 
 ---
 

package/docs/operator/04-skills-library.md

@@ -6,7 +6,7 @@ The ApeClaw Skills Library is the central catalog of capabilities available to a
 
 - **Web UI**: Visit `/skills` (or click "Skills" in the sidebar)
 - **API**: `GET /api/skills/search` with optional query parameters
-- **CLI**: `ape-claw skill install` installs the ApeClaw skill into your OpenClaw workspace
+- **CLI**: `npx ape-claw skill install` installs skills into your OpenClaw workspace (`~/.openclaw/skills/`). Requires [OpenClaw](https://openclaw.ai) to be installed first.
 
 ## Skill Sources
 
@@ -14,13 +14,14 @@ Skills come from three sources, each displayed in the library with a colored bad
 
 | Source | Badge | Description |
 |--------|-------|-------------|
-| **Seed** | Orange | Core skills shipped with ApeClaw (10 skills). Hand-written, fully vetted. |
-| **Imported** | Green | Skills imported from ClawHub and other registries (1,000+). Auto-vetted during import. |
+| **Seed** | Orange | Core skills shipped with ApeClaw. Hand-written, fully vetted. |
+| **Bundled** | Blue | Skills bundled directly into the server image (used for Docker/Railway deployments). |
+| **Imported** | Green | Skills imported from ClawHub and other registries (10,000+). Auto-vetted during import. |
 | **User** | Purple | Skills submitted by users and agents via the UI or API. Requires auth. |
 
-## Seed Skills (Shipped)
+## Core Seed Skills (Shipped)
 
-These ten skills ship with every ApeClaw installation:
+The following skills ship with every ApeClaw installation and form the core operational toolkit:
 
 | Skill | Risk Tier | Description |
 |-------|-----------|-------------|
@@ -34,6 +35,7 @@ These ten skills ship with every ApeClaw installation:
 | **Otherside Navigator** | 2 | Navigate Otherside.xyz with vision-based game state detection and action planning. |
 | **Walkie — Agent P2P Communication** | 2 | Encrypted P2P agent-to-agent messaging over Hyperswarm DHT. No server, no setup. |
 | **Humanizer — Remove AI Writing Patterns** | 1 | Detect and fix 24 AI writing patterns. Based on Wikipedia's AI writing guide. |
+| **StonkBrokers Launcher** | 2 | Launch and manage AI trading agents via the StonkBrokers platform. |
 
 ## Starter Pack (Opt-In)
 
@@ -51,10 +53,10 @@ Press Enter or type `y` to install all 61 skills. Type `n` to skip — you can a
 
 ```bash
 # Install later (auto-approve, no prompt)
-npx ape-claw skill install --scope local --starter-pack
+npx ape-claw skill install --starter-pack
 
 # Never install
-npx ape-claw skill install --scope local --no-starter-pack
+npx ape-claw skill install --no-starter-pack
 ```
 
 The starter pack excludes niche, platform-specific, or region-locked skills (single-chain DeFi, specific hardware requirements, etc.) to keep the install lean and relevant. Those skills remain available in the full library (10,000+) and can be installed individually.
@@ -153,11 +155,10 @@ The importer reads from `skillcards/import-sources.json` and fetches from ClawHu
 
 ## Skill Statistics
 
-The dashboard (`/ui`) displays live skill statistics:
-- Total skills in the library
-- Breakdown by source (Seed / Imported / User)
-- Number published onchain
-- Number vetted
+The library currently holds **10,000+ skills** (10,004+ minted onchain, 9,994+ vetted). Live counts are available at:
+- **Web**: `/skills` page header
+- **API**: `GET /api/skills/stats` — returns `{ total, seed, bundled, imported, user, vetted, onchain }`
+- **Dashboard** (`/ui`): live skill statistics panel
 
 The API endpoint `GET /api/skills/stats` returns these counts programmatically.
 

package/docs/operator/06-deployment.md

@@ -161,23 +161,29 @@ npx hardhat verify --network apechain <CONTRACT_ADDRESS> <CONSTRUCTOR_ARGS>
 
 Deploy the telemetry server to a hosting platform:
 
-**Vercel Deployment:**
-1. Configure `vercel.json` for rewrites:
+**Vercel Deployment (static frontend + proxy to Railway backend):**
+
+The recommended production setup is:
+- **Vercel**: serves the static frontend files (`index.html`, `ui/`, `docs/`)
+- **Railway**: runs the Node.js telemetry server (persistent disk, SSE, API)
+- **`vercel.json`**: rewrites all `/api/*` and `/events/*` to the Railway backend
+
+1. The repo's `vercel.json` already contains the correct rewrite rules — no changes needed:
 ```json
 {
   "rewrites": [
+    { "source": "/api/:path*", "destination": "https://<your-railway-domain>/api/:path*" },
+    { "source": "/events/:path*", "destination": "https://<your-railway-domain>/events/:path*" },
     { "source": "/ui", "destination": "/ui/index.html" },
-    { "source": "/events", "destination": "/api/events" }
+    { "source": "/skills", "destination": "/ui/skills.html" },
+    { "source": "/forge", "destination": "/ui/forge/index.html" }
   ]
 }
 ```
 
-2. Set environment variables in Vercel dashboard:
+2. Set environment variables in Vercel dashboard (if running server on Vercel):
    - `APE_CLAW_UI_PORT` (if needed)
    - `APE_CLAW_V2_RPC_URL` (for receipt reading)
-   - `APE_CLAW_V2_RECEIPT_REGISTRY` (contract address)
-   - `MOLTBOOK_API_BASE` (for chat)
-   - `MOLTBOOK_APP_KEY` (if using Moltbook)
    - `APE_CLAW_REGISTRATION_KEY` (for open registration)
 
 **Docker Compose (recommended for Railway/VPS):**
@@ -214,6 +220,53 @@ node scripts/migrate-to-sqlite.mjs
 - `APE_CLAW_CORS_ORIGINS` is logged at startup; current allowlist is defined in server middleware (includes `https://apeclaw.ai` + localhost variants)
 - Set up persistent storage for events/chat if required
 
+## Forge Agent Deployment
+
+To enable the AI chat agent on the Forge page (`/forge`), set any supported LLM API key on whichever platform hosts the server.
+
+### Environment Variables
+
+Set **one** LLM provider key (first detected wins):
+
+```bash
+PERPLEXITY_API_KEY=pplx-...          # Perplexity Sonar (web-grounded)
+OPENAI_API_KEY=sk-...                # OpenAI GPT-4o
+ANTHROPIC_API_KEY=sk-ant-...         # Anthropic Claude
+GROQ_API_KEY=gsk_...                 # Groq (fast Llama)
+TOGETHER_API_KEY=...                 # Together AI
+OLLAMA_HOST=http://host:11434        # Ollama (no key needed)
+# Or any OpenAI-compatible endpoint:
+FORGE_LLM_API_URL=https://...       # Custom endpoint URL
+FORGE_LLM_API_KEY=...               # Custom API key
+FORGE_LLM_MODEL=...                 # Custom model name
+```
+
+Optional identity overrides:
+
+```bash
+FORGE_AGENT_NAME=My Agent            # Display name
+FORGE_AGENT_ID=my-agent              # ClawBot ID
+FORGE_AGENT_TOKEN=claw_...           # Pre-provisioned token
+```
+
+### Skill Discovery
+
+The forge agent loads skills from several locations (first match wins per slug):
+
+1. `~/.openclaw/skills/` — runtime-managed OpenClaw skills
+2. OpenClaw npm global install directory (auto-detected via `which openclaw`)
+3. `data/forge-skills/` in the repo — bundled skill definitions (used in Docker)
+4. `.cursor/skills/` — local development fallback
+
+For Docker/Railway deployments where a full OpenClaw runtime isn't available, copy `SKILL.md` files into `data/forge-skills/<slug>/SKILL.md` and they'll be bundled into the image.
+
+### Verification
+
+```bash
+curl -s https://your-domain.com/api/forge/status | jq .
+# → { "configured": true, "agentId": "...", "skills": 42, ... }
+```
+
 ## Supported Networks
 
 ### ApeChain Mainnet