ape-claw 0.1.6 → 0.1.8

package/README.md

@@ -188,11 +188,12 @@ export APECLAW_SKILLCARD_URI_BASE="https://example.com/skillcards/seed"
 ### One-command install (no repo clone)
 
 ```bash
-npx ape-claw skill install
+npx --yes ape-claw@latest skill install
 ```
 
 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.
+During install, ApeClaw also prompts to enable the local Forge dashboard upgrade path.
 
 ### Fast path for new users (copy/paste)
 
@@ -201,8 +202,11 @@ Requires OpenClaw and Node.js `>=22.10.0`. Works on macOS, Linux, and Windows.
 # Verify it's available:
 openclaw skills list
 
-# 1) Install ApeClaw
-npx ape-claw skill install
+# 1) Install ApeClaw (force latest npm release)
+npx --yes ape-claw@latest skill install
+
+# 1b) Open local Forge dashboard (starts local server if needed)
+npx --yes ape-claw@latest dashboard
 
 # 2) Verify (always works, even if global PATH is not set yet)
 npx ape-claw doctor --json
@@ -258,21 +262,25 @@ After the core install, you'll be prompted to install the **Starter Pack** (61 s
 
 ```bash
 # Interactive: prompts you to choose
-npx ape-claw skill install
+npx --yes ape-claw@latest skill install
 
 # Auto-install starter pack (no prompt)
-npx ape-claw skill install --starter-pack
+npx --yes ape-claw@latest skill install --starter-pack
 
 # Skip starter pack entirely
-npx ape-claw skill install --no-starter-pack
+npx --yes ape-claw@latest skill install --no-starter-pack
 
 # JSON mode (programmatic): skips prompt, add --starter-pack to include it
-npx ape-claw skill install --starter-pack --json
+npx --yes ape-claw@latest skill install --starter-pack --json
 
 # Install into current project only (instead of global ~/.openclaw/)
-npx ape-claw skill install --scope local
+npx --yes ape-claw@latest skill install --scope local
 ```
 
+The same install flow also prompts for the local Forge dashboard upgrade.  
+Use `npx --yes ape-claw@latest dashboard` anytime as the stable local Forge entrypoint.
+If you see `Unknown command: dashboard`, you are running an older cached package — re-run with `npx --yes ape-claw@latest ...`.
+
 ### 3. Global CLI install (optional)
 
 ```bash
@@ -556,6 +564,15 @@ Then open `http://localhost:8787/` for the real-time dashboard showing:
 - Bridge operation status
 - Connection health
 
+For local Forge/OpenClaw takeover dashboard (no repo clone required), run:
+
+```bash
+npx ape-claw dashboard
+```
+
+This starts the packaged local UI server from npm and opens Forge.  
+GitHub clone + `npm run start:ui` is optional for development workflows.
+
 ### Clawllector Chat API
 
 Verified clawbots can chat with each other through the telemetry server.
@@ -800,6 +817,138 @@ The CLI auto-retries "Order not found" errors up to 3 times by fetching fresh li
 
 ---
 
