From 7519163ab5554fbfb38cfad0997f3f9386a74dbf Mon Sep 17 00:00:00 2001
From: Keith Patrick <keithy@consultant.com>
Date: Thu, 5 Mar 2026 05:07:09 +0000
Subject: [PATCH] docs: add plugins documentation to README
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

💘 Generated with Crush

Assisted-by: MiniMax-M2.5 via Crush <crush@charm.land>
---
 README.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/README.md b/README.md
index 7a31f9364..add583c56 100644
--- a/README.md
+++ b/README.md
@@ -1293,6 +1293,32 @@ picoclaw agent -m "Hello"
 | `picoclaw cron list`      | List all scheduled jobs       |
 | `picoclaw cron add ...`   | Add a scheduled job           |
 
+### Plugins
+
+PicoClaw supports extensible plugins. Place executable files in `~/.picoclaw/plugins/`:
+
+```bash
+# List available plugins
+picoclaw plugins-list
+
+# Run a plugin (shorthand)
+picoclaw service status
+
+# Run a plugin (full name)
+picoclaw picoclaw-service status
+
+# Get help for a plugin
+picoclaw service --help
+```
+
+Plugins are executables in `~/.picoclaw/plugins/` with names starting with `picoclaw-` (or match via prefix).
+
+For programmatic use, hide the banner:
+
+```bash
+PICOCLAW_NO_BANNER=1 picoclaw service status
+```
+
 ### Scheduled Tasks / Reminders
 
 PicoClaw supports scheduled reminders and recurring tasks through the `cron` tool: