docs: config doc edits

packages/web/src/content/docs/docs/config.mdx

@@ -5,9 +5,11 @@ description: Using the opencode JSON config.
 
 You can configure opencode using a JSON config file.
 
+---
+
 ## Format
 
-opencode supports both JSON and JSONC (JSON with Comments) formats. You can use comments in your configuration files:
+opencode supports both **JSON** and **JSONC** (JSON with Comments) formats.
 
 ```jsonc title="opencode.jsonc"
 {
@@ -19,7 +21,14 @@ opencode supports both JSON and JSONC (JSON with Comments) formats. You can use
 }
 ```
 
-This can be used to configure opencode globally or for a specific project.
+With JSONC, you can use comments in your configuration files:
+
+---
+
+## Locations
+
+You can place your config in a couple of different locations and they have a
+different order of precedence.
 
 ---
 
@@ -31,7 +40,11 @@ Place your global opencode config in `~/.config/opencode/opencode.json`. You'll
 
 ### Per project
 
-You can also add a `opencode.json` in your project. This is useful for configuring providers or modes specific to your project.
+You can also add a `opencode.json` in your project. It takes precedence over the global config. This is useful for configuring providers or modes specific to your project.
+
+:::tip
+Place project specific config in the root of your project.
+:::
 
 When opencode starts up, it looks for a config file in the current directory or traverse up to the nearest Git directory.
 
@@ -39,9 +52,9 @@ This is also safe to be checked into Git and uses the same schema as the global
 
 ---
 
-### Custom config file
+### Custom path
 
-You can specify a custom config file using the `OPENCODE_CONFIG` environment variable. This takes precedence over the global and project configs.
+You can also specify a custom config file path using the `OPENCODE_CONFIG` environment variable. This takes precedence over the global and project configs.
 
 ```bash
 export OPENCODE_CONFIG=/path/to/my/custom-config.json
@@ -111,12 +124,29 @@ You can configure the theme you want to use in your opencode config through the
 
 ---
 
-### Logging
+### Agents
+
+You can configure specialized agents for specific tasks through the `agent` option.
 
-Logs are written to:
+```jsonc title="opencode.jsonc"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "code-reviewer": {
+      "description": "Reviews code for best practices and potential issues",
+      "model": "anthropic/claude-sonnet-4-20250514",
+      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
+      "tools": {
+        // Disable file modification tools for review-only agent
+        "write": false,
+        "edit": false,
+      },
+    },
+  },
+}
+```
 
-- **macOS/Linux**: `~/.local/share/opencode/log/`
-- **Windows**: `%APPDATA%\opencode\log\`
+You can also define agents using markdown files in `~/.config/opencode/agent/` or `.opencode/agent/`. [Learn more here](/docs/agents).
 
 ---
 
@@ -169,118 +199,96 @@ opencode will automatically download any new updates when it starts up. You can
 
 ---
 
-### MCP servers
+### Formatters
 
-You can configure MCP servers you want to use through the `mcp` option.
+You can configure code formatters through the `formatter` option.
 
 ```json title="opencode.json"
 {
   "$schema": "https://opencode.ai/config.json",
-  "mcp": {}
+  "formatter": {
+    "prettier": {
+      "disabled": true
+    },
+    "custom-prettier": {
+      "command": ["npx", "prettier", "--write", "$FILE"],
+      "environment": {
+        "NODE_ENV": "development"
+      },
+      "extensions": [".js", ".ts", ".jsx", ".tsx"]
+    }
+  }
 }
 ```
 
-[Learn more here](/docs/mcp-servers).
+[Learn more about formatters here](/docs/formatters).
 
 ---
 
-### Instructions
+### Permissions
 
-You can configure the instructions for the model you're using through the `instructions` option.
+You can configure permissions to control what AI agents can do in your codebase through the `permission` option.
 
 ```json title="opencode.json"
 {
   "$schema": "https://opencode.ai/config.json",
-  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
+  "permission": {
+    "edit": "ask",
+    "bash": "ask"
+  }
 }
 ```
 
-This takes an array of paths and glob patterns to instruction files. [Learn more
-about rules here](/docs/rules).
+[Learn more about permissions here](/docs/permissions).
 
 ---
 
-### Agents
+### MCP servers
 
-You can configure specialized agents for specific tasks through the `agent` option.
+You can configure MCP servers you want to use through the `mcp` option.
 
-```jsonc title="opencode.jsonc"
+```json title="opencode.json"
 {
   "$schema": "https://opencode.ai/config.json",
-  "agent": {
-    "code-reviewer": {
-      "description": "Reviews code for best practices and potential issues",
-      "model": "anthropic/claude-sonnet-4-20250514",
-      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
-      "tools": {
-        // Disable file modification tools for review-only agent
-        "write": false,
-        "edit": false,
-      },
-    },
-  },
+  "mcp": {}
 }
 ```
 
-You can also define agents using markdown files in `~/.config/opencode/agent/` or `.opencode/agent/`. [Learn more here](/docs/agents).
+[Learn more here](/docs/mcp-servers).
 
 ---
 
-### Disabled providers
-
-You can disable providers that are loaded automatically through the `disabled_providers` option. This is useful when you want to prevent certain providers from being loaded even if their credentials are available.
-
-The `disabled_providers` option accepts an array of provider IDs. When a provider is disabled:
-
-- It won't be loaded even if environment variables are set
-- It won't be loaded even if API keys are configured through `opencode auth login`
-- The provider's models won't appear in the model selection list
+### Instructions
 
+You can configure the instructions for the model you're using through the `instructions` option.
 
 ```json title="opencode.json"
 {
   "$schema": "https://opencode.ai/config.json",
-  "disabled_providers": ["openai", "gemini"]
+  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
 }
 ```
 
----
+This takes an array of paths and glob patterns to instruction files. [Learn more
+about rules here](/docs/rules).
 
-### Formatters
+---
 
-You can configure code formatters through the `formatter` option. See [Formatters documentation](/docs/formatters) for more details.
+### Disabled providers
 
-```json title="opencode.json"
-{
-  "$schema": "https://opencode.ai/config.json",
-  "formatter": {
-    "prettier": {
-      "disabled": true
-    },
-    "custom-prettier": {
-      "command": ["npx", "prettier", "--write", "$FILE"],
-      "environment": {
-        "NODE_ENV": "development"
-      },
-      "extensions": [".js", ".ts", ".jsx", ".tsx"]
-    }
-  }
-}
-```
+You can disable providers that are loaded automatically through the `disabled_providers` option. This is useful when you want to prevent certain providers from being loaded even if their credentials are available.
 
----
+The `disabled_providers` option accepts an array of provider IDs. When a provider is disabled:
 
-### Permissions
+- It won't be loaded even if environment variables are set
+- It won't be loaded even if API keys are configured through `opencode auth login`
+- The provider's models won't appear in the model selection list
 
-You can configure permissions to control what AI agents can do in your codebase through the `permission` option.
 
 ```json title="opencode.json"
 {
   "$schema": "https://opencode.ai/config.json",
-  "permission": {
-    "edit": "ask",
-    "bash": "ask"
-  }
+  "disabled_providers": ["openai", "gemini"]
 }
 ```