docs: clarify OpenCode plugin configuration

Clarify how to attach Plannotator options when OpenCode has multiple plugins, and link the landing page OpenCode tab to setup and migration docs.

Author: backnotprop

apps/marketing/src/components/landing/HeroSection.astro

@@ -213,7 +213,17 @@ import AnnoReplace from './AnnoReplace.astro';
           '"plugin": ["@plannotator/opencode@latest"]',
           'Restart OpenCode to load the plugin'
         ],
-        detail: 'Then add to opencode.json:'
+        detail: 'Then add to opencode.json:',
+        links: [
+          {
+            text: 'OpenCode setup and custom agents',
+            url: '/docs/guides/opencode/#custom-planning-agents'
+          },
+          {
+            text: '0.19.1 migration guide',
+            url: '/docs/guides/opencode-migration-0-19-1/'
+          }
+        ]
       },
       copilot: {
         steps: [
@@ -283,18 +293,26 @@ import AnnoReplace from './AnnoReplace.astro';
         stepsEl.classList.add('hidden');
       }
 
-      // Handle marketplace link
+      // Handle documentation and marketplace links
       if (linkEl) { linkEl.remove(); linkEl = null; }
-      if (config.link) {
-        var a = document.createElement('a');
-        a.id = 'install-link';
-        a.href = config.link.url;
-        a.target = '_blank';
-        a.rel = 'noopener noreferrer';
-        a.className = 'mt-3 text-sm hidden sm:inline-flex items-center gap-1.5 text-muted-foreground hover:text-foreground transition-colors';
-        a.innerHTML = config.link.text + ' <svg class="w-3.5 h-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2"><path stroke-linecap="round" stroke-linejoin="round" d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14"/></svg>';
-        installBlock.parentNode.insertBefore(a, installBlock.nextSibling);
-        linkEl = a;
+      var links = config.links || (config.link ? [config.link] : []);
+      if (links.length) {
+        var linkWrap = document.createElement('div');
+        linkWrap.id = 'install-link';
+        linkWrap.className = 'mt-3 hidden sm:flex flex-wrap items-center gap-x-4 gap-y-1';
+
+        links.forEach(function(link) {
+          var a = document.createElement('a');
+          a.href = link.url;
+          a.target = link.url.charAt(0) === '/' ? '_self' : '_blank';
+          if (a.target === '_blank') a.rel = 'noopener noreferrer';
+          a.className = 'text-sm inline-flex items-center gap-1.5 text-muted-foreground hover:text-foreground transition-colors';
+          a.innerHTML = link.text + ' <svg class="w-3.5 h-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2"><path stroke-linecap="round" stroke-linejoin="round" d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14"/></svg>';
+          linkWrap.appendChild(a);
+        });
+
+        installBlock.parentNode.insertBefore(linkWrap, installBlock.nextSibling);
+        linkEl = linkWrap;
       }
     }
 

apps/marketing/src/content/docs/getting-started/configuration.md

@@ -73,6 +73,22 @@ To configure the workflow explicitly:
 }
 ```
 
+When Plannotator is used with other OpenCode plugins, the options object must stay attached to the Plannotator plugin entry:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["@plannotator/opencode@latest", {
+      "workflow": "plan-agent",
+      "planningAgents": ["plan", "sisyphus"]
+    }],
+    "oh-my-opencode-slim",
+    "openviking-opencode"
+  ]
+}
+```
+
 Use `workflow: "manual"` for commands-only mode, or `workflow: "all-agents"` to restore the legacy behavior where primary agents can call `submit_plan`. In `plan-agent` mode, any names listed in `planningAgents` are added alongside OpenCode's built-in `plan` agent. Slash commands (`/plannotator-review`, `/plannotator-annotate`, `/plannotator-last`) require the CLI to be installed separately via the install script.
 
 If you are upgrading from an older OpenCode install, see the [OpenCode 0.19.1 migration guide](/docs/guides/opencode-migration-0-19-1/).

apps/marketing/src/content/docs/guides/opencode-migration-0-19-1.md

@@ -136,6 +136,24 @@ Add it explicitly. OpenCode's built-in `plan` agent stays enabled in `plan-agent
 }
 ```
 
+If you also use other OpenCode plugins, keep Plannotator as the two-item array entry and put the other plugins beside it:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["@plannotator/opencode@latest", {
+      "workflow": "plan-agent",
+      "planningAgents": ["planner", "sisyphus"]
+    }],
+    "oh-my-opencode-slim",
+    "openviking-opencode"
+  ]
+}
+```
+
+Do not put `{ "workflow": "plan-agent" }` as a separate item in the `plugin` array. OpenCode expects each plugin entry to be either a string or `[pluginName, options]`.
+
 ### I upgraded but OpenCode still looks stale
 
 Restart OpenCode after upgrading. If a cached plugin version is still being used, rerun the install script or clear the OpenCode cache and restart.

apps/marketing/src/content/docs/guides/opencode.md

@@ -42,6 +42,25 @@ Default config:
 }
 ```
 
+If you use other OpenCode plugins, keep everything in the same `plugin` array and attach Plannotator's options directly to the Plannotator entry:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["@plannotator/opencode@latest", {
+      "workflow": "plan-agent",
+      "planningAgents": ["plan", "sisyphus"]
+    }],
+    "@tarquinen/opencode-dcp@latest",
+    "octto",
+    "oh-my-opencode-slim"
+  ]
+}
+```
+
+Do not put `{ "workflow": "plan-agent" }` as its own item in the `plugin` array. OpenCode plugin entries must be either a plugin string or a two-item array like `[pluginName, options]`.
+
 If you want the old broad behavior:
 
 ```json
@@ -68,6 +87,38 @@ If you want commands only:
 }
 ```
 
+## Custom planning agents
+
+OpenCode's built-in `plan` agent is always included in `plan-agent` mode. If you use another planning agent, add its OpenCode agent name to `planningAgents`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["@plannotator/opencode@latest", {
+      "workflow": "plan-agent",
+      "planningAgents": ["planner", "sisyphus"]
+    }]
+  ]
+}
+```
+
+With other plugins, the same rule applies. Only the Plannotator entry becomes a tuple with options:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["@plannotator/opencode@latest", {
+      "workflow": "plan-agent",
+      "planningAgents": ["planner", "sisyphus"]
+    }],
+    "oh-my-opencode-slim",
+    "openviking-opencode"
+  ]
+}
+```
+
 ## Approve with annotations
 
 Unlike Claude Code, OpenCode supports feedback on approval. This means:

apps/opencode-plugin/README.md

@@ -58,6 +58,25 @@ Default config:
 }
 ```
 
+If you use other OpenCode plugins, keep everything in one `plugin` array and attach Plannotator's options directly to the Plannotator entry:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["@plannotator/opencode@latest", {
+      "workflow": "plan-agent",
+      "planningAgents": ["plan", "sisyphus"]
+    }],
+    "@tarquinen/opencode-dcp@latest",
+    "octto",
+    "oh-my-opencode-slim"
+  ]
+}
+```
+
+Do not put `{ "workflow": "plan-agent" }` as its own item in the `plugin` array. OpenCode plugin entries must be either a plugin string or a two-item array like `[pluginName, options]`.
+
 Restore the old broad behavior:
 
 ```json