Merge pull request #59 from mvanhorn/docs/plugin-target-troubleshooting

docs: add "confirm your Paperclip host" troubleshooting note

Author: superbiche

README.md

@@ -169,6 +169,10 @@ curl -X POST http://127.0.0.1:3100/api/plugins/install \
 > **Note — `paperclipai` master, post [#5429](https://github.com/paperclipai/paperclip/pull/5429) (2026-05-09):**
 > The new Secrets Manager ships with a temporary kill switch on plugin secret-ref UUIDs while a company-scoped `plugin_config` follow-up lands. If you're running paperclipai master, plugin activation will fail with `Plugin secret references are disabled until company-scoped plugin config lands`, and `POST /api/plugins/:id/config` returns HTTP 422 for configs containing secret-ref UUIDs (e.g. `discordBotTokenRef`). This is intentional fail-closed mitigation (PAP-2394 — see the [upstream plan doc](https://github.com/paperclipai/paperclip/blob/master/doc/plans/2026-04-26-plugin-secret-ref-company-scope.md)). Until the follow-up lands, pin to the last paperclipai release before #5429. This callout will be removed once secret-ref resolution is restored.
 
+## Troubleshooting: confirm your Paperclip host
+
+Before filing a bug, confirm which Paperclip host this plugin is actually talking to. Run `paperclipai plugin target` ([#8575](https://github.com/paperclipai/paperclip/pull/8575)) — it prints the resolved API URL plus the server's status, version, deploymentMode, and deploymentExposure *before* anything is installed. A server version older than this plugin expects is the most common cause of activation failures and secret-resolution errors (e.g. `discordBotTokenRef` not resolving) that look like plugin bugs but aren't. If the URL or version is wrong, point Paperclip at the right host — or update the server — before opening an issue.
+
 ## Setup
 
 1. Create a Discord application at https://discord.com/developers/applications