From ca1fa75a23b67b9a3a3f9f32bdd34b51c54c1e2a Mon Sep 17 00:00:00 2001
From: Yimikami <hi@yimikami.me>
Date: Wed, 11 Mar 2026 16:48:26 +0300
Subject: [PATCH] docs: clarify scoped installs and openclaw setup

---
 integrations/README.md                | 18 +++++++++++++-----
 integrations/github-copilot/README.md |  4 ++--
 integrations/openclaw/README.md       |  6 ++++++
 3 files changed, 21 insertions(+), 7 deletions(-)

diff --git a/integrations/README.md b/integrations/README.md
index 3bb0868..c51b039 100644
--- a/integrations/README.md
+++ b/integrations/README.md
@@ -21,18 +21,18 @@ supported agentic coding tools.
 # Install for all detected tools automatically
 ./scripts/install.sh
 
-# Install for a specific tool
+# Install a specific home-scoped tool
 ./scripts/install.sh --tool antigravity
 ./scripts/install.sh --tool gemini-cli
 ./scripts/install.sh --tool copilot
-./scripts/install.sh --tool opencode
 ./scripts/install.sh --tool openclaw
-./scripts/install.sh --tool cursor
-./scripts/install.sh --tool aider
-./scripts/install.sh --tool windsurf
 ./scripts/install.sh --tool claude-code
 ```
 
+For project-scoped tools such as OpenCode, Cursor, Aider, and Windsurf, run
+the installer from your target project root as shown in the tool-specific
+sections below.
+
 ## Regenerating Integration Files
 
 If you add or modify agents, regenerate all integration files:
@@ -114,6 +114,14 @@ See [opencode/README.md](opencode/README.md) for details.
 Each agent becomes an OpenClaw workspace containing `SOUL.md`, `AGENTS.md`,
 and `IDENTITY.md`.
 
+Before installing, generate the OpenClaw workspaces:
+
+```bash
+./scripts/convert.sh --tool openclaw
+```
+
+Then install them:
+
 ```bash
 ./scripts/install.sh --tool openclaw
 ```
diff --git a/integrations/github-copilot/README.md b/integrations/github-copilot/README.md
index 2065549..8c094b4 100644
--- a/integrations/github-copilot/README.md
+++ b/integrations/github-copilot/README.md
@@ -1,7 +1,7 @@
 # GitHub Copilot Integration
 
-The Agency works natively with GitHub Copilot. No conversion needed — agents work
-natively with the existing `.md` + YAML frontmatter format.
+The Agency works with GitHub Copilot out of the box. No conversion needed —
+agents use the existing `.md` + YAML frontmatter format.
 
 ## Install
 
diff --git a/integrations/openclaw/README.md b/integrations/openclaw/README.md
index 7d4a30d..7399e7a 100644
--- a/integrations/openclaw/README.md
+++ b/integrations/openclaw/README.md
@@ -5,6 +5,12 @@ and `IDENTITY.md` files. The installer copies each workspace into
 `~/.openclaw/agency-agents/` and registers it when the `openclaw` CLI is
 available.
 
+Before installing, generate the OpenClaw workspaces:
+
+```bash
+./scripts/convert.sh --tool openclaw
+```
+
 ## Install
 
 ```bash