diff --git a/docs/v3/guides/integrations/openclaw.mdx b/docs/v3/guides/integrations/openclaw.mdx
index d6c7180c..5c96a026 100644
--- a/docs/v3/guides/integrations/openclaw.mdx
+++ b/docs/v3/guides/integrations/openclaw.mdx
@@ -22,23 +22,78 @@ echo "HONCHO_API_KEY=hc_..." >> ~/.openclaw/.env
 
 ## Install the Plugin
 
+### Option A: ClawHub Skill (Recommended)
+
+The `honcho-setup` skill on [ClawHub](https://clawhub.ai/ajspig/honcho-setup) handles installation, migration, and workspace setup interactively:
+
+```bash
+clawhub install honcho-setup
+```
+
+Then run the skill from a chat session. It will walk you through plugin installation, legacy memory migration, and workspace doc setup.
+
+### Option B: Manual Install
+
+Install the plugin using the OpenClaw plugin system. **Do not install `@honcho-ai/sdk` directly or use `npm install` in the workspace.**
+
 ```bash
 openclaw plugins install @honcho-ai/openclaw-honcho
 ```
 
-The install script automatically syncs workspace docs, migrates existing memory to Honcho, and archives legacy files. Restart the gateway after installing:
+Then enable it:
+
+```bash
+openclaw plugins enable openclaw-honcho
+```
+
+If the gateway logs show `Cannot find module '@honcho-ai/sdk'`, install the plugin's dependencies manually:
+
+```bash
+cd ~/.openclaw/extensions/openclaw-honcho && npm install
+```
+
+Restart the gateway after installing:
 
 ```bash
 openclaw gateway restart
 ```
 
+## Migrating Legacy Memory
+
+If you have existing workspace memory files (`USER.md`, `MEMORY.md`, `IDENTITY.md`, `memory/`, `canvas/`, etc.), these can be migrated to Honcho. The recommended path is the `honcho-setup` ClawHub skill, which handles this interactively.
+
+<Note>
+Commit any existing memory files to version control before migrating.
+</Note>
+
+### Legacy files
+
+**User/owner files** (content describes the user):
+- `USER.md`, `IDENTITY.md`, `MEMORY.md`
+- All files in `memory/` and `canvas/` directories
+
+**Agent/self files** (content describes the agent):
+- `SOUL.md`, `AGENTS.md`, `TOOLS.md`, `BOOTSTRAP.md`, `HEARTBEAT.md`
+
+### Upload to Honcho
+
+Files are uploaded to Honcho via the **messages upload endpoint**. User/owner files are uploaded through the owner peer, and agent/self files through the openclaw peer. The `honcho-setup` skill automates this using `session.uploadFile()`.
+
+### Archive originals
+
+After uploading:
+
+1. **Remove originals** for legacy-only files: `USER.md`, `MEMORY.md`, `IDENTITY.md`, `HEARTBEAT.md`
+2. **Keep originals** for active workspace docs: `AGENTS.md`, `TOOLS.md`, `SOUL.md`, `BOOTSTRAP.md`
+3. **Move directories** (`memory/`, `canvas/`) into an `archive/` directory
+
 ## How It Works
 
 Once installed, the plugin runs automatically:
 
-* **Context Injection** — Before every AI turn, Honcho injects the user's profile, representation, and conversation summary.
-* **Message Observation** — After every AI turn, the exchange is persisted to Honcho for extraction and long-term storage.
-* **Dual Peer Model** — Honcho maintains separate representations for the user and the agent.
+* **Message Observation** — After every AI turn, the conversation is persisted to Honcho. Both user and agent messages are observed, allowing Honcho to build and refine its models.
+* **Tool-Based Context Access** — The AI can query Honcho mid-conversation using tools like `honcho_recall`, `honcho_search`, and `honcho_analyze` to retrieve relevant context.
+* **Dual Peer Model** — Honcho maintains separate representations: one for the user (preferences, facts, communication style) and one for the agent (personality, learned behaviors).
 
 ## AI Tools
 
@@ -77,12 +132,53 @@ Optional — the plugin works out of the box with `HONCHO_API_KEY` set.
 
 ### Self-Hosted Honcho
 
-Point the plugin to your local instance:
+Point the plugin to your local instance and follow the [self-hosting guide](https://github.com/plastic-labs/honcho?tab=readme-ov-file#local-development) to get started:
 
 ```bash
 echo "HONCHO_BASE_URL=http://localhost:8000" >> ~/.openclaw/.env
 ```
 
+## Local File Search (QMD Integration)
+
+The plugin automatically exposes OpenClaw's `memory_search` and `memory_get` tools when a memory backend is configured, allowing both Honcho cloud memory and local file search together.
+
+### Setup
+
+1. Install [QMD](https://github.com/tobi/qmd) on your server
+
+2. Configure OpenClaw in `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "memory": {
+    "backend": "qmd",
+    "qmd": {
+      "limits": {
+        "timeoutMs": 120000
+      }
+    }
+  }
+}
+```
+
+3. Set up QMD collections and restart:
+
+```bash
+qmd collection add ~/Documents/notes --name notes
+qmd update
+openclaw gateway restart
+```
+
+### Available Tools
+
+When QMD is configured, you get both Honcho and local file tools:
+
+| Tool | Source | Description |
+| ---- | ------ | ----------- |
+| `honcho_*` | Honcho | Cross-session memory, user modeling, dialectic reasoning |
+| `memory_search` | QMD | Search local markdown files |
+| `memory_get` | QMD | Retrieve file content |
+
 ## Next Steps
 
 <CardGroup cols={2}>