+## Troubleshooting
+
+### `openclaw: command not found` after install
+
+The OpenClaw installer may not update your shell PATH automatically. Fix:
+
+```bash
+mkdir -p "$HOME/.npm-global"
+npm config set prefix "$HOME/.npm-global"
+npm install -g openclaw@latest
+export PATH="$HOME/.npm-global/bin:$PATH"
+rehash   # zsh only
+```
+
+Add the `export PATH` line to `~/.zshrc` (or `~/.bashrc`) to make it permanent.
+
+### `Unknown command: dashboard`
+
+You are running a stale cached version of `ape-claw`. Force the latest:
+
+```bash
+rm -rf ~/.npm/_npx
+npm cache verify
+npx --yes ape-claw@latest dashboard
+```
+
+Always use `npx --yes ape-claw@latest` (not just `npx ape-claw`) for fresh installs.
+
+### OpenClaw gateway not starting / `openclaw.json` missing
+
+If `openclaw gateway start` fails silently after a fresh install, generate the config first:
+
+```bash
+openclaw onboard --non-interactive --accept-risk --auth-choice skip --install-daemon --skip-channels --skip-skills --skip-ui --json
+openclaw gateway start
+```
+
+The `dashboard` command does this automatically, but running it manually helps if the gateway service is stuck.
+
+### `Disconnected from gateway: device token mismatch` or `pairing required`
+
+After reinstalling or regenerating OpenClaw config, the CLI may have a stale device token. Approve the pending pairing request:
+
+```bash
+# List pending requests
+openclaw devices list
+
+# Approve the pending request (copy the Request ID from the Pending table)
+openclaw devices approve <request-id>
+```
+
+The `ape-claw dashboard` command auto-detects and approves pending pairings, but if you see this on the native OpenClaw dashboard, approve manually as shown above.
+
+### Forge chat returns `Error: internal error`
+
+This usually means the OpenClaw gateway cannot reach its configured LLM. Common causes:
+
+1. **Wrong model for your API key**: OpenClaw defaults to `anthropic/claude-opus-4-6`. If you only have an OpenAI key:
+   ```bash
+   openclaw config set agents.defaults.model.primary "openai/gpt-4o"
+   openclaw gateway restart
+   ```
+
+2. **Invalid API key saved**: Check `~/.openclaw/.env` — the `OPENAI_API_KEY` value should start with `sk-`. If it looks like garbage, re-enter it.
+
+3. **Gateway pairing issue**: The Forge backend calls `openclaw agent` which needs a paired device:
+   ```bash
+   openclaw devices pair --auto-approve
+   ```
+
+### Forge page loads but chat says `Forge agent not configured`
+
+The Forge reads LLM keys from OpenClaw's config, not its own env. Make sure you have a key in `~/.openclaw/.env`:
+
+```bash
+echo 'OPENAI_API_KEY=sk-your-key-here' >> ~/.openclaw/.env
+```
+
+Then set the matching model:
+
+```bash
+openclaw config set agents.defaults.model.primary "openai/gpt-4o"
+openclaw gateway restart
+```
+
+### `localhost:8787` not loading (Forge server)
+
+On macOS, `localhost` may resolve to IPv6 (`::1`) while the server binds to IPv4. Use `http://127.0.0.1:8787/forge` instead. The latest version binds to `0.0.0.0` by default, fixing this.
+
+### `.zshrc` parse error on shell startup
+
+If you see `parse error near 'fi'` or similar, the OpenClaw installer may have left a stale snippet. Edit `~/.zshrc`, remove the broken block, and make the OpenClaw completion line conditional:
+
+```bash
+if [ -f "$HOME/.openclaw/completions/openclaw.zsh" ]; then
+  source "$HOME/.openclaw/completions/openclaw.zsh"
+fi
+```
+
+### Fresh install checklist (zero to working Forge)
+
+```bash
+# 1. Install OpenClaw
+curl -fsSL https://openclaw.ai/install.sh | bash
+export PATH="$HOME/.npm-global/bin:$PATH"
+rehash   # zsh only
+
+# 2. Onboard + start gateway
+openclaw onboard --non-interactive --accept-risk \
+  --auth-choice skip --install-daemon \
+  --skip-channels --skip-skills --skip-ui --json
+openclaw gateway install
+# Wait a few seconds for the gateway service to start, then approve pairing:
+sleep 5
+openclaw devices list
+# Copy the Request ID from the Pending table, then:
+openclaw devices approve <request-id>
+
+# 3. Set your LLM key
+echo 'OPENAI_API_KEY=sk-your-key-here' >> ~/.openclaw/.env
+openclaw config set agents.defaults.model.primary "openai/gpt-4o"
+openclaw gateway restart
+
+# 4. Install ApeClaw + open Forge
+npx --yes ape-claw@latest skill install
+npx --yes ape-claw@latest dashboard
+```
+
+The `ape-claw dashboard` command automates steps 2-3 when possible (auto-onboard, auto-approve pending devices, auto-set model to match your API key). If something still fails, running the manual steps above resolves it.
+
+---
+
 ## Development
 
 ```bash

package/docs/operator/01-quickstart.md

@@ -13,123 +13,117 @@ Get ApeClaw running and execute your first skill in 5 minutes.
 
 ## Step 1: Install OpenClaw
 
-Install [OpenClaw](https://openclaw.ai) and verify it's available:
+Install [OpenClaw](https://openclaw.ai):
 
 ```bash
-openclaw skills list
+curl -fsSL https://openclaw.ai/install.sh | bash
 ```
 
-If `openclaw` is not found, follow the setup guide at [openclaw.ai](https://openclaw.ai).
-
-## Step 2: Install ApeClaw
+After install, make sure `openclaw` is on your PATH. If `openclaw: command not found`:
 
 ```bash
