config: published schema at opencode.ai/config.json rejects documented V2 fields (skills, mcp.*, permissions)

Summary

The JSON Schema served at https://opencode.ai/config.json — the URL referenced by $schema in every V2 config — describes an older/hybrid shape that does not match current V2 documentation. As a result, editor IntelliSense and any standards-based validator flag valid V2 configs as invalid, including configs whose fields are copied verbatim from the V2 docs. This also actively misleads users: for MCP, the stale schema suggests adding an enabled key, while V2 explicitly has no enabled field.

Environment

• opencode version: 0.0.0-beta-17759
• OS: Darwin 27.0.0 (arm64)
• Terminal: Apple_Terminal (xterm-256color)
• Shell: /bin/zsh
• Install/channel: beta
• Active plugins: one local plugin (subagent-session-guard.ts); unrelated to this issue

Reproduction

1. Create ~/.config/opencode/opencode.json using examples taken verbatim from the V2 docs:

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [{ "action": "shell", "resource": "git push *", "effect": "ask" }],
  "skills": ["./team-skills"],
  "mcp": {
    "timeout": { "startup": 45000, "catalog": 30000, "execution": 600000 },
    "servers": {
      "everything": {
        "type": "local",
        "command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
      }
    }
  }
}

2. Run opencode2 debug config → exits 0, parses and normalizes everything. opencode2 mcp list shows the server connecting. The runtime accepts all fields.

3. Validate the same file against the published schema with any JSON-Schema validator:

curl -sS https://opencode.ai/config.json -o schema.json
python3 - <<'EOF'
import json, jsonschema
schema = json.load(open("schema.json"))
config = json.load(open("opencode.json"))
for err in jsonschema.Draft202012Validator(schema).iter_errors(config):
    print("/".join(map(str, err.absolute_path)), "->", err.message)
EOF

Expected Behavior

A config following current V2 documentation should validate cleanly against the schema its own $schema field points to.

Actual Behavior

The validator reports errors on documented V2 fields:

/skills -> ['~/.config/opencode/skills'] is not of type 'object'
/mcp/timeout -> {'startup': 45000, ...} is not valid under any of the given schemas
/mcp/servers -> {'everything': {...}} is not valid under any of the given schemas
/ -> Additional properties are not allowed ('permissions' was unexpected)

Specific mismatches between the published schema and the V2 docs:

Also flagged on a real-world config: experimental.subagent_depth and model-level reasoning_efforts.

The MCP case is worse than cosmetic: because the schema's only accepted shapes mention enabled, anyone "fixing" their config to satisfy validators will add a field that V2 does not support.

Additional Context

• This is pure schema/docs drift — the beta runtime handles all of these fields correctly, so the schema appears to predate the V2 config format.
• Since V2 configs ship with this $schema URL, editors (VS Code, Zed, etc.) show spurious diagnostics on doc-recommended configs, and third-party tooling built on the schema reports the same false positives.
• Reproduced consistently with jsonschema Draft202012Validator (18 errors on a real-world V2 config that loads cleanly in the CLI).
• Suggestion: regenerate the published schema from the current V2 types, and/or serve a versioned schema (e.g. /v2/config.json) so older editors keep working while V2 configs get accurate validation.