[OUAO-FRANK]

What I did

docs/installation-guides/install-opencode.md documents only the OpenCode v1 MCP configuration: servers directly under mcp, an enabled: true flag, camelCase OAuth fields, and a tools block for hiding tools. OpenCode v2 accepts none of those shapes, so a reader following the guide ends up with a server that never connects and no diagnostic that explains why.

The guide now leads with the version distinction and documents both shapes:

• v2 (new primary section). Servers live under mcp.servers, they connect automatically, and a server is disabled with "disabled": true. Remote and local examples are updated to that shape, plus the opencode mcp add / --url / --header / --global CLI path, /mcps for connect-disconnect-auth, opencode mcp list showing connected / needs authentication, permissions actions (matching <server>_<tool>) instead of a tools block, and the mcp.timeout startup / catalog / execution knobs.
• v1 (kept, moved below). The previous config shape is retained verbatim as its own section so existing v1 readers are not stranded, and the four differences are called out: no servers level, enabled versus disabled, camelCase versus snake_case OAuth fields, and tools versus permissions.
• Troubleshooting gained the failure that started this: a v2 config read by v1 (or the reverse) usually surfaces as a server that never connects, because the disabled/enabled field or the servers level is not recognised.

Everything that is version-independent is unchanged: the PAT and environment-variable guidance, the oauth: false explanation, the single-array command shape, the environment key, {env:VAR_NAME} interpolation, the toolset/context warning, and the Docker prerequisites.

Related issue

fixes #3450

(not mandatory) A picture of a cute animal, if possible in relation to what you did

   /\_/\
  ( o.o )   "my config was v1 in a v2 world"
   > ^ <    -- every OpenCode user, once

Verification

Documentation-only change; no code paths touched.

• git diff --stat → 1 file changed, 151 insertions(+), 69 deletions(-), all of it inside docs/installation-guides/install-opencode.md; no other file is modified.
• git ls-files --eol on the file reports i/lf w/lf, so the LF endings and the repository's line-ending policy are preserved (no whole-file churn from an editor).
• Every config snippet in the new text was checked against the current OpenCode documentation for v2 MCP servers (mcp.servers, disabled, permissions, mcp.timeout, opencode mcp add --url/--header/--global) and, for the v1 section, against the v1 page (mcp.<name>, enabled, tools, camelCase oauth fields).
• grep -n '"enabled"' docs/installation-guides/install-opencode.md now returns only the three intentional v1 occurrences; the v2 snippets use disabled.
• Links added in the change (https://opencode.ai/v2/docs/config, /v2/docs/permissions) resolve; the pre-existing relative links to ../server-configuration.md, ../oauth-login.md, ./README.md, and ../../README.md#available-toolsets are unchanged and still exist in the tree.

I did not run script/test or script/lint: neither covers Markdown content, and this diff contains no Go or UI files.