diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9dc859b..aea077c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -27,7 +27,7 @@ Point OpenCode at the checkout while developing:
 
 The directory form lets OpenCode resolve the package's `./server` export and enforce its `engines.opencode` range.
 
-For a quick drop-in test, you can instead copy `index.js` to `.opencode/plugins/sprites.js`; global drop-ins live at `~/.config/opencode/plugins/`. OpenCode loads drop-ins as bare file specifiers, so they cannot receive a plugin options object. Use the package-directory form when testing non-default options.
+Do not copy or symlink `index.js` into `.opencode/plugins/` or `~/.config/opencode/plugins/`. It is a package entry point rather than a drop-in file plugin, and the TUI may try to load it through the wrong plugin path. Drop-in plugins also cannot receive an options object. Use package-directory configuration for local development.
 
 ## Run checks
 
diff --git a/README.md b/README.md
index bb9ff0f..d39599f 100644
--- a/README.md
+++ b/README.md
@@ -32,6 +32,8 @@ If the package is not yet available from npm, clone this repository and point Op
 
 Use an absolute `file://` URL. This installation form has the same features as the npm package.
 
+Use the package-directory entry shown above rather than copying or symlinking `index.js` into an OpenCode `plugins` directory. This plugin uses its package `./server` export and is not distributed as a drop-in file plugin.
+
 ## Authenticate
 
 Run `/sprites-status` or ask OpenCode to list your Sprites. The first Sprites request should start OpenCode's browser OAuth flow.