diff --git a/docs/user-guide.md b/docs/user-guide.md
index 65cba22b..0692ef14 100644
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -187,6 +187,53 @@ If you want to do the planning on the web with Claude (Sonnet 4 or Opus), Gemini
 npx bmad-method install
 ```
 
+### OpenCode (SST)
+
+BMAD integrates with SST OpenCode via a project-level `opencode.jsonc`/`opencode.json` (JSON-only, no Markdown fallback).
+
+- Installation:
+  - Run `npx bmad-method install` and choose `OpenCode (SST)` in the IDE list.
+  - The installer will detect an existing `opencode.jsonc`/`opencode.json` or create a minimal `opencode.jsonc` if missing.
+  - It will:
+    - Ensure `instructions` includes `.bmad-core/core-config.yaml` (and each selected expansion pack’s `config.yaml`).
+    - Merge BMAD agents and commands using file references (`{file:./.bmad-core/...}`), idempotently.
+    - Preserve other top-level fields and user-defined entries.
+
+- Prefixes and collisions:
+  - You can opt-in to prefix agent keys with `bmad-` and command keys with `bmad:tasks:` to avoid name collisions.
+  - If a key already exists and is not BMAD-managed, the installer will skip it and suggest enabling prefixes.
+
+- What gets added:
+  - `instructions`: `.bmad-core/core-config.yaml` plus any selected expansion pack `config.yaml` files.
+  - `agent`: BMAD agents from core and selected packs.
+    - `prompt`: `{file:./.bmad-core/agents/<id>.md}` (or pack path)
+    - `mode`: `primary` for orchestrators, otherwise `subagent`
+    - `tools`: `{ write: true, edit: true, bash: true }`
+    - `description`: extracted from the agent’s `whenToUse`
+  - `command`: BMAD tasks from core and selected packs.
+    - `template`: `{file:./.bmad-core/tasks/<id>.md}` (or pack path)
+    - `description`: extracted from the task’s “Purpose” section
+
+- Selected Packages Only:
+  - The installer includes agents and tasks only from the packages you selected in the earlier step (core and chosen packs).
+
+- Refresh after changes:
+  - Re-run:
+    ```bash
+    npx bmad-method install -f -i opencode
+    ```
+  - The installer safely updates entries without duplication and preserves your custom fields and comments.
+
+- Optional convenience script:
+  - You can add a script to your project’s `package.json` for quick refreshes:
+    ```json
+    {
+      "scripts": {
+        "bmad:opencode": "bmad-method install -f -i opencode"
+      }
+    }
+    ```
+
 ### Codex (CLI & Web)
 
 BMAD integrates with OpenAI Codex via `AGENTS.md` and committed core agent files.
diff --git a/tools/installer/lib/ide-setup.js b/tools/installer/lib/ide-setup.js
index 73c38c85..d80681dd 100644
--- a/tools/installer/lib/ide-setup.js
+++ b/tools/installer/lib/ide-setup.js
@@ -401,6 +401,12 @@ class IdeSetup extends BaseIdeSetup {
           summary.agentsUpdated++;
         } else {
           summary.agentsSkipped++;
+          // Collision warning: key exists but does not appear BMAD-managed (different prompt path)
+          console.log(
+            chalk.yellow(
+              `⚠︎ Skipped agent key '${key}' (existing entry not BMAD-managed). Tip: enable agent prefixes to avoid collisions.`,
+            ),
+          );
         }
       }
 
@@ -437,6 +443,11 @@ class IdeSetup extends BaseIdeSetup {
             summary.agentsUpdated++;
           } else {
             summary.agentsSkipped++;
+            console.log(
+              chalk.yellow(
+                `⚠︎ Skipped agent key '${prefixedKey}' (existing entry not BMAD-managed). Tip: enable agent prefixes to avoid collisions.`,
+              ),
+            );
           }
         }
       }
@@ -466,6 +477,11 @@ class IdeSetup extends BaseIdeSetup {
           summary.commandsUpdated++;
         } else {
           summary.commandsSkipped++;
+          console.log(
+            chalk.yellow(
+              `⚠︎ Skipped command key '${key}' (existing entry not BMAD-managed). Tip: enable command prefixes to avoid collisions.`,
+            ),
+          );
         }
       }
 
@@ -495,6 +511,11 @@ class IdeSetup extends BaseIdeSetup {
             summary.commandsUpdated++;
           } else {
             summary.commandsSkipped++;
+            console.log(
+              chalk.yellow(
+                `⚠︎ Skipped command key '${prefixedKey}' (existing entry not BMAD-managed). Tip: enable command prefixes to avoid collisions.`,
+              ),
+            );
           }
         }
       }