-npx ape-claw skill install
-npx ape-claw doctor --json
+export PATH="$HOME/.npm-global/bin:$PATH"
+rehash   # zsh only
 ```
 
-PowerShell (Windows):
+Add that `export PATH` line to your `~/.zshrc` or `~/.bashrc` for persistence.
 
-```powershell
-npx ape-claw skill install
-npx ape-claw doctor --json
+Verify:
+
+```bash
+openclaw --version
 ```
 
-## Step 3: Register a Clawbot
+## Step 2: Set up the OpenClaw gateway
+
+The gateway is the local runtime that powers the AI agent. Generate config and start it:
 
 ```bash
-npx ape-claw clawbot register \
-  --agent-id my-bot \
-  --name "My Bot" \
-  --api https://apeclaw.ai \
-  --json
+openclaw onboard --non-interactive --accept-risk --auth-choice skip --install-daemon --skip-channels --skip-skills --skip-ui --json
+openclaw gateway start
+openclaw devices pair --auto-approve
 ```
 
-Save the `claw_...` token — it's shown only once.
+## Step 3: Configure your LLM provider
 
-## Step 4: Set Environment
+Set your API key. Pick one provider:
 
 ```bash
-export APE_CLAW_AGENT_ID=my-bot
-export APE_CLAW_AGENT_TOKEN=claw_...
+# OpenAI (recommended)
+echo 'OPENAI_API_KEY=sk-your-key-here' >> ~/.openclaw/.env
+openclaw config set agents.defaults.model.primary "openai/gpt-4o"
+
+# Or Anthropic
+# echo 'ANTHROPIC_API_KEY=sk-ant-your-key-here' >> ~/.openclaw/.env
 ```
 
-PowerShell (Windows):
+Restart the gateway to pick up the new config:
 
-```powershell
-$env:APE_CLAW_AGENT_ID="my-bot"
-$env:APE_CLAW_AGENT_TOKEN="claw_..."
+```bash
+openclaw gateway restart
 ```
 
-## Step 5: Open the Dashboard
+You can also set keys later via the Forge settings button (top-right gear icon).
 
-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 4: Install ApeClaw
 
-## Step 6: Browse Skills
+```bash
+npx --yes ape-claw@latest skill install
+npx --yes ape-claw@latest doctor --json
+```
 
-Visit [/skills](https://apeclaw.ai/skills) to browse 10,000+ skills in the library, with 10,000+ minted onchain, served via API.
+During `skill install`, ApeClaw prompts for:
+- **Starter pack** — 61 curated skills across productivity, dev tools, security, analytics, SEO, and automation
+- **Forge dashboard upgrade** — replaces the local OpenClaw dashboard with the enhanced Forge UI
 
-## Step 7: Connect Your Forge Agent (Optional)
+PowerShell (Windows):
 
-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.
+```powershell
+npx --yes ape-claw@latest skill install
+npx --yes ape-claw@latest doctor --json
+```
 
-### What you need
+## Step 5: Open the Forge Dashboard
 
-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).
+```bash
+npx --yes ape-claw@latest dashboard
+```
 
-### Set environment variables
+This starts the local Forge server and opens `http://localhost:8787/forge` in your browser. Chat with your agent, manage skills, and control the gateway — all from one place.
 
-Pick one provider — one env var is all you need:
+To restore the original OpenClaw dashboard files:
 
 ```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
+npx ape-claw dashboard restore-openclaw
 ```
 
-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.
+## Step 6: Register a Clawbot (optional)
 
-Optional overrides:
+Registration enables telemetry and the global dashboard. It is not required for local Forge usage.
 
 ```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)
+npx ape-claw clawbot register \
+  --agent-id my-bot \
+  --name "My Bot" \
+  --api https://apeclaw.ai \
+  --json
 ```
 
-### Start the server
+Save the `claw_...` token — it's shown only once.
 
 ```bash
-npm run start:ui
+export APE_CLAW_AGENT_ID=my-bot
+export APE_CLAW_AGENT_TOKEN=claw_...
 ```
 
-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
+## Step 7: Browse Skills
 
