From 07f1280cb0dc044a81b0f9f0f392d29ba13490bb Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Mon, 12 Jan 2026 01:27:05 +0000
Subject: [PATCH] docs: expand plugin quickstart

---
 docs/plugin.md                  | 27 +++++++++++++++++++++++++++
 docs/plugins/voice-call.md      | 29 +++++++++++++++++++++++++++--
 extensions/voice-call/README.md |  1 +
 3 files changed, 55 insertions(+), 2 deletions(-)

diff --git a/docs/plugin.md b/docs/plugin.md
index 17c91a1b7..7230bef44 100644
--- a/docs/plugin.md
+++ b/docs/plugin.md
@@ -6,6 +6,33 @@ read_when:
 ---
 # Plugins (Extensions)
 
+## Quick start (new to plugins?)
+
+A plugin is just a **small code module** that extends Clawdbot with extra
+features (commands, tools, and Gateway RPC).
+
+Most of the time, you’ll use plugins when you want a feature that’s not built
+into core Clawdbot yet (or you want to keep optional features out of your main
+install).
+
+Fast path:
+
+1) See what’s already loaded:
+
+```bash
+clawdbot plugins list
+```
+
+2) Install an official plugin (example: Voice Call):
+
+```bash
+clawdbot plugins install @clawdbot/voice-call
+```
+
+3) Restart the Gateway, then configure under `plugins.entries.<id>.config`.
+
+See [Voice Call](/plugins/voice-call) for a concrete example plugin.
+
 Clawdbot plugins are **TypeScript modules** loaded at runtime via jiti. They can
 register:
 
diff --git a/docs/plugins/voice-call.md b/docs/plugins/voice-call.md
index c0c7cbb88..12a17443c 100644
--- a/docs/plugins/voice-call.md
+++ b/docs/plugins/voice-call.md
@@ -9,11 +9,18 @@ read_when:
 
 Outbound voice calls for Clawdbot via a plugin.
 
+If you’re new to plugins, start with [Plugins](/plugin): what they are, where
+they live on disk, and how install/config works.
+
 Current providers:
 - `twilio` (real calls)
 - `log` (dev fallback; no network)
 
-If you haven’t read the general plugin docs yet, start with [Plugins](/plugin).
+Quick mental model:
+- Install plugin
+- Restart Gateway
+- Configure under `plugins.entries.voice-call.config`
+- Use `clawdbot voicecall …` or the `voice_call` tool
 
 ## Install
 
@@ -27,7 +34,25 @@ This downloads the package, extracts it into `~/.clawdbot/extensions/`, and enab
 
 Restart the Gateway afterwards.
 
-### Option B: install from a local folder (dev)
+### Option B: install from a local folder (dev, no copying)
+
+This keeps the plugin in-place (great for iterating locally) and adds the folder
+to `plugins.load.paths`.
+
+```bash
+clawdbot plugins install /absolute/path/to/voice-call
+```
+
+If your plugin has dependencies, install them in that folder (so it has a
+`node_modules`):
+
+```bash
+cd /absolute/path/to/voice-call && pnpm install
+```
+
+Restart the Gateway afterwards.
+
+### Option C: copy into the global extensions folder (dev)
 
 ```bash
 mkdir -p ~/.clawdbot/extensions
diff --git a/extensions/voice-call/README.md b/extensions/voice-call/README.md
index 796f72712..32b7858e3 100644
--- a/extensions/voice-call/README.md
+++ b/extensions/voice-call/README.md
@@ -6,6 +6,7 @@ Official Voice Call plugin for **Clawdbot**.
 - Dev fallback: `log` (no network)
 
 Docs: `https://docs.clawd.bot/plugins/voice-call`
+Plugin system: `https://docs.clawd.bot/plugin`
 
 ## Install (local dev)