From 22717878cc6c1837e13df244be65f74e1a1eab61 Mon Sep 17 00:00:00 2001
From: Vincent Koc <vincentkoc@ieee.org>
Date: Wed, 22 Apr 2026 00:14:32 -0700
Subject: [PATCH] docs(tokenjuice): add bundled plugin guide (#70038)

* docs(tokenjuice): add bundled plugin guide

* docs(tokenjuice): sort nav entry
---
 docs/docs.json           |  1 +
 docs/tools/index.md      |  7 ++--
 docs/tools/tokenjuice.md | 76 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 81 insertions(+), 3 deletions(-)
 create mode 100644 docs/tools/tokenjuice.md

diff --git a/docs/docs.json b/docs/docs.json
index 6fdc0576762..1ae08671395 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -1226,6 +1226,7 @@
                   "tools/pdf",
                   "tools/reactions",
                   "tools/thinking",
+                  "tools/tokenjuice",
                   "tools/video-generation"
                 ]
               },
diff --git a/docs/tools/index.md b/docs/tools/index.md
index 33b66f1f2dc..26134f1a4d4 100644
--- a/docs/tools/index.md
+++ b/docs/tools/index.md
@@ -104,11 +104,12 @@ legacy `tools.bash.*` aliases normalize to the same protected exec paths.
 
 Plugins can register additional tools. Some examples:
 
-- [Lobster](/tools/lobster) — typed workflow runtime with resumable approvals
-- [LLM Task](/tools/llm-task) — JSON-only LLM step for structured output
-- [Music Generation](/tools/music-generation) — shared `music_generate` tool with workflow-backed providers
 - [Diffs](/tools/diffs) — diff viewer and renderer
+- [LLM Task](/tools/llm-task) — JSON-only LLM step for structured output
+- [Lobster](/tools/lobster) — typed workflow runtime with resumable approvals
+- [Music Generation](/tools/music-generation) — shared `music_generate` tool with workflow-backed providers
 - [OpenProse](/prose) — markdown-first workflow orchestration
+- [Tokenjuice](/tools/tokenjuice) — compact noisy `exec` and `bash` tool results
 
 ## Tool configuration
 
diff --git a/docs/tools/tokenjuice.md b/docs/tools/tokenjuice.md
new file mode 100644
index 00000000000..e03398d1a10
--- /dev/null
+++ b/docs/tools/tokenjuice.md
@@ -0,0 +1,76 @@
+---
+title: "Tokenjuice"
+summary: "Compact noisy exec and bash tool results with an optional bundled plugin"
+read_when:
+  - You want shorter `exec` or `bash` tool results in OpenClaw
+  - You want to enable the bundled tokenjuice plugin
+  - You need to understand what tokenjuice changes and what it leaves raw
+---
+
+# Tokenjuice
+
+`tokenjuice` is an optional bundled plugin that compacts noisy `exec` and `bash`
+tool results after the command has already run.
+
+It changes the returned `tool_result`, not the command itself. Tokenjuice does
+not rewrite shell input, rerun commands, or change exit codes.
+
+Today this applies to Pi embedded runs, where tokenjuice hooks the embedded
+`tool_result` path and trims the output that goes back into the session.
+
+## Enable the plugin
+
+Fast path:
+
+```bash
+openclaw config set plugins.entries.tokenjuice.enabled true
+```
+
+Equivalent:
+
+```bash
+openclaw plugins enable tokenjuice
+```
+
+OpenClaw already ships the plugin. There is no separate `plugins install`
+or `tokenjuice install openclaw` step.
+
+If you prefer editing config directly:
+
+```json5
+{
+  plugins: {
+    entries: {
+      tokenjuice: {
+        enabled: true,
+      },
+    },
+  },
+}
+```
+
+## What tokenjuice changes
+
+- Compacts noisy `exec` and `bash` results before they are fed back into the session.
+- Keeps the original command execution untouched.
+- Preserves exact file-content reads and other commands that tokenjuice should leave raw.
+- Stays opt-in: disable the plugin if you want verbatim output everywhere.
+
+## Verify it is working
+
+1. Enable the plugin.
+2. Start a session that can call `exec`.
+3. Run a noisy command such as `git status`.
+4. Check that the returned tool result is shorter and more structured than the raw shell output.
+
+## Disable the plugin
+
+```bash
+openclaw config set plugins.entries.tokenjuice.enabled false
+```
+
+Or:
+
+```bash
+openclaw plugins disable tokenjuice
+```