docs: add v2 configuration reference

packages/docs/AGENTS.md

@@ -0,0 +1,22 @@
+# V2 documentation guide
+
+## Structure
+
+- This directory is a standalone Mintlify site deployed from `packages/docs` on the `dev` branch.
+- Write documentation in MDX. Every page should have `title` and `description` frontmatter.
+- `docs.json` owns site configuration and navigation. Add, move, or remove its page entries whenever the corresponding MDX pages change.
+- Put static files in `assets/` and reference them with root-relative paths such as `/assets/example.svg`.
+- The API endpoint reference is generated by Mintlify from `openapi.json`; do not duplicate endpoint documentation as hand-written MDX.
+- Keep documentation aligned with the V2 packages. Do not use `packages/opencode` as the source of truth unless the task explicitly concerns V1.
+
+## Local development
+
+- At the start of documentation work, launch `bun dev` from `packages/docs` using the shell tool with `background: true`. Never run the dev server in a foreground shell call and do not poll the process; wait for the background completion notification.
+- Preview the site at `http://localhost:3333`. Mintlify does not expose a host option and binds the preview to all network interfaces. The server reloads changes to MDX and `docs.json` automatically.
+- Use the running preview to verify navigation, links, Mintlify components, code blocks, and desktop and mobile layout.
+
+## Validation
+
+- Run `bun validate` from `packages/docs` after making documentation or configuration changes.
+- Run `bun broken-links` from `packages/docs` when pages, navigation, headings, or links change.
+- Treat validation errors and broken internal links as blockers. Also verify external links relevant to the change when practical.

packages/docs/README.md

@@ -4,21 +4,19 @@ The V2 documentation is a Mintlify site deployed from `packages/docs` on the `de
 
 ## Local preview
 
-The Mintlify CLI requires Node.js 20 through 24.
-
 From this directory, run:
 
 ```bash
