From d66bd6439b1f5f726291654e00718061025b425a Mon Sep 17 00:00:00 2001
From: Affaan Mustafa <affaan@dcube.ai>
Date: Mon, 9 Mar 2026 21:10:46 -0700
Subject: [PATCH] docs: clarify opencode npm plugin scope

---
 .opencode/MIGRATION.md | 10 ++++++++++
 .opencode/README.md    | 11 ++++++++++-
 .opencode/index.ts     | 11 +++++++----
 README.md              |  7 +++++++
 4 files changed, 34 insertions(+), 5 deletions(-)

diff --git a/.opencode/MIGRATION.md b/.opencode/MIGRATION.md
index 2277d7ae..afb2507b 100644
--- a/.opencode/MIGRATION.md
+++ b/.opencode/MIGRATION.md
@@ -297,6 +297,15 @@ Then in your `opencode.json`:
 }
 ```
 
+This only loads the published ECC OpenCode plugin module (hooks/events and exported plugin tools).
+It does **not** automatically inject ECC's full `agent`, `command`, or `instructions` config into your project.
+
+If you want the full ECC OpenCode workflow surface, use the repository's bundled `.opencode/opencode.json` as your base config or copy these pieces into your project:
+- `.opencode/commands/`
+- `.opencode/prompts/`
+- `.opencode/instructions/INSTRUCTIONS.md`
+- the `agent` and `command` sections from `.opencode/opencode.json`
+
 ## Troubleshooting
 
 ### Configuration Not Loading
@@ -322,6 +331,7 @@ Then in your `opencode.json`:
 1. Verify the command is defined in `opencode.json` or as `.md` file in `.opencode/commands/`
 2. Check the referenced agent exists
 3. Ensure the template uses `$ARGUMENTS` for user input
+4. If you installed only `plugin: ["ecc-universal"]`, note that npm plugin install does not auto-add ECC commands or agents to your project config
 
 ## Best Practices
 
diff --git a/.opencode/README.md b/.opencode/README.md
index 60d901aa..eaaa73a5 100644
--- a/.opencode/README.md
+++ b/.opencode/README.md
@@ -32,7 +32,16 @@ Add to your `opencode.json`:
   "plugin": ["ecc-universal"]
 }
 ```
-After installation, the `ecc-install` CLI becomes available:
+
+This loads the ECC OpenCode plugin module from npm:
+- hook/event integrations
+- bundled custom tools exported by the plugin
+
+It does **not** auto-register the full ECC command/agent/instruction catalog in your project config. For the full OpenCode setup, either:
+- run OpenCode inside this repository, or
+- copy the relevant `.opencode/commands/`, `.opencode/prompts/`, `.opencode/instructions/`, and `agent` / `command` config entries into your own project
+
+After installation, the `ecc-install` CLI is also available:
 
 ```bash
 npx ecc-install typescript
diff --git a/.opencode/index.ts b/.opencode/index.ts
index 4b686715..c8736525 100644
--- a/.opencode/index.ts
+++ b/.opencode/index.ts
@@ -1,12 +1,10 @@
 /**
  * Everything Claude Code (ECC) Plugin for OpenCode
  *
- * This package provides a complete OpenCode plugin with:
- * - 13 specialized agents (planner, architect, code-reviewer, etc.)
- * - 31 commands (/plan, /tdd, /code-review, etc.)
+ * This package provides the published ECC OpenCode plugin module:
  * - Plugin hooks (auto-format, TypeScript check, console.log warning, env injection, etc.)
  * - Custom tools (run-tests, check-coverage, security-audit, format-code, lint-check, git-summary)
- * - 37 skills (coding-standards, security-review, tdd-workflow, etc.)
+ * - Bundled reference config/assets for the wider ECC OpenCode setup
  *
  * Usage:
  *
@@ -22,6 +20,10 @@
  * }
  * ```
  *
+ * That enables the published plugin module only. For ECC commands, agents,
+ * prompts, and instructions, use this repository's `.opencode/opencode.json`
+ * as a base or copy the bundled `.opencode/` assets into your project.
+ *
  * Option 2: Clone and use directly
  * ```bash
  * git clone https://github.com/affaan-m/everything-claude-code
@@ -51,6 +53,7 @@ export const metadata = {
     agents: 13,
     commands: 31,
     skills: 37,
+    configAssets: true,
     hookEvents: [
       "file.edited",
       "tool.execute.before",
diff --git a/README.md b/README.md
index 05e33b99..0426ed6c 100644
--- a/README.md
+++ b/README.md
@@ -1050,6 +1050,13 @@ Then add to your `opencode.json`:
 }
 ```
 
+That npm plugin entry enables ECC's published OpenCode plugin module (hooks/events and plugin tools).
+It does **not** automatically add ECC's full command/agent/instruction catalog to your project config.
+
+For the full ECC OpenCode setup, either:
+- run OpenCode inside this repository, or
+- copy the bundled `.opencode/` config assets into your project and wire the `agent` / `command` entries in `opencode.json`
+
 ### Documentation
 
 - **Migration Guide**: `.opencode/MIGRATION.md`