Config docs should clarify that .opencode/opencode.json{,c} is loaded as a config source

[rich-jojo]

Summary

I noticed a mismatch between the published config docs and the current implementation.

The docs currently describe config precedence as:

1. remote config
2. global config
3. custom config
4. project config (opencode.json in project)
5. .opencode directories — agents, commands, plugins
6. inline config

That wording makes .opencode sound directory-only, not file-based.

But the implementation in packages/opencode/src/config/config.ts explicitly loads:

• .opencode/opencode.jsonc
• .opencode/opencode.json

as part of config precedence.

Evidence

In packages/opencode/src/config/config.ts:

// 5) .opencode directories (.opencode/agents/, .opencode/commands/, .opencode/plugins/, .opencode/opencode.json{,c})

and later:

if (dir.endsWith(".opencode") || dir === Flag.OPENCODE_CONFIG_DIR) {
  for (const file of ["opencode.jsonc", "opencode.json"]) {
    result = mergeConfigConcatArrays(result, await loadFile(path.join(dir, file)))
  }
}

But the public docs at packages/web/src/content/docs/config.mdx only say:

5. .opencode directories - agents, commands, plugins

Why this matters

Tooling and contributors can reasonably read the docs and conclude that .opencode/opencode.json is not an officially supported config file location.

That makes it harder to know whether behavior around .opencode/opencode.json is intentional API surface or just incidental implementation detail.

Suggested fix

Clarify the docs so step 5 explicitly mentions .opencode/opencode.json{,c} if that support is intentional.

If it is not intended to be supported, then the implementation and/or comments should be tightened instead.

[github-actions]

This issue might be related to an existing issue. Please check:

• docs: path for mcp configuration is inconsistent (.opencode.jsonc and .opencode.json) #13459: Similar docs inconsistency around .opencode.jsonc vs .opencode.json path naming in the MCP docs

They cover slightly different aspects (MCP docs vs config precedence docs), but the underlying confusion is related — the docs don't clearly communicate how .opencode/opencode.json{,c} is used as a config source.

[rich-jojo]

Closing because I am no longer tracking or upstreaming my own backlog in non-owned repos.