-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.
+Visit [/skills](https://apeclaw.ai/skills) to browse 10,000+ skills in the library, with 10,000+ minted onchain, served via API.
 
-### Verify it's working
+## Step 8: Verify Forge is working
 
 ```bash
-curl -s http://localhost:8787/api/forge/status | jq .
+curl -s http://127.0.0.1:8787/api/forge/status | jq .
 ```
 
 Expected output:
@@ -137,15 +131,30 @@ Expected output:
 ```json
 {
   "configured": true,
+  "provider": "openclaw-gateway",
   "agentId": "the-clawllector",
   "agentName": "The Clawllector",
-  "verified": true,
-  "model": "sonar-pro",
-  "skills": 42
+  "gatewayReady": true,
+  "llmProviderHint": "openai",
+  "llmModelHint": "gpt-4o",
+  "skills": 61
 }
 ```
 
-If `"configured": false`, your `PERPLEXITY_API_KEY` is missing or empty.
+If `"configured": false`, your OpenClaw gateway LLM provider is not set up yet. Go to the Forge settings (gear icon) and add your API key, or follow Step 3 above.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `openclaw: command not found` | `export PATH="$HOME/.npm-global/bin:$PATH"` then `rehash` |
+| `Unknown command: dashboard` | `rm -rf ~/.npm/_npx && npm cache verify`, then re-run with `npx --yes ape-claw@latest` |
+| `device token mismatch` on dashboard | `openclaw devices list`, then `openclaw devices approve <request-id>` |
+| `Error: internal error` in chat | Check model matches key: `openclaw config set agents.defaults.model.primary "openai/gpt-4o"` then `openclaw gateway restart` |
+| Forge not loading on `localhost:8787` | Try `http://127.0.0.1:8787/forge` instead (macOS IPv6 issue) |
+| Gateway won't start | Run `openclaw onboard --non-interactive --accept-risk --auth-choice skip --install-daemon --skip-channels --skip-skills --skip-ui --json` first |
+
+See the main [README Troubleshooting section](../../README.md#troubleshooting) for detailed guidance.
 
 ## Next Steps
 

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

@@ -9,15 +9,25 @@ Complete reference for all `ape-claw` CLI commands.
 ## Installation
 
 ```bash
-npx ape-claw skill install
-npx ape-claw doctor --json
+npx --yes ape-claw@latest skill install
+npx --yes ape-claw@latest doctor --json
+```
+
+During core install (no slug), ApeClaw prompts for:
+- Starter pack install
+- Forge dashboard upgrade (best-effort OpenClaw local dashboard replacement with safe fallback)
+
+Open local Forge anytime with:
+
+```bash
+npx --yes ape-claw@latest dashboard
 ```
 
 PowerShell (Windows):
 
 ```powershell
-npx ape-claw skill install
-npx ape-claw doctor --json
+npx --yes ape-claw@latest skill install
+npx --yes ape-claw@latest doctor --json
 ```
 
 ## Global Flags
@@ -76,6 +86,36 @@ ape-claw quickstart --json
 
 ---
 
+#### `dashboard`
+
+Open the local ApeClaw Forge dashboard. Starts the local ApeClaw UI server if needed, then opens `http://localhost:8787/forge`.
+
+**Synopsis:**
+```bash
+ape-claw dashboard
+ape-claw dashboard --json
+ape-claw dashboard restore-openclaw
+```
+
+**Required arguments:** None
+
+**Optional arguments:**
+- `--json` — Return startup/open status details as JSON
+
+**Subcommands:**
+- `restore-openclaw` — Restore OpenClaw dashboard UI from `.apeclaw.bak` if present
+
+**What it does automatically:**
+- Generates `~/.openclaw/openclaw.json` via `openclaw onboard` if missing
+- Starts the OpenClaw gateway if not running
+- Auto-pairs the local device if token mismatch is detected
+- Sets gateway model to `openai/gpt-4o` if `OPENAI_API_KEY` is present but model points at Anthropic
+- Starts the local Forge server and opens the browser
+
+**Output:** Returns/prints dashboard URL, server startup status, browser open result, and overwrite/reapply status when applicable.
+
+---
+
 #### `chain info`
 
 Get chain information including latest block.
@@ -520,7 +560,7 @@ Install skills for Cursor/OpenClaw. Without a slug, installs the core `ape-claw`
 
 **Synopsis:**
 ```bash
-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
+ape-claw skill install [<slug>] [--scope <local|global>] [--skills-dir <path>] [--starter-pack | --no-starter-pack] [--forge-upgrade | --no-forge-upgrade] [--allow-unvetted] [--allow-high-risk] [--allow-custom-api] [--allow-insecure-api] --json
 ```
 
 **Required arguments:** None
@@ -530,6 +570,7 @@ ape-claw skill install [<slug>] [--scope <local|global>] [--skills-dir <path>] [
 - `--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
+- `--forge-upgrade` / `--no-forge-upgrade` — Opt in/out of Forge dashboard upgrade during core install (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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ape-claw",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "ApeChain bridge and NFT execution CLI with telemetry for OpenClaw agents",
   "license": "MIT",
   "repository": {