diff --git a/cookbook/clone-and-attach.mdx b/cookbook/clone-and-attach.mdx
new file mode 100644
index 00000000..653c2d35
--- /dev/null
+++ b/cookbook/clone-and-attach.mdx
@@ -0,0 +1,104 @@
+---
+title: Clone and Attach
+description: Provision a sandbox yourself — shallow-clone a repo and run its setup script — then attach an OpenHands conversation to the prepared environment.
+---
+
+**Source:** [`clone-and-attach/`](https://github.com/jpshackelford/oh-examples/tree/main/clone-and-attach)
+
+Normally OpenHands clones your repository automatically when a conversation starts. This example shows how to take control of that process: you provision the sandbox, clone the repo, run its setup script, and only then hand it off to the agent.
+
+## Why Do This?
+
+- **Pre-warm expensive environments** so the agent starts instantly
+- **Clone a specific commit, tag, or monorepo sub-path** that the default flow doesn't support
+- **Run custom bootstrapping** before the agent gets involved
+- **Reuse one prepared sandbox** across multiple scripted conversations
+
+## How It Works
+
+```
+POST /api/v1/sandboxes                       # 1. Create sandbox
+GET  /api/v1/sandboxes?id=<id>               # 2. Poll until RUNNING
+POST {agent}/api/bash/execute_bash_command   # 3. git clone --depth 1 <repo>
+POST {agent}/api/bash/execute_bash_command   # 4. bash .openhands/setup.sh
+POST /api/v1/app-conversations               # 5. Attach conversation (sandbox_id=<id>)
+GET  /api/v1/app-conversations/start-tasks   # 6. Poll for app_conversation_id
+```
+
+Steps 1–2 and 5–6 use the **Cloud app server** (`X-Session-API-Key: <OH_API_KEY>`). Steps 3–4 use the **agent server** (`X-Session-API-Key: <session_api_key>`).
+
+## The Key Field: `sandbox_id`
+
+`POST /api/v1/app-conversations` accepts a `sandbox_id` parameter. Pass the ID of a sandbox you already prepared and the new conversation attaches to it instead of creating a fresh one:
+
+```python
+resp = requests.post(
+    f"{CLOUD}/api/v1/app-conversations",
+    headers=cloud_headers,
+    json={
+        "sandbox_id": sid,
+        "initial_message": {
+            "role": "user",
+            "content": [{"type": "text", "text": message}],
+        },
+    },
+)
+start_task_id = resp.json()["id"]
+```
+
+## Attaching Is Asynchronous
+
+`POST /api/v1/app-conversations` returns a **start task**, not the conversation itself. Poll until `app_conversation_id` is available:
+
+```python
+for _ in range(80):
+    tasks = requests.get(
+        f"{CLOUD}/api/v1/app-conversations/start-tasks",
+        headers=cloud_headers,
+        params={"ids": start_task_id},
+    ).json()
+    task = tasks[0]
+    if task.get("app_conversation_id"):
+        break
+    time.sleep(3)
+
+conversation_id = task["app_conversation_id"]
+print(f"https://app.all-hands.dev/conversations/{conversation_id}")
+```
+
+## Quickstart
+
+```bash
+export OH_API_KEY="your-api-key"
+pip install requests
+
+# Zero-config: clones this example repo and attaches a conversation
+python attach_conversation.py
+```
+
+## Configuration Options
+
+All inputs accept flags or environment variable fallbacks:
+
+| Flag | Env var | Default | Purpose |
+|------|---------|---------|---------|
+| `--api-key` | `OH_API_KEY` | *(required)* | Cloud API key |
+| `--repo` | `REPO_URL` | this repo | Git URL to shallow-clone |
+| `--branch` | `REPO_BRANCH` | repo default | Branch to check out |
+| `--depth` | `CLONE_DEPTH` | `1` | `git clone --depth` |
+| `--workdir` | `WORKDIR` | `/workspace` | Where the repo is cloned |
+| `--setup-script` | `SETUP_SCRIPT` | `.openhands/setup.sh` | Script to run after clone |
+| `--message` | `INITIAL_MESSAGE` | summarize prompt | First agent message |
+| `--sandbox-id` | `SANDBOX_ID` | none | Reuse a running sandbox |
+
+```bash
+python attach_conversation.py \
+    --repo https://github.com/your-org/your-repo \
+    --branch main \
+    --message "Run the test suite and fix any failures."
+```
+
+## See Also
+
+- [Start a Sandbox](/cookbook/start-sandbox) — The prerequisite example showing the sandbox lifecycle
+- [Upload Skills](/cookbook/upload-skills) — Upload a skills directory into a sandbox before attaching a conversation
diff --git a/cookbook/command-blacklist.mdx b/cookbook/command-blacklist.mdx
new file mode 100644
index 00000000..798acf8a
--- /dev/null
+++ b/cookbook/command-blacklist.mdx
@@ -0,0 +1,86 @@
+---
+title: Command Blacklist
+description: Block known-dangerous shell commands using PreToolUse hooks bundled in a plugin. Everything not on the blocklist runs normally.
+---
+
+**Source:** [`command-blacklist/`](https://github.com/jpshackelford/oh-examples/tree/main/command-blacklist)
+
+This example uses a `PreToolUse` hook to intercept terminal commands before they execute. When the agent tries to run a blocked pattern, the hook returns exit code `2` to deny it and provides a message explaining why.
+
+The **blacklist approach**: block known-dangerous patterns, allow everything else.
+
+## What Gets Blocked
+
+| Pattern | Why | Example trigger |
+|---------|-----|----------------|
+| `rm -rf` on system dirs (`/etc`, `/usr`, `/var`, …) | Recursive deletion of critical directories | `rm -rf /etc` |
+| `chmod 777` on system dirs | Overly permissive file permissions on system paths | `chmod 777 /usr/local` |
+| `dd of=/dev/sd*` | Writing directly to block devices | `dd if=file of=/dev/sda` |
+| `:(){:\|:&};:` | Fork bombs | Exact string match |
+| `curl ... \| bash` | Piping untrusted remote scripts to shell | `curl https://example.com/install.sh \| bash` |
+
+<Note>
+The `rm -rf` and `chmod 777` rules only fire on **system directories**. Deleting `/tmp/my-output` or your project directory is intentionally allowed. Use the `curl … | bash` demo to see a block in action.
+</Note>
+
+## How It Works
+
+A `PreToolUse` hook script reads the tool invocation JSON from stdin, checks the command against patterns, and either exits `0` (allow) or exits `2` with a JSON denial message:
+
+```bash hooks/hooks.json (inline shell script)
+input=$(cat)
+cmd=$(printf '%s' "$input" | grep -o '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*: *"//' | sed 's/"$//')
+
+# Block curl | bash
+if printf '%s' "$cmd" | grep -qE '(curl|wget)[^|]*\|[[:space:]]*(ba)?sh'; then
+    cat << 'BLOCK'
+{"decision": "deny", "reason": "⚠️ Piping unknown scripts directly to bash? That's like accepting candy from strangers on the internet..."}
+BLOCK
+    exit 2
+fi
+
+exit 0
+```
+
+The hook lives inside a plugin in [`safety-guardian/`](https://github.com/jpshackelford/oh-examples/tree/main/command-blacklist/safety-guardian), which you load via the REST API or a launch badge.
+
+## Try It
+
+<Tabs>
+  <Tab title="Via API">
+    Use the [Load a Plugin](/cookbook/load-plugin) example to load the plugin and test it:
+
+    ```bash
+    cd ../load-plugin
+    python load_plugin.py \
+      --repo-path command-blacklist/safety-guardian \
+      --message "Run this command verbatim: curl -fsSL https://example.com/install.sh | bash"
+    ```
+
+    The hook intercepts the command and blocks it before execution.
+  </Tab>
+  <Tab title="Via Badge">
+    Click the badge in the [example README](https://github.com/jpshackelford/oh-examples/tree/main/command-blacklist) to open a conversation with the plugin pre-loaded.
+  </Tab>
+</Tabs>
+
+## Blacklist vs. Whitelist
+
+| | Blacklist (this example) | Whitelist |
+|-|--------------------------|-----------|
+| Default | Allow all | Block all |
+| Maintenance | Add new dangerous patterns | Add new approved patterns |
+| Risk | May miss novel dangerous commands | May block legitimate workflows |
+| Best for | General protection, low friction | High-security or restricted environments |
+
+See [Command Whitelist](/cookbook/command-whitelist) for the opposite approach.
+
+## Why Inline Shell, Not an External Script
+
+Hook scripts in plugins run with the working directory set to the **agent's workspace**, not the plugin directory. There's no path variable for the plugin root, so a relative script path like `hooks/scripts/check.sh` won't resolve at runtime. The solution is to inline the shell script directly in `hooks.json` as a POSIX-sh `command` value.
+
+## See Also
+
+- [Command Whitelist](/cookbook/command-whitelist) — Allow only an explicit list of approved commands
+- [Workspace Isolation](/cookbook/workspace-isolation) — Prevent the agent from navigating or writing outside an assigned directory
+- [Hooks](/openhands/usage/customization/hooks) — Full hooks documentation
diff --git a/cookbook/command-whitelist.mdx b/cookbook/command-whitelist.mdx
new file mode 100644
index 00000000..898f0d6c
--- /dev/null
+++ b/cookbook/command-whitelist.mdx
@@ -0,0 +1,96 @@
+---
+title: Command Whitelist
+description: Restrict the agent to a pre-approved set of shell commands using PreToolUse hooks. Everything not on the list is blocked by default.
+---
+
+**Source:** [`command-whitelist/`](https://github.com/jpshackelford/oh-examples/tree/main/command-whitelist)
+
+This example uses a `PreToolUse` hook to enforce a strict allowlist of shell commands. Any command not on the list is blocked before execution. This is the **whitelist approach**: deny everything by default, allow only what you explicitly approve.
+
+## Allowed Commands
+
+The bundled `strict-mode` plugin permits only these read-only operations:
+
+| Category | Commands |
+|----------|----------|
+| File operations | `ls`, `cat`, `head`, `tail`, `file` |
+| Search & filter | `grep`, `find`, `wc` |
+| System info | `pwd`, `whoami`, `date`, `uname`, `df`, `du`, `stat` |
+| Utilities | `echo`, `which`, `env`, `printenv`, `history`, `tree` |
+
+Everything else — `pip`, `npm`, `rm`, `git`, `curl`, and anything else — is **blocked**.
+
+## How It Works
+
+The hook extracts the command name from the tool invocation JSON, checks it against the approved list, and denies it if not found:
+
+```bash
+input=$(cat)
+# Extract first word of the command (the binary name)
+cmd=$(printf '%s' "$input" \
+    | grep -o '"command"[[:space:]]*:[[:space:]]*"[^"]*"' \
+    | head -1 | sed 's/.*: *"//' | sed 's/"$//' \
+    | awk '{print $1}' | sed 's|.*/||')
+
+# Check against the approved list
+case "$cmd" in
+    ls|cat|head|tail|file|grep|find|wc|pwd|whoami|date|uname|df|du|stat|echo|which|env|printenv|history|tree)
+        exit 0  # Allow
+        ;;
+    *)
+        printf '{"decision": "deny", "reason": "🚫 Command '\''%s'\'' is not in the approved list."}\n' "$cmd"
+        exit 2  # Block
+        ;;
+esac
+```
+
+The hook lives in [`strict-mode/`](https://github.com/jpshackelford/oh-examples/tree/main/command-whitelist/strict-mode).
+
+## Try It
+
+<Tabs>
+  <Tab title="Via API">
+    ```bash
+    cd ../load-plugin
+
+    # This will be blocked (pip is not on the whitelist)
+    python load_plugin.py \
+      --repo-path command-whitelist/strict-mode \
+      --message "Install the requests package"
+
+    # This will be allowed (ls is on the whitelist)
+    python load_plugin.py \
+      --repo-path command-whitelist/strict-mode \
+      --message "List all Python files in the current directory"
+    ```
+  </Tab>
+  <Tab title="Via Badge">
+    Click the badge in the [example README](https://github.com/jpshackelford/oh-examples/tree/main/command-whitelist) to open a conversation with the plugin pre-loaded.
+  </Tab>
+</Tabs>
+
+## Customizing the Allowlist
+
+Edit the `case` statement in `hooks/hooks.json` to add commands for your use case:
+
+```bash
+# Add git read operations to the allowlist
+ls|cat|head|tail|file|grep|find|wc|pwd|whoami|date|uname|df|du|stat|echo|which|env|printenv|history|tree|git)
+    exit 0
+    ;;
+```
+
+## When to Use Whitelisting
+
+| Use case | Recommendation |
+|----------|---------------|
+| General development work | [Blacklist](/cookbook/command-blacklist) — fewer blocked operations |
+| Read-only exploration or analysis | **Whitelist** — agent can only inspect, never modify |
+| Regulated environments | **Whitelist** — explicit control over every permitted action |
+| Shared/multi-tenant setups | [Workspace Isolation](/cookbook/workspace-isolation) combined with either approach |
+
+## See Also
+
+- [Command Blacklist](/cookbook/command-blacklist) — Block specific dangerous commands while allowing everything else
+- [Workspace Isolation](/cookbook/workspace-isolation) — Enforce directory boundaries regardless of which commands are used
+- [Hooks](/openhands/usage/customization/hooks) — Full hooks documentation
diff --git a/cookbook/conversation-metrics.mdx b/cookbook/conversation-metrics.mdx
new file mode 100644
index 00000000..3e4b8524
--- /dev/null
+++ b/cookbook/conversation-metrics.mdx
@@ -0,0 +1,88 @@
+---
+title: Conversation Metrics
+description: Retrieve cost, token usage, and cache statistics for any OpenHands conversation using a CLI tool that supports both V0 and V1 APIs.
+---
+
+**Source:** [`conversation-metrics/`](https://github.com/jpshackelford/oh-examples/tree/main/conversation-metrics)
+
+`oh-metrics` is a zero-dependency CLI tool that fetches cost and token usage for an OpenHands conversation. It automatically detects whether the conversation uses the V0 or V1 API and applies the appropriate retrieval strategy.
+
+## Installation
+
+```bash
+git clone https://github.com/jpshackelford/oh-examples.git
+cd oh-examples
+pip install -e conversation-metrics/
+```
+
+Or run the script directly (Python 3.10+ required):
+
+```bash
+chmod +x oh-examples/conversation-metrics/oh-metrics
+```
+
+## Usage
+
+```bash
+export OH_API_KEY="your-api-key"
+./oh-metrics <conversation_id>
+```
+
+## Example Output
+
+```
+────────────────────────────────────────────────────────────
+Conversation: 72d40619b8534f9b9de6c3f17a71072d
+Title: Fix authentication bug
+API Version: V1 via V1 (events)
+────────────────────────────────────────────────────────────
+💰 Total Cost: $0.42 USD
+
+📊 Token Usage:
+   Prompt tokens:     245,120
+   Completion tokens: 3,840
+   Total tokens:      248,960
+
+🗄️  Cache:
+   Cache read:        198,400
+   Cache write:       42,720
+
+📐 Context window:    200,000
+────────────────────────────────────────────────────────────
+```
+
+## JSON Output
+
+Pass `--json` for programmatic use:
+
+```bash
+./oh-metrics <conversation_id> --json
+```
+
+## Features
+
+- **Auto-detects** conversation version (V0 vs V1) and uses the appropriate API
+- **Graceful fallback** chain — tries multiple endpoints until one succeeds
+- **JSON output** for integration with dashboards or alerting pipelines
+- **API call logging** with `--verbose` for debugging
+- **Zero dependencies** — uses only the Python standard library
+- **Fixture-based testing** — high test coverage via recorded API responses
+
+## Getting a Conversation ID
+
+Conversation IDs appear in the URL when you open a conversation:
+
+```
+https://app.all-hands.dev/conversations/<conversation_id>
+```
+
+You can also retrieve them programmatically:
+
+```bash
+curl -s https://app.all-hands.dev/api/v1/app-conversations \
+  -H "X-Session-API-Key: $OH_API_KEY" | python3 -m json.tool
+```
+
+## See Also
+
+- [Conversation Tags](/cookbook/conversation-tags) — Attach metadata to conversations for tracking and filtering
diff --git a/cookbook/conversation-tags.mdx b/cookbook/conversation-tags.mdx
new file mode 100644
index 00000000..6c204c7f
--- /dev/null
+++ b/cookbook/conversation-tags.mdx
@@ -0,0 +1,117 @@
+---
+title: Conversation Tags
+description: Attach arbitrary key-value metadata to an OpenHands conversation using the tags field, and read it back from your own tooling.
+---
+
+**Source:** [`conversation-tags/`](https://github.com/jpshackelford/oh-examples/tree/main/conversation-tags)
+
+Conversations have a free-form `tags` map for storing your own metadata — for example, an external `environment_url` or a `job_id` from your CI system. This example shows the full write-then-read round-trip.
+
+Tags are the supported replacement for adding custom fields to the conversation model. Instead of waiting for the API to expose a new field, put it in `tags`.
+
+## Tag Rules
+
+| Rule | Detail |
+|------|--------|
+| Keys | Lowercase alphanumeric only — no `_` or `-` (e.g., use `environmenturl`, not `environment_url`) |
+| Values | Arbitrary strings, 256 characters max |
+| `PATCH` behavior | **Replaces all tags** — this example does a read-modify-write to merge |
+
+## The Two-Server Split
+
+Tags are written on the **agent server** (which owns the conversation), not the Cloud app server. The Cloud's `AppConversation.tags` field is eventually consistent — it typically catches up within a few seconds.
+
+| Step | Server | Call |
+|------|--------|------|
+| Start a conversation | Cloud | `POST /api/v1/app-conversations` |
+| Resolve agent URL + key | Cloud | `GET /api/v1/app-conversations?ids=<id>` |
+| **Write tags** | **Agent** | `PATCH {conversation_url}` |
+| Read tags back | Cloud | `GET /api/v1/app-conversations?ids=<id>` |
+
+## How It Works
+
+### 1. Start a Conversation
+
+```python
+import os
+import requests
+
+CLOUD = "https://app.all-hands.dev"
+cloud_headers = {"X-Session-API-Key": os.environ["OH_API_KEY"]}
+
+task = requests.post(
+    f"{CLOUD}/api/v1/app-conversations",
+    headers=cloud_headers,
+    json={"initial_message": {"role": "user", "content": [{"type": "text", "text": "Hello"}]}},
+).json()
+```
+
+### 2. Resolve the Agent URL
+
+```python
+# Poll until conversation is ready, then fetch conversation details
+conv = requests.get(
+    f"{CLOUD}/api/v1/app-conversations",
+    headers=cloud_headers,
+    params={"ids": conversation_id},
+).json()[0]
+
+conversation_url = conv["conversation_url"]   # full agent resource URL
+session_api_key = conv["session_api_key"]
+agent_headers = {"X-Session-API-Key": session_api_key}
+```
+
+### 3. Write Tags (Agent Server)
+
+```python
+# Read existing tags first to avoid clobbering them
+existing = requests.get(conversation_url, headers=agent_headers).json()
+merged_tags = {**existing.get("tags", {}), "environmenturl": "https://env.example.com", "jobid": "42"}
+
+requests.patch(
+    conversation_url,
+    headers=agent_headers,
+    json={"tags": merged_tags},
+)
+```
+
+### 4. Read Tags Back (Cloud)
+
+```python
+# The Cloud reflects the agent server's tags (eventually consistent)
+import time
+for _ in range(10):
+    conv = requests.get(
+        f"{CLOUD}/api/v1/app-conversations",
+        headers=cloud_headers,
+        params={"ids": conversation_id},
+    ).json()[0]
+    if conv.get("tags"):
+        break
+    time.sleep(2)
+
+print(conv["tags"])
+# {"environmenturl": "https://env.example.com", "jobid": "42"}
+```
+
+## Quickstart
+
+```bash
+export OH_API_KEY="your-api-key"
+pip install requests
+python tag_conversation.py
+```
+
+Pass your own tags with `--tag`:
+
+```bash
+python tag_conversation.py \
+    --tag environmenturl=https://staging.example.com \
+    --tag jobid=ci-run-1234 \
+    --keep   # don't delete the conversation after the demo
+```
+
+## See Also
+
+- [Per-Conversation Secrets](/cookbook/per-conversation-secrets) — Inject secrets that are scoped to a single conversation
+- [Conversation Metrics](/cookbook/conversation-metrics) — Retrieve cost and token usage for a conversation
diff --git a/cookbook/index.mdx b/cookbook/index.mdx
new file mode 100644
index 00000000..04fb7f5b
--- /dev/null
+++ b/cookbook/index.mdx
@@ -0,0 +1,94 @@
+---
+title: Cookbook
+description: Practical, runnable examples for working with the OpenHands REST API.
+---
+
+The Cookbook is a collection of standalone Python examples that show how to use the OpenHands Cloud API. Each example is self-contained, runnable with a single script, and focused on one clear task.
+
+All examples live in the [jpshackelford/oh-examples](https://github.com/jpshackelford/oh-examples) repository on GitHub.
+
+## Prerequisites
+
+Most examples require an OpenHands API key:
+
+```bash
+export OH_API_KEY="your-api-key"
+```
+
+Get your API key from [app.all-hands.dev](https://app.all-hands.dev) under **Settings → API Keys**.
+
+## Examples
+
+### Sandboxes
+
+<CardGroup cols={2}>
+  <Card title="Start a Sandbox" icon="box" href="/cookbook/start-sandbox">
+    Create a sandbox via the V1 API and run shell commands directly against the agent-server — no conversation needed.
+  </Card>
+  <Card title="Clone and Attach" icon="code-branch" href="/cookbook/clone-and-attach">
+    Provision a sandbox yourself (clone a repo + run its setup script), then attach a conversation to that prepared environment.
+  </Card>
+</CardGroup>
+
+### Conversations
+
+<CardGroup cols={2}>
+  <Card title="Conversation Metrics" icon="chart-bar" href="/cookbook/conversation-metrics">
+    CLI tool to retrieve cost and token usage for any conversation, with support for both V0 and V1 APIs.
+  </Card>
+  <Card title="Conversation Tags" icon="tag" href="/cookbook/conversation-tags">
+    Attach arbitrary key-value metadata to a conversation and read it back from your own tooling.
+  </Card>
+  <Card title="Per-Conversation Secrets" icon="lock" href="/cookbook/per-conversation-secrets">
+    Inject secrets scoped to a single conversation — as bash environment variables or to authenticate an MCP server.
+  </Card>
+</CardGroup>
+
+### Plugins & Skills
+
+<CardGroup cols={2}>
+  <Card title="Load a Plugin" icon="plug" href="/cookbook/load-plugin">
+    Start a conversation with a plugin pre-loaded using a single REST API field.
+  </Card>
+  <Card title="Launch Plugin Badge" icon="badge-check" href="/cookbook/launch-plugin-badge">
+    Build a no-code `/launch` link, HTML button, or README badge that opens a conversation with your plugin pre-loaded.
+  </Card>
+  <Card title="Upload Skills" icon="graduation-cap" href="/cookbook/upload-skills">
+    Upload a local skills directory into a sandbox so every subsequent conversation inherits those skills.
+  </Card>
+  <Card title="Test MCP Config" icon="server" href="/cookbook/test-mcp-config">
+    Validate MCP server configurations against a live sandbox before wiring them into a conversation.
+  </Card>
+</CardGroup>
+
+### Hooks
+
+<CardGroup cols={2}>
+  <Card title="Command Blacklist" icon="ban" href="/cookbook/command-blacklist">
+    Block known-dangerous shell commands with PreToolUse hooks while letting everything else through.
+  </Card>
+  <Card title="Command Whitelist" icon="shield-check" href="/cookbook/command-whitelist">
+    Restrict the agent to a pre-approved set of commands with PreToolUse hooks.
+  </Card>
+  <Card title="Workspace Isolation" icon="lock-keyhole" href="/cookbook/workspace-isolation">
+    Enforce directory boundaries with hooks — prevent agents from navigating or writing outside their assigned workspace.
+  </Card>
+</CardGroup>
+
+## API Overview
+
+The OpenHands Cloud API has two server types that work together:
+
+| Server | Base URL | Auth header | Purpose |
+|--------|----------|-------------|---------|
+| **Cloud app server** | `https://app.all-hands.dev` | `X-Session-API-Key: <OH_API_KEY>` | Manages sandboxes and conversations |
+| **Agent server** | From `sandbox.exposed_urls` | `X-Session-API-Key: <session_api_key>` | Runs inside each sandbox; executes commands and holds conversation state |
+
+Most examples start by calling the Cloud app server to create a sandbox or conversation, then switch to the agent server to interact with the runtime directly.
+
+## Related Resources
+
+- [Cloud API Reference](/openhands/usage/cloud/cloud-api) — Full API reference for the OpenHands Cloud API
+- [Plugins](/overview/plugins) — How plugins work and how to create them
+- [Hooks](/openhands/usage/customization/hooks) — Full hooks reference for repository-based hooks
+- [Skills](/overview/skills) — How to create and use skills
diff --git a/cookbook/launch-plugin-badge.mdx b/cookbook/launch-plugin-badge.mdx
new file mode 100644
index 00000000..f5b2b486
--- /dev/null
+++ b/cookbook/launch-plugin-badge.mdx
@@ -0,0 +1,126 @@
+---
+title: Launch Plugin Badge
+description: Build a no-code /launch link, HTML button, or README badge that opens an OpenHands conversation with your plugin pre-loaded — no API key in the URL.
+---
+
+**Source:** [`launch-plugin-badge/`](https://github.com/jpshackelford/oh-examples/tree/main/launch-plugin-badge)
+
+The OpenHands frontend has a `/launch` route that anyone can click. It decodes a `plugins` parameter, shows a confirmation modal, and — after the user confirms — calls `POST /api/v1/app-conversations` using the **user's own auth**. No secrets in the URL.
+
+This is the no-code equivalent of [Load a Plugin](/cookbook/load-plugin): instead of writing Python to call the API, you construct a URL and put it in a README badge or an HTML button.
+
+## The URL Format
+
+```
+https://app.all-hands.dev/launch?plugins=<BASE64>&message=<URL-ENCODED>
+```
+
+| Parameter | Format | Purpose |
+|-----------|--------|---------|
+| `plugins` | Base64-encoded JSON array of plugin specs | Which plugins to load |
+| `message` | URL-encoded string | Initial message sent to the agent |
+
+## Building the URL
+
+<Steps>
+  <Step>
+    ### Define Your Plugin Spec
+
+    ```python
+    plugins = [
+        {
+            "source": "github:your-org/your-repo",
+            "ref": "main",
+            "repo_path": "path/to/plugin-dir",
+        }
+    ]
+    ```
+  </Step>
+  <Step>
+    ### Base64-Encode It
+
+    ```python
+    import base64
+    import json
+
+    encoded = base64.b64encode(json.dumps(plugins).encode()).decode()
+    ```
+  </Step>
+  <Step>
+    ### URL-Encode the Message
+
+    ```python
+    from urllib.parse import quote
+
+    message = "/my-plugin:run"
+    encoded_message = quote(message)
+    ```
+  </Step>
+  <Step>
+    ### Assemble the URL
+
+    ```python
+    url = f"https://app.all-hands.dev/launch?plugins={encoded}&message={encoded_message}"
+    ```
+  </Step>
+</Steps>
+
+## Turn It Into a Badge
+
+Once you have the URL, wrap it in Markdown or HTML:
+
+<Tabs>
+  <Tab title="Markdown badge">
+    ```markdown
+    [![Open with my plugin](https://img.shields.io/badge/Open%20with%20my%20plugin-blue)](YOUR_LAUNCH_URL)
+    ```
+  </Tab>
+  <Tab title="HTML button">
+    ```html
+    <a href="YOUR_LAUNCH_URL">
+      <button>Open with my plugin</button>
+    </a>
+    ```
+  </Tab>
+  <Tab title="Plain link">
+    ```markdown
+    [Open with my plugin](YOUR_LAUNCH_URL)
+    ```
+  </Tab>
+</Tabs>
+
+## Use the Generator Script
+
+The example ships a script that builds and prints these for you:
+
+```bash
+python build_launch_url.py \
+    --source github:your-org/your-repo \
+    --repo-path path/to/plugin-dir \
+    --message "/my-plugin:run" \
+    --label "Try my plugin"
+```
+
+No API key needed — this only constructs URLs.
+
+## Parameterized Plugins
+
+If your plugin declares `parameters` in its manifest, they appear as editable inputs in the launch confirmation modal:
+
+```python
+plugins = [
+    {
+        "source": "github:your-org/your-repo",
+        "ref": "main",
+        "repo_path": "my-plugin",
+        "parameters": {
+            "environment": "staging",   # Pre-fills the input; user can change it
+        },
+    }
+]
+```
+
+## See Also
+
+- [Load a Plugin](/cookbook/load-plugin) — The programmatic (Python) equivalent of this example
+- [Plugins](/overview/plugins) — Full plugin documentation including how to create a plugin manifest
diff --git a/cookbook/load-plugin.mdx b/cookbook/load-plugin.mdx
new file mode 100644
index 00000000..58ea679c
--- /dev/null
+++ b/cookbook/load-plugin.mdx
@@ -0,0 +1,131 @@
+---
+title: Load a Plugin
+description: Start an OpenHands conversation with a plugin pre-loaded using a single field in the REST API call.
+---
+
+**Source:** [`load-plugin/`](https://github.com/jpshackelford/oh-examples/tree/main/load-plugin)
+
+A plugin is a small git-hosted bundle that can include slash commands, skills, hooks, and MCP server configurations. Loading one at conversation-start is as simple as adding a `plugins` field to the `POST /api/v1/app-conversations` request.
+
+## The One Field That Matters
+
+```python
+import os
+import requests
+
+requests.post(
+    "https://app.all-hands.dev/api/v1/app-conversations",
+    headers={"X-Session-API-Key": os.environ["OH_API_KEY"]},
+    json={
+        "plugins": [
+            {
+                "source": "github:your-org/your-repo",
+                "ref": "main",
+                "repo_path": "path/to/plugin-dir",
+            }
+        ],
+        "initial_message": {
+            "role": "user",
+            "content": [{"type": "text", "text": "/my-plugin:run"}],
+        },
+    },
+)
+```
+
+A plugin spec has three parts:
+
+| Field | Meaning | Example |
+|-------|---------|---------|
+| `source` | Where the plugin lives | `github:your-org/your-repo` |
+| `ref` | Git ref (branch, tag, SHA) | `main` |
+| `repo_path` | Sub-directory within the repo | `plugins/my-plugin` |
+
+## The Call Is Asynchronous
+
+`POST /api/v1/app-conversations` returns a **start task**, not a finished conversation. Poll until `app_conversation_id` is available:
+
+```python
+import time
+
+task_id = resp.json()["id"]
+CLOUD = "https://app.all-hands.dev"
+cloud_headers = {"X-Session-API-Key": os.environ["OH_API_KEY"]}
+
+for _ in range(80):
+    tasks = requests.get(
+        f"{CLOUD}/api/v1/app-conversations/start-tasks",
+        headers=cloud_headers,
+        params={"ids": task_id},
+    ).json()
+    if tasks[0].get("app_conversation_id"):
+        break
+    time.sleep(3)
+
+conv_id = tasks[0]["app_conversation_id"]
+print(f"https://app.all-hands.dev/conversations/{conv_id}")
+```
+
+## Two Ways to Drive the Plugin
+
+The `initial_message` controls what happens after the plugin loads:
+
+<Tabs>
+  <Tab title="Run an entry command">
+    Send the plugin's slash command as the initial message. The agent executes it immediately:
+
+    ```python
+    "initial_message": {
+        "role": "user",
+        "content": [{"type": "text", "text": "/my-plugin:start duck"}]
+    }
+    ```
+  </Tab>
+  <Tab title="Natural language prompt">
+    Send a natural-language message. The plugin's skills and commands are available for the agent to use when relevant:
+
+    ```python
+    "initial_message": {
+        "role": "user",
+        "content": [{"type": "text", "text": "Tell me a dad joke"}]
+    }
+    ```
+  </Tab>
+</Tabs>
+
+## Try the Example
+
+The example ships a working `dad-joke/` plugin that tells dad jokes. Run it to see the full flow:
+
+```bash
+export OH_API_KEY="your-api-key"
+pip install requests
+python load_plugin.py
+# Opens a conversation that tells a dad joke about a duck
+```
+
+Override the default behavior:
+
+```bash
+python load_plugin.py --message "Tell me a dad joke about a cat"
+```
+
+## Plugin Structure
+
+A minimal plugin needs these files:
+
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json    # Manifest: name, version, description
+├── skills/
+│   └── my-plugin/
+│       └── SKILL.md   # Skills the agent loads at startup
+└── hooks/
+    └── hooks.json     # Optional: lifecycle hooks
+```
+
+## See Also
+
+- [Launch Plugin Badge](/cookbook/launch-plugin-badge) — Create a no-code clickable link or badge that loads your plugin
+- [Per-Conversation Secrets](/cookbook/per-conversation-secrets) — Pass secrets to authenticate a plugin's MCP server
+- [Plugins](/overview/plugins) — Full plugin documentation
diff --git a/cookbook/per-conversation-secrets.mdx b/cookbook/per-conversation-secrets.mdx
new file mode 100644
index 00000000..e9913871
--- /dev/null
+++ b/cookbook/per-conversation-secrets.mdx
@@ -0,0 +1,108 @@
+---
+title: Per-Conversation Secrets
+description: Inject secrets scoped to a single conversation — as bash environment variables, or to authenticate an MCP server via placeholder expansion in a plugin's .mcp.json.
+---
+
+**Source:** [`per-conversation-secrets/`](https://github.com/jpshackelford/oh-examples/tree/main/per-conversation-secrets)
+
+OpenHands lets users store secrets in their vault for long-lived credentials. This example covers a different need: injecting a secret that belongs to one conversation only — for example, a customer's OAuth token, a temporary CI credential, or a per-tenant API key.
+
+## Two Patterns
+
+### Pattern A — Secrets as Bash Environment Variables
+
+Pass `secrets` at conversation-start time. The agent can then use `$MY_KEY` in any bash command it runs.
+
+```python
+requests.post(
+    f"{CLOUD}/api/v1/app-conversations",
+    headers=cloud_headers,
+    json={
+        "secrets": {
+            "DATABASE_URL": "postgres://user:pass@host/db",
+            "API_TOKEN": "tok_abc123",
+        },
+        "initial_message": {
+            "role": "user",
+            "content": [{"type": "text", "text": "Run the migration using $DATABASE_URL"}],
+        },
+    },
+)
+```
+
+The secrets are available as environment variables in every bash command the agent runs, but are never stored in the conversation transcript.
+
+### Pattern B — Secrets as MCP Server Auth
+
+The same `secrets` field also drives `${VARIABLE}` expansion inside a **plugin's** `.mcp.json`. When you ship a plugin with a placeholder like `${MCP_SECRET_TOKEN}` in its MCP server config, OpenHands fills it in from the conversation's secrets before dialing that MCP server.
+
+```json .mcp.json inside the plugin
+{
+  "mcpServers": {
+    "my-api": {
+      "url": "${MCP_SERVER_URL}/mcp",
+      "transport": "sse",
+      "headers": {
+        "Authorization": "Bearer ${MCP_SECRET_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+At conversation-start time, pass matching secrets:
+
+```python
+requests.post(
+    f"{CLOUD}/api/v1/app-conversations",
+    headers=cloud_headers,
+    json={
+        "plugins": [{"source": "github:your-org/your-plugins", "ref": "main", "repo_path": "my-plugin"}],
+        "secrets": {
+            "MCP_SERVER_URL": "https://api.example.com",
+            "MCP_SECRET_TOKEN": customer_oauth_token,
+        },
+        "initial_message": ...,
+    },
+)
+```
+
+OpenHands expands the placeholders before connecting to the MCP server. The token is never visible in the conversation transcript.
+
+## What Is a Plugin?
+
+A plugin is a directory in a git repo with three files:
+
+```
+my-plugin/
+├── .mcp.json            # MCP server config with ${...} placeholders
+├── .plugin/plugin.json  # Manifest: name, version, author
+└── SKILL.md             # Documentation the agent reads at startup
+```
+
+<Note>
+This example ships a working `test-plugin/` in the repo — a ready-made plugin whose `.mcp.json` uses `${MCP_SERVER_URL}` and `${MCP_SECRET_TOKEN}`.
+</Note>
+
+## Quickstart
+
+```bash
+export OH_API_KEY="your-api-key"
+pip install requests
+
+# Pattern A: secrets as bash env vars
+python test_secrets_at_start.py
+
+# Pattern B: secrets expand into plugin MCP config
+python test_mcp_secrets_at_start.py
+```
+
+## Mid-Conversation Injection (Legacy)
+
+You can also inject secrets into a running conversation via the agent server's `/secrets` endpoint. This is less common — most use cases are better served by passing secrets at conversation-start. See [`test_secrets.py`](https://github.com/jpshackelford/oh-examples/blob/main/per-conversation-secrets/test_secrets.py) for the implementation.
+
+## See Also
+
+- [Load a Plugin](/cookbook/load-plugin) — How to load a plugin into a conversation
+- [Test MCP Config](/cookbook/test-mcp-config) — Validate MCP server configurations before use
+- [Conversation Tags](/cookbook/conversation-tags) — Attach non-secret metadata to a conversation
diff --git a/cookbook/start-sandbox.mdx b/cookbook/start-sandbox.mdx
new file mode 100644
index 00000000..75ce2bcc
--- /dev/null
+++ b/cookbook/start-sandbox.mdx
@@ -0,0 +1,123 @@
+---
+title: Start a Sandbox
+description: Create an OpenHands Cloud sandbox and run shell commands directly against the agent-server REST API — no conversation required.
+---
+
+**Source:** [`start-sandbox/`](https://github.com/jpshackelford/oh-examples/tree/main/start-sandbox)
+
+Sometimes you want a managed remote workspace you drive yourself — for tooling, batch jobs, or programmatic agents — without a full conversation. This example creates a sandbox, waits for it to be ready, then executes shell commands directly on the agent-server.
+
+## Two Servers
+
+OpenHands uses two separate servers:
+
+| Server | Purpose | Auth |
+|--------|---------|------|
+| **Cloud app server** (`app.all-hands.dev`) | Creates and tracks sandboxes | `X-Session-API-Key: <OH_API_KEY>` |
+| **Agent server** (URL from `exposed_urls`) | Runs inside the sandbox; executes commands | `X-Session-API-Key: <session_api_key>` |
+
+The `session_api_key` is different from your Cloud API key — it's returned by the sandbox-create response.
+
+## The Flow
+
+```
+POST /api/v1/sandboxes                      # 1. Create sandbox
+GET  /api/v1/sandboxes?id=<id>              # 2. Poll until status == RUNNING
+POST {agent_url}/api/bash/execute_bash_command  # 3. Run commands
+```
+
+## Quickstart
+
+```bash
+export OH_API_KEY="your-api-key"
+pip install requests
+python sandbox_demo_brief.py
+```
+
+## How It Works
+
+### 1. Create the Sandbox
+
+```python
+import os
+import requests
+
+CLOUD = "https://app.all-hands.dev"
+headers = {"X-Session-API-Key": os.environ["OH_API_KEY"]}
+
+sb = requests.post(f"{CLOUD}/api/v1/sandboxes", headers=headers).json()
+sid = sb["id"]
+```
+
+### 2. Poll Until Running
+
+The sandbox starts asynchronously. Poll until `status == "RUNNING"`:
+
+```python
+import time
+
+for _ in range(60):
+    if sb["status"] == "RUNNING":
+        break
+    time.sleep(3)
+    sb = requests.get(
+        f"{CLOUD}/api/v1/sandboxes", headers=headers, params={"id": sid}
+    ).json()[0]
+```
+
+### 3. Locate the Agent Server
+
+The sandbox response includes an `exposed_urls` list. Find the one named `"AGENT_SERVER"`:
+
+```python
+agent_url = next(u["url"] for u in sb["exposed_urls"] if u["name"] == "AGENT_SERVER")
+sess = {"X-Session-API-Key": sb["session_api_key"]}
+```
+
+### 4. Run Commands
+
+Use `POST /api/bash/execute_bash_command` to run shell commands:
+
+```python
+def sh(cmd):
+    r = requests.post(
+        f"{agent_url}/api/bash/execute_bash_command",
+        headers=sess,
+        json={"command": cmd, "timeout": 30},
+    ).json()
+    return (r.get("stdout") or "") + (r.get("stderr") or "")
+
+print(sh("ls -la /workspace"))
+```
+
+## Example Output
+
+```
+sandbox: 59Ji2kvkUtZZSm7zAkAxwN
+  status: RUNNING
+agent: https://rzwfxneubhwcfpav.prod-runtime.all-hands.dev
+
+=== ls -la /workspace ===
+drwxr-sr-x bash_events
+drwxr-sr-x conversations
+drwxrws--- lost+found
+```
+
+## Cleanup
+
+The example intentionally leaves the sandbox running. To delete it:
+
+```bash
+SID=<sandbox_id>
+curl -X DELETE "https://app.all-hands.dev/api/v1/sandboxes/${SID}?sandbox_id=${SID}" \
+     -H "X-Session-API-Key: $OH_API_KEY"
+```
+
+<Note>
+The OpenAPI schema for the agent-server is available at `{agent_url}/openapi.json` once the sandbox is `RUNNING`.
+</Note>
+
+## See Also
+
+- [Clone and Attach](/cookbook/clone-and-attach) — Builds on this: clones a repo, runs its setup script, then attaches a conversation to the prepared sandbox
+- [Test MCP Config](/cookbook/test-mcp-config) — Uses a sandbox to validate MCP server configurations before use
diff --git a/cookbook/test-mcp-config.mdx b/cookbook/test-mcp-config.mdx
new file mode 100644
index 00000000..5ffaea39
--- /dev/null
+++ b/cookbook/test-mcp-config.mdx
@@ -0,0 +1,87 @@
+---
+title: Test MCP Config
+description: Validate MCP server configurations against a live sandbox before wiring them into a conversation — catch bad URLs, auth failures, and connection errors early.
+---
+
+**Source:** [`test-mcp-config/`](https://github.com/jpshackelford/oh-examples/tree/main/test-mcp-config)
+
+When you configure an MCP server in the OpenHands UI, there's no feedback on whether it actually connects. A bad URL or wrong token causes the server's tools to silently disappear from the agent's toolset. This example uses the agent-server's `POST /api/mcp/test` endpoint to validate a config end-to-end before using it.
+
+<Note>
+Requires agent-server 1.29.0 / OpenHands 1.8.0 or later. Older runtimes return 404.
+</Note>
+
+## How It Works
+
+```
+POST /api/v1/sandboxes              # 1. Start a sandbox (no conversation needed)
+GET  /api/v1/sandboxes?id=<id>      # 2. Poll until RUNNING
+POST {agent}/api/mcp/test           # 3. Validate the MCP config
+DELETE /api/v1/sandboxes/<id>       # 4. Clean up
+```
+
+The `POST /api/mcp/test` endpoint connects to a single MCP server, lists its tools, and optionally calls a specific tool to verify credentials. It returns HTTP 200 in both success and failure cases — a connection failure is an expected validation result, not a server error.
+
+## Response Format
+
+```json
+// Success
+{"ok": true, "tools": ["list_issues", "create_issue"], "tool_result": null}
+
+// Failure
+{"ok": false, "error": "Client failed to connect: connection refused", "error_kind": "connection"}
+```
+
+`error_kind` is one of: `timeout`, `connection`, or `unknown`. Auth failures (e.g., a `401`) currently return as `unknown` — read `error` for the full message.
+
+## Usage
+
+```bash
+export OH_API_KEY="your-api-key"
+pip install requests
+
+# Validate a streamable-HTTP server with a bearer token
+python test_mcp_config.py \
+    --url https://mcp.example.com/mcp \
+    --type shttp \
+    --server-api-key "$TOKEN"
+
+# Also invoke a specific tool to exercise the credentials
+python test_mcp_config.py \
+    --url https://mcp.example.com/mcp \
+    --header "Authorization=Bearer $TOKEN" \
+    --tool-call list_resources
+
+# Validate a local stdio (subprocess) server
+python test_mcp_config.py \
+    --type stdio \
+    --command "uvx mcp-server-fetch"
+```
+
+## Supported Transport Types
+
+| Type | `--type` flag | Typical use |
+|------|--------------|-------------|
+| Streamable HTTP | `shttp` | Remote HTTP MCP servers |
+| Server-Sent Events | `sse` | Older HTTP MCP servers |
+| Stdio (subprocess) | `stdio` | Local CLI-based MCP servers |
+
+## Multiple Configs at Once
+
+Pass a JSON file with multiple server configurations to validate them all in one run:
+
+```bash
+python test_mcp_config.py --config servers.json
+```
+
+```json servers.json
+[
+  {"url": "https://linear.mcp.example.com/mcp", "type": "shttp", "api_key": "lin_xxx"},
+  {"url": "https://github.mcp.example.com/mcp", "type": "shttp", "api_key": "ghp_xxx"}
+]
+```
+
+## See Also
+
+- [Per-Conversation Secrets](/cookbook/per-conversation-secrets) — Use per-conversation secrets to supply MCP server auth tokens at runtime
+- [Start a Sandbox](/cookbook/start-sandbox) — How sandbox creation and polling works
diff --git a/cookbook/upload-skills.mdx b/cookbook/upload-skills.mdx
new file mode 100644
index 00000000..608e171c
--- /dev/null
+++ b/cookbook/upload-skills.mdx
@@ -0,0 +1,83 @@
+---
+title: Upload Skills
+description: Upload a local skills directory into an OpenHands sandbox so that every conversation attached to that sandbox has access to your skills.
+---
+
+**Source:** [`upload-skills/`](https://github.com/jpshackelford/oh-examples/tree/main/upload-skills)
+
+Skills are Markdown files with YAML frontmatter that tell the agent how to do something. Normally you commit them to a repo's `.openhands/` directory. This example shows a programmatic alternative: start a sandbox, upload your skills directory into it, then attach a conversation that inherits them.
+
+## How It Works
+
+```
+POST /api/v1/sandboxes                         # 1. Create sandbox
+GET  /api/v1/sandboxes?id=<id>                 # 2. Poll until RUNNING
+POST {agent}/api/files/upload_file             # 3. Upload each SKILL.md
+POST /api/v1/app-conversations                 # 4. Attach conversation (sandbox_id=<id>)
+```
+
+The agent server's `/api/files/upload_file` endpoint accepts a multipart POST with the file content and a destination path. Skills are uploaded to `~/.openhands/skills/` by default (the location OpenHands checks at conversation start).
+
+## Quickstart
+
+```bash
+export OH_API_KEY="your-api-key"
+pip install requests
+
+# Upload the bundled example skills and start a conversation
+python upload_skills.py ./example-skills
+```
+
+## Configuration Options
+
+| Flag | Env var | Default | Purpose |
+|------|---------|---------|---------|
+| `skills_dir` | *(positional)* | `./example-skills` | Local directory of skills to upload |
+| `--remote-skills-dir` | `REMOTE_SKILLS_DIR` | `~/.openhands/skills` | Destination in the sandbox |
+| `--message` | `INITIAL_MESSAGE` | "list your skills" | First message to the agent |
+| `--sandbox-id` | `SANDBOX_ID` | none | Reuse a running sandbox |
+
+```bash
+python upload_skills.py ~/my-skills \
+    --remote-skills-dir '~/.agents/skills' \
+    --message "Use the deploy-helper skill to outline a release plan."
+```
+
+## Skill Format
+
+Each skill is a directory containing a `SKILL.md` with YAML frontmatter:
+
+```markdown
+---
+name: deploy-helper
+description: Guides the agent through a standard deployment checklist.
+triggers:
+  - deploy
+  - release
+---
+
+# Deploy Helper
+
+Before deploying, always:
+1. Run the test suite: `make test`
+2. Check the diff: `git diff main`
+3. Tag the release: `git tag v<version>`
+```
+
+The `triggers` list activates the skill automatically when matching keywords appear in a user message.
+
+## Reusing the Sandbox
+
+Once skills are uploaded, you can reuse that sandbox for subsequent conversations so they all inherit the skills automatically. Control this with the **Sandbox Grouping Strategy** in **Settings → Application**:
+
+- **No Grouping** (default): each new conversation gets a fresh sandbox — skills won't be present
+- **Any grouping strategy** (e.g., Group by Newest): new conversations join the existing, skills-loaded sandbox
+
+<Note>
+A sandbox must still be running for new conversations to join it. If the seeded sandbox has gone inactive, start a new one with `--sandbox-id` to wake it up.
+</Note>
+
+## See Also
+
+- [Clone and Attach](/cookbook/clone-and-attach) — Another way to prepare a sandbox before attaching a conversation
+- [Skills](/overview/skills) — Full documentation on creating and using skills
diff --git a/cookbook/workspace-isolation.mdx b/cookbook/workspace-isolation.mdx
new file mode 100644
index 00000000..fcc1ca5d
--- /dev/null
+++ b/cookbook/workspace-isolation.mdx
@@ -0,0 +1,127 @@
+---
+title: Workspace Isolation
+description: Enforce directory boundaries with PreToolUse hooks — prevent agents from navigating or writing outside their assigned workspace, essential for running multiple conversations in parallel.
+---
+
+**Source:** [`workspace-isolation/`](https://github.com/jpshackelford/oh-examples/tree/main/workspace-isolation)
+
+When you run multiple OpenHands conversations in parallel on a local machine, each agent works in a different directory. Without isolation, agents can accidentally `cd` into a sibling project, delete the wrong files, or write test output that collides with another agent's work.
+
+This example enforces directory boundaries with `PreToolUse` hooks on both the `terminal` and `file_editor` tools.
+
+<Note>
+In OpenHands Cloud, each conversation gets its own container — workspace isolation is already guaranteed. This example is primarily useful for local setups running multiple conversations in parallel.
+</Note>
+
+## What Gets Blocked
+
+### Terminal Commands
+
+| Operation | Blocked? |
+|-----------|----------|
+| `cd`, `pushd`, `popd` to a path outside the workspace | ✅ Blocked |
+| `rm`, `mv`, `cp`, `chmod`, `mkdir`, etc. targeting external paths | ✅ Blocked |
+| Output redirection (`>`, `>>`) to external paths | ✅ Blocked |
+| Read operations (`cat`, `grep`) of external files | ✅ Allowed |
+| Any operation inside the workspace | ✅ Allowed |
+
+### File Editor Operations
+
+| Operation | Blocked? |
+|-----------|----------|
+| `view` (read-only) anywhere | ✅ Always allowed |
+| `create`, `str_replace`, `insert`, `undo_edit` outside workspace | ✅ Blocked |
+
+## The `# read-only` Escape Hatch
+
+Add `# read-only` to a command to allow reading system files outside the workspace:
+
+```bash
+cat /etc/os-release  # read-only   ← allowed
+uname -a             # read-only   ← allowed
+echo "data" > /tmp/output.txt  # read-only   ← still blocked (write operation)
+```
+
+## How the Hooks Work
+
+Two hooks in the `sandbox-enforcer` plugin work together:
+
+**Terminal hook** — extracts the command name and target path, checks whether the path is inside the workspace:
+
+```bash
+input=$(cat)
+workspace="${OPENHANDS_PROJECT_DIR:-$PWD}"
+
+# Extract command and check if cd/write ops target outside workspace
+cmd=$(printf '%s' "$input" | grep -o '"command"[[:space:]]*:[[:space:]]*"[^"]*"' \
+    | head -1 | sed 's/.*: *"//' | sed 's/"$//')
+
+# [navigation check, write-op check, redirect check]
+# ...
+
+exit 0  # Allow if nothing matched
+```
+
+**File editor hook** — always allows `view`, blocks write commands that target paths outside the workspace.
+
+Both hooks use `OPENHANDS_PROJECT_DIR` (set by OpenHands Cloud/Enterprise) or fall back to `$PWD`.
+
+## Try It
+
+<Tabs>
+  <Tab title="Via API">
+    ```bash
+    cd ../load-plugin
+
+    # This will be blocked (navigating outside workspace)
+    python load_plugin.py \
+      --repo-path workspace-isolation/sandbox-enforcer \
+      --message "Navigate to /tmp and list the files there"
+
+    # This will be allowed (stays in workspace)
+    python load_plugin.py \
+      --repo-path workspace-isolation/sandbox-enforcer \
+      --message "List all files in the current directory"
+    ```
+  </Tab>
+  <Tab title="Via Badge">
+    Click the badge in the [example README](https://github.com/jpshackelford/oh-examples/tree/main/workspace-isolation) to open a conversation with the plugin pre-loaded.
+  </Tab>
+</Tabs>
+
+## Local Multi-Agent Setup
+
+```bash
+mkdir -p ~/projects/{web-app,api-server,cli-tool}
+
+# Start three conversations, each with isolation enforced
+python load_plugin.py --workdir ~/projects/web-app \
+    --repo-path workspace-isolation/sandbox-enforcer \
+    --message "Refactor the auth module"
+
+python load_plugin.py --workdir ~/projects/api-server \
+    --repo-path workspace-isolation/sandbox-enforcer \
+    --message "Add rate limiting"
+```
+
+Each agent stays in its assigned directory.
+
+## Limitations
+
+This is a heuristic-based implementation. For production multi-tenant use, see [jpshackelford/lxa](https://github.com/jpshackelford/lxa/blob/main/src/hooks/sandbox.py), which uses Python with full `pathlib` path resolution, symlink following, and `shlex` parsing.
+
+| Limitation | Impact |
+|------------|--------|
+| No full shell parsing | Complex quoting might bypass detection |
+| No symlink resolution | A symlink inside the workspace can point outside |
+| Fails open | If the hook can't parse input, it allows the operation |
+
+## Why Inline Shell
+
+Hook scripts in plugins run with the working directory set to the agent's workspace — there's no plugin-root path variable. External script files (`hooks/scripts/check.sh`) won't resolve at runtime. The hooks inline the POSIX-sh logic directly as a `command` string in `hooks.json`. Reference copies of the same scripts in `hooks/scripts/` exist for readability.
+
+## See Also
+
+- [Command Blacklist](/cookbook/command-blacklist) — Block specific dangerous commands
+- [Command Whitelist](/cookbook/command-whitelist) — Allow only approved commands
+- [Hooks](/openhands/usage/customization/hooks) — Full hooks documentation
diff --git a/docs.json b/docs.json
index 1524f452..8aefccf8 100644
--- a/docs.json
+++ b/docs.json
@@ -495,6 +495,44 @@
             ]
           }
         ]
+      },
+      {
+        "tab": "Cookbook",
+        "pages": [
+          "cookbook/index",
+          {
+            "group": "Sandboxes",
+            "pages": [
+              "cookbook/start-sandbox",
+              "cookbook/clone-and-attach"
+            ]
+          },
+          {
+            "group": "Conversations",
+            "pages": [
+              "cookbook/conversation-metrics",
+              "cookbook/conversation-tags",
+              "cookbook/per-conversation-secrets"
+            ]
+          },
+          {
+            "group": "Plugins & Skills",
+            "pages": [
+              "cookbook/load-plugin",
+              "cookbook/launch-plugin-badge",
+              "cookbook/upload-skills",
+              "cookbook/test-mcp-config"
+            ]
+          },
+          {
+            "group": "Hooks",
+            "pages": [
+              "cookbook/command-blacklist",
+              "cookbook/command-whitelist",
+              "cookbook/workspace-isolation"
+            ]
+          }
+        ]
       }
     ]
   },