-npx mint dev
+bun dev
 ```
 
-The preview opens at `http://localhost:3000` and reloads when MDX or `docs.json` changes.
+The preview opens at `http://localhost:3333` and reloads when MDX or `docs.json` changes.
 
 Validate changes before opening a pull request:
 
 ```bash
-npx mint validate
-npx mint broken-links
+bun validate
+bun broken-links
 ```
 
 The hosted preview is available at [opencode.mintlify.site](https://opencode.mintlify.site).

packages/docs/config.mdx

@@ -6,3 +6,439 @@ description: "Configure OpenCode."
 <Tip>
   You shouldn't have to configure OpenCode manually. Ask OpenCode to update its configuration for you.
 </Tip>
+
+## Format
+
+OpenCode supports both **JSON** and **JSONC** (JSON with Comments) configuration files.
+
+```jsonc title="opencode.jsonc"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "openai/gpt-5.2-custom",
+  "providers": {
+    "openai": {
+      "models": {
+        "gpt-5.2-custom": {
+          "modelID": "gpt-5.2",
+          "name": "GPT-5.2 Custom"
+        }
+      }
+    }
+  }
+}
+```
+
+## Locations
+
+OpenCode loads global configuration from:
+
+```text
+~/.config/opencode/opencode.json(c)
+```
+
+Project-specific configuration can use either form:
+
+```text
+/home/user/projects/my-app/opencode.json(c)
+/home/user/projects/my-app/.opencode/opencode.json(c)
+```
+
+When OpenCode starts, it searches for configuration files from the current
+directory upward to the project root. The files are merged, and configuration
+closer to the current directory takes precedence.
+
+For example, consider a monorepo with OpenCode started from
+`/home/user/projects/acme/packages/web`:
+
+```text
+~/.config/opencode/opencode.json
+
+/home/user/projects/acme/
+├── opencode.json
+└── packages/
+    └── web/
+        ├── opencode.json
+        └── src/
+```
+
+OpenCode applies these files from lowest to highest precedence:
+
+1. `~/.config/opencode/opencode.json`
+2. `/home/user/projects/acme/opencode.json`
+3. `/home/user/projects/acme/packages/web/opencode.json`
+
+Settings in the package config override matching settings from the repository
+config, which override matching settings from the global config. Settings that
+do not conflict are preserved from every file.
+
+## Schema
+
+The complete OpenCode configuration schema is available at
+[opencode.ai/config.json](https://opencode.ai/config.json).
+
+Add the `$schema` field to your configuration file to enable validation and
+autocomplete in editors that support JSON Schema:
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json"
+}
+```
+
+Use the schema as the source of truth for available fields, accepted values,
+and nested configuration shapes.
+
+### Shell
+
+Set the shell used by the terminal and shell tools.
+
+```jsonc
+{
+  "shell": "/bin/zsh"
+}
+```
+
+### Model
+
+Set the default model in `provider/model` format. Add `#variant` to select a
+specific model variant.
+
+```jsonc
+{
+  "model": "anthropic/claude-sonnet-4-5#high"
+}
+```
+
+See the [models guide](https://opencode.ai/docs/models/) for model selection
+and local models.
+
+### Default agent
+
+Choose the primary agent used when a session does not select one explicitly.
+
+```jsonc
+{
+  "default_agent": "build"
+}
+```
+
+See the [agents guide](https://opencode.ai/docs/agents/) for built-in and custom
+agents.
+
+### Autoupdate
+
+Control automatic updates. Set this to `false` to disable updates or `"notify"`
+to receive update notifications.
+
+```jsonc
+{
+  "autoupdate": false
+}
+```
+
+### Sharing
+
+Control whether sessions can be shared manually, shared automatically, or not
+shared at all.
+
+```jsonc
+{
+  "share": "manual"
+}
+```
+
+See the [sharing guide](https://opencode.ai/docs/share/) for more details.
+
+### Username
+
+Set the username displayed in conversations.
+
+```jsonc
+{
+  "username": "alice"
+}
+```
+
+### Permissions
+
+Define ordered rules that allow, deny, or ask before an agent uses a tool on a
+matching resource.
+
+```jsonc
+{
+  "permissions": [
+    {
+      "action": "bash",
+      "resource": "git push *",
+      "effect": "ask"
+    }
+  ]
+}
+```
+
+See the [permissions guide](https://opencode.ai/docs/permissions/) for rule
+matching and available actions.
+
+### Agents
+
+Override built-in agents or define specialized agents with their own model,
+instructions, mode, and permissions.
+
+```jsonc
+{
+  "agents": {
+    "reviewer": {
+      "description": "Review changes without editing files",
+      "mode": "subagent",
+      "system": "Focus on correctness, security, and missing tests.",
+      "permissions": [
+        { "action": "edit", "resource": "*", "effect": "deny" }
+      ]
+    }
+  }
+}
+```
+
+See the [agents guide](https://opencode.ai/docs/agents/) for all agent options
+and file-based agents.
+
+### Snapshots
+
+Enable or disable the snapshots used by undo and revert behavior.
+
+```jsonc
+{
+  "snapshots": false
+}
+```
+
+### Watcher
+
+Ignore files and directories that should not trigger filesystem updates.
+
+```jsonc
+{
+  "watcher": {
+    "ignore": ["dist/**", "coverage/**"]
+  }
+}
+```
+
+### Formatter
+
+Enable built-in formatters, disable formatting entirely, or configure formatter
+commands by name.
+
+```jsonc
+{
+  "formatter": {
+    "prettier": {
+      "command": ["bunx", "prettier", "--write", "$FILE"],
+      "extensions": [".js", ".ts", ".tsx"]
+    }
+  }
+}
+```
+
+See the [formatters guide](https://opencode.ai/docs/formatters/) for built-in
+formatters and custom commands.
+
+### LSP
+
+Enable built-in language servers, disable them, or configure servers by name.
+
+```jsonc
+{
+  "lsp": {
+    "typescript": {
+      "command": ["typescript-language-server", "--stdio"],
+      "extensions": [".ts", ".tsx"]
+    }
+  }
+}
+```
+
+See the [LSP guide](https://opencode.ai/docs/lsp/) for language server setup.
+
+### Attachments
+
+Control how oversized image attachments are resized or rejected before they are
+sent to a model.
+
+```jsonc
+{
+  "attachments": {
+    "image": {
+      "auto_resize": true,
+      "max_width": 2000,
+      "max_height": 2000,
+      "max_base64_bytes": 5242880
+    }
+  }
+}
+```
+
+### Tool output
+
+Set the maximum number of lines and bytes retained from a tool result.
+
+```jsonc
+{
+  "tool_output": {
+    "max_lines": 2000,
+    "max_bytes": 51200
+  }
+}
+```
+
+### MCP
+
+Configure local and remote Model Context Protocol servers. Global timeouts can
+be overridden by an individual server.
+
+```jsonc
+{
+  "mcp": {
+    "servers": {
+      "playwright": {
+        "type": "local",
+        "command": ["bunx", "@playwright/mcp"]
+      }
+    }
+  }
+}
+```
+
+See the [MCP guide](https://opencode.ai/docs/mcp-servers/) for remote servers,
+OAuth, environment variables, and timeouts.
+
+### Compaction
+
+Control automatic context compaction and how much recent context it preserves.
+
+```jsonc
+{
+  "compaction": {
+    "auto": true,
+    "keep": {
+      "tokens": 8000
+    },
+    "buffer": 20000
+  }
+}
+```
+
+### Skills
+
+Add directories or URLs that OpenCode should search for agent skills.
+
+```jsonc
+{
+  "skills": ["./team-skills", "https://example.com/.well-known/skills/"]
+}
+```
+
+See the [skills guide](https://opencode.ai/docs/skills/) for skill structure and
+automatic discovery under `.opencode/skills/`.
+
+### Commands
+
+Define reusable slash commands as named prompt templates.
+
+```jsonc
+{
+  "commands": {
+    "review": {
+      "description": "Review the current changes",
+      "template": "Review the current diff for correctness and missing tests."
+    }
+  }
+}
+```
+
+See the [commands guide](https://opencode.ai/docs/commands/) for arguments,
+models, agents, and file-based commands.
+
+### Instructions
+
+Load additional instruction files, globs, or URLs into the agent's context.
+
+```jsonc
+{
+  "instructions": ["CONTRIBUTING.md", "docs/guidelines/*.md"]
+}
+```
+
+See the [rules guide](https://opencode.ai/docs/rules/) for project instructions
+and `AGENTS.md`.
+
+### References
+
+Make local directories or Git repositories available as named supporting
+context.
+
+```jsonc
+{
+  "references": {
+    "docs": {
+      "path": "../product-docs",
+      "description": "Product behavior and terminology"
+    },
+    "effect": {
+      "repository": "Effect-TS/effect",
+      "branch": "main"
+    }
+  }
+}
+```
+
+See the [references guide](https://opencode.ai/docs/references/) for shorthand,
+visibility, and path resolution.
+
+### Plugins
+
+Load plugins from packages or local files. Use the object form when a plugin
+accepts options.
+
+```jsonc
+{
+  "plugins": [
+    "opencode-example-plugin",
+    {
+      "package": "./plugins/local.ts",
+      "options": {
+        "enabled": true
+      }
+    }
+  ]
+}
+```
+
+See the [plugins guide](/plugins) for plugin development and configuration.
+
+### Providers
+
+Configure providers and add or override their models, request settings,
+headers, and model variants.
+
+```jsonc
+{
+  "providers": {
+    "openai": {
+      "models": {
+        "gpt-5.2-custom": {
+          "modelID": "gpt-5.2",
+          "name": "GPT-5.2 Custom",
+          "limit": {
+            "context": 200000,
+            "output": 32000
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+See the [providers guide](https://opencode.ai/docs/providers/) for credentials,
+custom endpoints, provider packages, and model configuration.

packages/docs/package.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@opencode-ai/docs",
+  "private": true,
+  "scripts": {
+    "dev": "bun --bun mint dev --no-open --port 3333",
+    "validate": "bun --bun mint validate",
+    "broken-links": "bun --bun mint broken-links"
+  },
+  "devDependencies": {
+    "mint": "4.2.666"
+  }
+}