diff --git a/docs/AGENTS.default.md b/docs/AGENTS.default.md
index a1044ba0d..cdbb83258 100644
--- a/docs/AGENTS.default.md
+++ b/docs/AGENTS.default.md
@@ -8,26 +8,26 @@ read_when:
 
 ## First run (recommended)
 
-Clawdbot uses a dedicated workspace directory for the agent. Default: `~/.clawdbot/workspace`.
+Clawdbot uses a dedicated workspace directory for the agent. Default: `~/clawd` (configurable via `agent.workspace`).
 
 1) Create the workspace (if it doesn’t already exist):
 
 ```bash
-mkdir -p ~/.clawdbot/workspace
+mkdir -p ~/clawd
 ```
 
 2) Copy the default workspace templates into the workspace:
 
 ```bash
-cp docs/templates/AGENTS.md ~/.clawdbot/workspace/AGENTS.md
-cp docs/templates/SOUL.md ~/.clawdbot/workspace/SOUL.md
-cp docs/templates/TOOLS.md ~/.clawdbot/workspace/TOOLS.md
+cp docs/templates/AGENTS.md ~/clawd/AGENTS.md
+cp docs/templates/SOUL.md ~/clawd/SOUL.md
+cp docs/templates/TOOLS.md ~/clawd/TOOLS.md
 ```
 
 3) Optional: if you want the personal assistant skill roster, replace AGENTS.md with this file:
 
 ```bash
-cp docs/AGENTS.default.md ~/.clawdbot/workspace/AGENTS.md
+cp docs/AGENTS.default.md ~/clawd/AGENTS.md
 ```
 
 4) Optional: choose a different workspace by setting `agent.workspace` (supports `~`):
@@ -73,7 +73,7 @@ cp docs/AGENTS.default.md ~/.clawdbot/workspace/AGENTS.md
 If you treat this workspace as Clawd’s “memory”, make it a git repo (ideally private) so `AGENTS.md` and your memory files are backed up.
 
 ```bash
-cd ~/.clawdbot/workspace
+cd ~/clawd
 git init
 git add AGENTS.md
 git commit -m "Add Clawd workspace"
diff --git a/docs/browser-linux-troubleshooting.md b/docs/browser-linux-troubleshooting.md
index 33643634a..3cbd4dbe1 100644
--- a/docs/browser-linux-troubleshooting.md
+++ b/docs/browser-linux-troubleshooting.md
@@ -1,3 +1,8 @@
+---
+summary: "Fix Chrome/Chromium CDP startup issues for Clawdbot browser control on Linux"
+read_when: "Browser control fails on Linux, especially with snap Chromium"
+---
+
 # Browser Troubleshooting (Linux)
 
 ## Problem: "Failed to start Chrome CDP on port 18800"
diff --git a/docs/onboarding-config-protocol.md b/docs/onboarding-config-protocol.md
index 64da823b6..58eb2fa1e 100644
--- a/docs/onboarding-config-protocol.md
+++ b/docs/onboarding-config-protocol.md
@@ -1,3 +1,8 @@
+---
+summary: "RPC protocol notes for onboarding wizard and config schema"
+read_when: "Changing onboarding wizard steps or config schema endpoints"
+---
+
 # Onboarding + Config Protocol
 
 Purpose: shared onboarding + config surfaces across CLI, macOS app, and Web UI.
diff --git a/docs/onboarding.md b/docs/onboarding.md
index 948d1c2c2..200fd267e 100644
--- a/docs/onboarding.md
+++ b/docs/onboarding.md
@@ -102,7 +102,7 @@ Once setup is complete, the user can switch to the normal chat (`main`) via the
 
 We no longer collect identity in the onboarding wizard. Instead, the **first agent run** performs a playful bootstrap ritual using files in the workspace:
 
-- Workspace is created implicitly (default `~/.clawdbot/workspace`) when local is selected,
+- Workspace is created implicitly (default `~/clawd`, configurable via `agent.workspace`) when local is selected,
   but only if the folder is empty or already contains `AGENTS.md`.
 - Files are seeded: `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`.
 - `BOOTSTRAP.md` tells the agent to keep it conversational:
@@ -131,7 +131,7 @@ The workspace is created automatically as part of agent bootstrap (no dedicated
 Recommendation: treat the workspace as the agent’s “memory” and make it a git repo (ideally private) so identity + memories are backed up:
 
 ```bash
-cd ~/.clawdbot/workspace
+cd ~/clawd
 git init
 git add AGENTS.md
 git commit -m "Add agent workspace"
diff --git a/docs/remote-gateway-readme.md b/docs/remote-gateway-readme.md
index 98193a866..039955a6d 100644
--- a/docs/remote-gateway-readme.md
+++ b/docs/remote-gateway-readme.md
@@ -1,3 +1,8 @@
+---
+summary: "SSH tunnel setup for Clawdbot.app connecting to a remote gateway"
+read_when: "Connecting the macOS app to a remote gateway over SSH"
+---
+
 # Running Clawdbot.app with a Remote Gateway
 
 Clawdbot.app uses SSH tunneling to connect to a remote gateway. This guide shows you how to set it up.
diff --git a/docs/slack.md b/docs/slack.md
index 22f6654ba..a42b7cd53 100644
--- a/docs/slack.md
+++ b/docs/slack.md
@@ -1,3 +1,8 @@
+---
+summary: "Slack socket mode setup and Clawdbot config"
+read_when: "Setting up Slack or debugging Slack socket mode"
+---
+
 # Slack (socket mode)
 
 ## Setup