From 39e09273ca625a54b26fb32c31d0cc4766e3adc6 Mon Sep 17 00:00:00 2001
From: Gustavo Madeira Santana <gumadeiras@gmail.com>
Date: Sat, 28 Feb 2026 20:40:30 -0500
Subject: [PATCH] docs(diffs): update docs for diffs plugin

---
 docs/docs.json             |   1 +
 docs/tools/diffs.md        | 132 +++++++++++++++++++++++++++++++++++++
 docs/tools/index.md        |   1 +
 extensions/diffs/README.md |   1 +
 4 files changed, 135 insertions(+)
 create mode 100644 docs/tools/diffs.md

diff --git a/docs/docs.json b/docs/docs.json
index 761f30f51..c91d21f39 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -987,6 +987,7 @@
                 "pages": [
                   "tools/lobster",
                   "tools/llm-task",
+                  "tools/diffs",
                   "tools/exec",
                   "tools/web",
                   "tools/apply-patch",
diff --git a/docs/tools/diffs.md b/docs/tools/diffs.md
new file mode 100644
index 000000000..f4726dbb3
--- /dev/null
+++ b/docs/tools/diffs.md
@@ -0,0 +1,132 @@
+---
+title: "Diffs"
+summary: "Read-only diff viewer and PNG renderer for agents (optional plugin tool)"
+description: "Use the optional Diffs plugin to render before/after text or unified patches as a gateway-hosted diff view or a PNG."
+read_when:
+  - You want agents to show code or markdown edits as diffs
+  - You want a canvas-ready viewer URL or a rendered diff PNG
+---
+
+# Diffs
+
+`diffs` is an **optional plugin tool** that renders a read-only diff from either:
+
+- arbitrary `before` / `after` text
+- a unified patch
+
+The tool can produce:
+
+- a gateway-hosted viewer URL for canvas use
+- a PNG image for message delivery
+- both outputs together
+
+## Enable the plugin
+
+```json5
+{
+  plugins: {
+    entries: {
+      diffs: {
+        enabled: true,
+      },
+    },
+  },
+}
+```
+
+## What agents get back
+
+- `mode: "view"` returns `details.viewerUrl` and `details.viewerPath`
+- `mode: "image"` returns `details.imagePath` only
+- `mode: "both"` returns the viewer details plus `details.imagePath`
+
+Typical agent patterns:
+
+- open `details.viewerUrl` in canvas with `canvas present`
+- send `details.imagePath` with the `message` tool using `path` or `filePath`
+
+## Tool inputs
+
+Before/after input:
+
+```json
+{
+  "before": "# Hello\n\nOne",
+  "after": "# Hello\n\nTwo",
+  "path": "docs/example.md",
+  "mode": "view"
+}
+```
+
+Patch input:
+
+```json
+{
+  "patch": "diff --git a/src/example.ts b/src/example.ts\n--- a/src/example.ts\n+++ b/src/example.ts\n@@ -1 +1 @@\n-const x = 1;\n+const x = 2;\n",
+  "mode": "both"
+}
+```
+
+Useful options:
+
+- `mode`: `view`, `image`, or `both`
+- `layout`: `unified` or `split`
+- `theme`: `light` or `dark`
+- `expandUnchanged`: expand unchanged sections instead of collapsing them
+- `path`: display name for before/after input
+- `title`: explicit diff title
+- `ttlSeconds`: viewer artifact lifetime
+- `baseUrl`: override the gateway base URL used in the returned viewer link
+
+## Plugin defaults
+
+Set plugin-wide defaults in `~/.openclaw/openclaw.json`:
+
+```json5
+{
+  plugins: {
+    entries: {
+      diffs: {
+        enabled: true,
+        config: {
+          defaults: {
+            fontFamily: "Fira Code",
+            fontSize: 15,
+            layout: "unified",
+            wordWrap: true,
+            background: true,
+            theme: "dark",
+            mode: "both",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Supported defaults:
+
+- `fontFamily`
+- `fontSize`
+- `layout`
+- `wordWrap`
+- `background`
+- `theme`
+- `mode`
+
+Explicit tool parameters override the plugin defaults.
+
+## Notes
+
+- Viewer pages are hosted locally by the gateway under `/plugins/diffs/...`.
+- Viewer artifacts are ephemeral and stored locally.
+- `mode: "image"` uses a faster image-only render path and does not create a viewer URL.
+- PNG rendering requires a Chromium-compatible browser. If auto-detection is not enough, set `browser.executablePath`.
+- Diff rendering is powered by [Diffs](https://diffs.com).
+
+## Related docs
+
+- [Tools overview](/tools)
+- [Plugins](/tools/plugin)
+- [Browser](/tools/browser)
diff --git a/docs/tools/index.md b/docs/tools/index.md
index 9b9a4586c..4e7d7f169 100644
--- a/docs/tools/index.md
+++ b/docs/tools/index.md
@@ -174,6 +174,7 @@ Optional plugin tools:
 
 - [Lobster](/tools/lobster): typed workflow runtime with resumable approvals (requires the Lobster CLI on the gateway host).
 - [LLM Task](/tools/llm-task): JSON-only LLM step for structured workflow output (optional schema validation).
+- [Diffs](/tools/diffs): read-only diff viewer and PNG renderer for before/after text or unified patches.
 
 ## Tool inventory
 
diff --git a/extensions/diffs/README.md b/extensions/diffs/README.md
index d889d2f81..41fdf0676 100644
--- a/extensions/diffs/README.md
+++ b/extensions/diffs/README.md
@@ -151,3 +151,4 @@ diff --git a/src/example.ts b/src/example.ts
 - The viewer is hosted locally through the gateway under `/plugins/diffs/...`.
 - Artifacts are ephemeral and stored in the local temp directory.
 - PNG rendering requires a Chromium-compatible browser. Set `browser.executablePath` if auto-detection is not enough.
+- Diff rendering is powered by [Diffs](https://diffs.com).