diff --git a/docs/tools/index.md b/docs/tools/index.md
index ccb0c87c6..984957c34 100644
--- a/docs/tools/index.md
+++ b/docs/tools/index.md
@@ -154,6 +154,9 @@ See [Plugins](/plugin) for install + config, and [Skills](/tools/skills) for how
 tool usage guidance is injected into prompts. Some plugins ship their own skills
 alongside tools (for example, the voice-call plugin).
 
+Optional plugin tools:
+- [Lobster](/tools/lobster): typed workflow runtime with resumable approvals (requires the Lobster CLI on the gateway host).
+
 ## Tool inventory
 
 ### `apply_patch`
diff --git a/docs/tools/lobster.md b/docs/tools/lobster.md
index bb3f4d130..11f77f827 100644
--- a/docs/tools/lobster.md
+++ b/docs/tools/lobster.md
@@ -1,6 +1,10 @@
 ---
 title: Lobster
+summary: "Typed workflow runtime for Clawdbot with resumable approval gates."
 description: Typed workflow runtime for Clawdbot — composable pipelines with approval gates.
+read_when:
+  - You want deterministic multi-step workflows with explicit approvals
+  - You need to resume a workflow without re-running earlier steps
 ---
 
 # Lobster
@@ -11,10 +15,41 @@ Lobster is a workflow shell that lets Clawdbot run multi-step tool sequences as
 
 Today, complex workflows require many back-and-forth tool calls. Each call costs tokens, and the LLM has to orchestrate every step. Lobster moves that orchestration into a typed runtime:
 
-- **One call instead of many**: Clawdbot calls `lobster.run(...)` once and gets a structured result.
+- **One call instead of many**: Clawdbot runs one Lobster tool call and gets a structured result.
 - **Approvals built in**: Side effects (send email, post comment) halt the workflow until explicitly approved.
 - **Resumable**: Halted workflows return a token; approve and resume without re-running everything.
 
+## How it works
+
+Clawdbot launches the local `lobster` CLI in **tool mode** and parses a JSON envelope from stdout.
+If the pipeline pauses for approval, the tool returns a `resumeToken` so you can continue later.
+
+## Install Lobster
+
+Install the Lobster CLI on the **same host** that runs the Clawdbot Gateway (see the [Lobster repo](https://github.com/vignesh07/lobster)), and ensure `lobster` is on `PATH`.
+If you want to use a custom binary location, pass an **absolute** `lobsterPath` in the tool call.
+
+## Enable the tool
+
+Lobster is an **optional** plugin tool (not enabled by default). Allow it per agent:
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "tools": {
+          "allow": ["lobster"]
+        }
+      }
+    ]
+  }
+}
+```
+
+You can also allow it globally with `tools.allow` if every agent should see it.
+
 ## Example: Email triage
 
 Without Lobster:
@@ -30,58 +65,53 @@ User: "Check my email and draft replies"
 ```
 
 With Lobster:
-```
-clawd calls: lobster.run("email.triage --limit 20")
-
-Returns:
+```json
 {
+  "action": "run",
+  "pipeline": "email.triage --limit 20",
+  "timeoutMs": 30000
+}
+```
+
+Returns a JSON envelope (truncated):
+```json
+{
+  "ok": true,
   "status": "needs_approval",
-  "output": {
-    "summary": "5 need replies, 2 need action",
-    "drafts": [...]
-  },
+  "output": [{ "summary": "5 need replies, 2 need action" }],
   "requiresApproval": {
+    "type": "approval_request",
     "prompt": "Send 2 draft replies?",
+    "items": [],
     "resumeToken": "..."
   }
 }
+```
 
-User approves → clawd calls: lobster.resume(token, approve: true)
-→ Emails sent
+User approves → resume:
+```json
+{
+  "action": "resume",
+  "token": "<resumeToken>",
+  "approve": true
+}
 ```
 
 One workflow. Deterministic. Safe.
 
-## Enable
-
-Lobster is an **optional** plugin tool. Enable it in your agent config:
-
-```json
-{
-  "agents": {
-    "list": [{
-      "id": "main",
-      "tools": {
-        "allow": ["lobster"]
-      }
-    }]
-  }
-}
-```
-
-You also need the `lobster` CLI installed locally.
-
-## Actions
+## Tool parameters
 
 ### `run`
 
-Execute a Lobster pipeline in tool mode.
+Run a pipeline in tool mode.
 
 ```json
 {
   "action": "run",
   "pipeline": "gog.gmail.search --query 'newer_than:1d' | email.triage",
-  "timeoutMs": 30000
+  "cwd": "/path/to/workspace",
+  "timeoutMs": 30000,
+  "maxStdoutBytes": 512000
 }
 ```
 
@@ -97,13 +127,45 @@ Continue a halted workflow after approval.
 }
 ```
 
-## Security
+### Optional inputs
+
+- `lobsterPath`: Absolute path to the Lobster binary (omit to use `PATH`).
+- `cwd`: Working directory for the pipeline (defaults to the current process working directory).
+- `timeoutMs`: Kill the subprocess if it exceeds this duration (default: 20000).
+- `maxStdoutBytes`: Kill the subprocess if stdout exceeds this size (default: 512000).
+
+## Output envelope
+
+Lobster returns a JSON envelope with one of three statuses:
+
+- `ok` → finished successfully
+- `needs_approval` → paused; `requiresApproval.resumeToken` is required to resume
+- `cancelled` → explicitly denied or cancelled
+
+The tool surfaces the envelope in both `content` (pretty JSON) and `details` (raw object).
+
+## Approvals
+
+If `requiresApproval` is present, inspect the prompt and decide:
+
+- `approve: true` → resume and continue side effects
+- `approve: false` → cancel and finalize the workflow
+
+## Safety
 
 - **Local subprocess only** — no network calls from the plugin itself.
 - **No secrets** — Lobster doesn't manage OAuth; it calls clawd tools that do.
-- **Sandbox-aware** — disabled when `ctx.sandboxed` is true.
+- **Sandbox-aware** — disabled when the tool context is sandboxed.
 - **Hardened** — `lobsterPath` must be absolute if specified; timeouts and output caps enforced.
 
+## Troubleshooting
+
+- **`lobster subprocess timed out`** → increase `timeoutMs`, or split a long pipeline.
+- **`lobster output exceeded maxStdoutBytes`** → raise `maxStdoutBytes` or reduce output size.
+- **`lobster returned invalid JSON`** → ensure the pipeline runs in tool mode and prints only JSON.
+- **`lobster failed (code …)`** → run the same pipeline in a terminal to inspect stderr.
+
 ## Learn more
 
-- [Lobster repo](https://github.com/vignesh07/lobster) — runtime, commands, and workflow examples.
+- [Plugins](/plugin)
+- [Plugin tool authoring](/plugins/agent-tools)