docs: cover V2 schema during config migration

packages/core/src/plugin/skill/opencode.md

@@ -22,11 +22,10 @@ legacy OpenCode, or migrating from V1.
 Use only <https://opencode.ai/v2/docs/> documentation as the source of truth for V2.
 Do not use <https://opencode.ai/docs/>, which documents V1, and do not use
 general web search to resolve a V2 documentation question when the V2 docs or
-linked pages cover it. The schema served from
-<https://opencode.ai/config.json> may describe V1 even though V2 configuration
-files include that URL for editor integration. Never use it to infer V2 field
-names or shapes. If V2 documentation is missing or contradictory, state the
-uncertainty or ask for clarification instead of falling back to V1.
+linked pages cover it. The V1 schema at <https://opencode.ai/config.json> is
+not the native V2 schema at <https://opencode.ai/v2/config.json>. If V2
+documentation is missing or contradictory, state the uncertainty or ask for
+clarification instead of falling back to V1.
 
 V1 documentation and syntax may be consulted only when the user explicitly
 asks about V1 or when needed as migration input. Outputs and recommendations
@@ -74,7 +73,7 @@ autocomplete:
 
 ```jsonc
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
 }
 ```
 
@@ -101,8 +100,8 @@ preferences, especially themes and keybindings.
 
 Do not guess field names or shapes. Fetch the V2 configuration guide and its
 linked topic guide as the source of truth, and preserve unrelated settings when
-editing an existing file. Keep the published `$schema` URL in configuration
-examples, but do not fetch it to determine the V2 configuration shape.
+editing an existing file. Use the V2 `$schema` URL for native V2 examples;
+leave the V1 URL in existing files that still use V1 syntax.
 
 See the [full configuration guide](https://opencode.ai/v2/docs/config) for
 every field, examples, config locations, and links to dedicated feature guides.
@@ -145,7 +144,9 @@ V1 config files and `.opencode/` definitions are intended to remain compatible.
 The only intentional breaking changes are the server API and plugin API. Native
 V2 config uses more ergonomic shapes, but conversion is optional. When the user
 requests conversion, inspect the complete configuration, preserve behavior and
-unrelated settings, and apply only the relevant migrations from the guide. For
+unrelated settings, and apply only the relevant migrations from the guide. Update
+`$schema` to `https://opencode.ai/v2/config.json` when a file is fully converted;
+do not rewrite the V1 URL merely because V2 loads its legacy contents. For
 plugin migrations, fetch and follow both the migration guide and the full
 [plugins guide](https://opencode.ai/v2/docs/build/plugins). If non-API V1
 functionality fails in V2, use the `report` skill to file it as a compatibility

packages/schema/script/config-schema.ts

@@ -0,0 +1,27 @@
+import { Schema } from "effect"
+import { Config } from "../src/config.js"
+
+const target = process.argv[2]
+if (!target) throw new Error("A schema output path is required")
+
+const document = Schema.toJsonSchemaDocument(Config.Info)
+const content = `${JSON.stringify(
+  {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://opencode.ai/v2/config.json",
+    ...document.schema,
+    ...(Object.keys(document.definitions).length ? { $defs: document.definitions } : {}),
+  },
+  null,
+  2,
+)}\n`
+
+if (process.argv.includes("--check")) {
+  if ((await Bun.file(target).text()) !== content) {
+    console.error("Generated V2 config schema is stale. Run `bun run generate` from services/www.")
+    process.exit(1)
+  }
+  process.exit(0)
+}
+
+await Bun.write(target, content)

services/www/.gitignore

@@ -3,3 +3,4 @@
 dist/
 node_modules/
 public/cli.json
+public/config.json

services/www/README.md

@@ -6,6 +6,7 @@ The standard Astro website for OpenCode. The only deployment-specific path is th
 - `src/docs/` is the self-contained documentation feature rendered under `/docs`.
 - `/install` proxies the current installer.
 - `/openapi.json` serves the generated OpenAPI specification.
+- `/config.json` serves the generated V2 `opencode.json` schema.
 
 The deployment currently sets `base: "/v2"`. The `v2.opencode.ai` alias is handled by a Cloudflare Redirect Rule outside this project.
 

services/www/package.json

@@ -7,7 +7,7 @@
     "dev": "bun run generate && astro dev --host --port 3000",
     "build": "bun run generate && astro build && bun script/pagefind.ts && bun run validate && bun script/prepare-cloudflare.ts",
     "deploy": "wrangler deploy --config dist/server/wrangler.json",
-    "generate": "bun script/generate-openapi.ts && bun --cwd ../../packages/cli script/schema.ts ../../services/www/public/cli.json",
+    "generate": "bun script/generate-openapi.ts && bun --cwd ../../packages/cli script/schema.ts ../../services/www/public/cli.json && bun --cwd ../../packages/schema script/config-schema.ts ../../services/www/public/config.json",
     "check:generated": "bun script/generate-openapi.ts --check",
     "validate": "bun script/validate-links.ts",
     "typecheck": "astro check"

services/www/src/docs/content/agents.mdx

@@ -65,7 +65,7 @@ Define agents under `agents` in any [OpenCode configuration file](/config):
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "agents": {
     "reviewer": {
       "description": "Reviews current changes",
@@ -85,7 +85,7 @@ Set the primary agent used when a session has not selected one:
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "default_agent": "writer",
   "agents": {
     "writer": { "mode": "primary" },

services/www/src/docs/content/attachments.mdx

@@ -79,7 +79,7 @@ Configure image normalization in `opencode.json` or `opencode.jsonc`:
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "media": {
     "image": {
       "auto_resize": true,

services/www/src/docs/content/build/plugins/effect.mdx

@@ -31,7 +31,7 @@ plugins.
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "plugins": [
     "opencode-acme-effect-plugin",
     "opencode-acme-effect-plugin@1.2.0",

services/www/src/docs/content/build/plugins/index.mdx

@@ -23,7 +23,7 @@ or plugin directories from other locations, add them to `plugins` in `opencode.j
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "plugins": [
     "opencode-acme-plugin",
     "opencode-acme-plugin@1.2.0",

services/www/src/docs/content/commands.mdx

@@ -53,7 +53,7 @@ Define commands under `commands` in any OpenCode JSON or JSONC [configuration fi
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "commands": {
     "review": {
       "description": "Review code for correctness",

services/www/src/docs/content/compaction.mdx

@@ -26,7 +26,7 @@ Automatic compaction is on by default:
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "compaction": {
     "auto": true,
     "keep": { "tokens": 15000 },
@@ -72,7 +72,7 @@ Add `compaction` to any [OpenCode configuration file](/config):
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "compaction": {
     "auto": false,
     "keep": { "tokens": 24000 },
@@ -97,7 +97,7 @@ provider or model with `settings.compaction`:
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "providers": {
     "openai": {
       "settings": { "compaction": { "type": "native" } },

services/www/src/docs/content/config.mdx

@@ -6,7 +6,7 @@ Create `opencode.jsonc` in your project to configure OpenCode. Add the schema fo
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "model": "anthropic/claude-sonnet-4-5",
 }
 ```
@@ -19,7 +19,7 @@ OpenCode supports JSON and JSONC. Use JSONC when you want comments or trailing c
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   // Use this model by default.
   "model": "anthropic/claude-sonnet-4-5",
 }
@@ -71,14 +71,14 @@ which overrides the global config. Settings that do not conflict are preserved.
 ## Schema
 
 The complete OpenCode configuration schema is available at
-[opencode.ai/config.json](https://opencode.ai/config.json).
+[opencode.ai/v2/config.json](https://opencode.ai/v2/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"
+  "$schema": "https://opencode.ai/v2/config.json"
 }
 ```
 

services/www/src/docs/content/console/go.mdx

@@ -329,7 +329,7 @@ the [model](/models) using the format `opencode-go/<model-id>`:
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "model": "opencode-go/kimi-k3",
 }
 ```

services/www/src/docs/content/console/models.mdx

@@ -123,7 +123,7 @@ use the format `opencode/<model-id>`:
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "model": "opencode/gpt-5.5",
 }
 ```

services/www/src/docs/content/formatters.mdx

@@ -7,7 +7,7 @@ them. Formatters are disabled by default, so enable them in your configuration:
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "formatter": true,
 }
 ```
@@ -20,7 +20,7 @@ available.
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "formatter": true,
 }
 ```
@@ -30,7 +30,7 @@ formatters. An empty object is therefore equivalent to `true`.
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "formatter": {},
 }
 ```
@@ -85,7 +85,7 @@ formatter needs both `command` and `extensions` to run.
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "formatter": {
     "prettier": {
       "environment": {
@@ -182,7 +182,7 @@ Omit `formatter` or set it to `false` to disable all formatting. An explicit
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "formatter": false,
 }
 ```

services/www/src/docs/content/instructions.mdx

@@ -104,7 +104,7 @@ The V2 config schema accepts an `instructions` array, but V2 does not currently
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "instructions": ["CONTRIBUTING.md", "docs/guidelines/*.md", "https://example.com/instructions.md"],
 }
 ```

services/www/src/docs/content/mcp-servers.mdx

@@ -31,7 +31,7 @@ To configure a server by hand, give it a unique name under `mcp.servers`. V2 doe
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "mcp": {
     "servers": {
       "my-server": {
@@ -86,7 +86,7 @@ Use configuration for process options such as a working directory or environment
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "mcp": {
     "servers": {
       "everything": {
@@ -136,7 +136,7 @@ Use configuration when the server needs headers or other options. Store secrets
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "mcp": {
     "servers": {
       "context7": {
@@ -182,7 +182,7 @@ For dynamic registration, configure only the server URL:
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "mcp": {
     "servers": {
       "sentry": {
@@ -204,7 +204,7 @@ When a provider gives you client credentials, use V2's snake_case OAuth fields:
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "mcp": {
     "servers": {
       "company-tools": {
@@ -244,7 +244,7 @@ Timeouts are positive integer milliseconds. Set defaults under `mcp.timeout`; a
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "mcp": {
     "timeout": {
       "startup": 45000,
@@ -276,7 +276,7 @@ OpenCode opens every server with the classic MCP `initialize` handshake by defau
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "mcp": {
     "servers": {
       "modern": {

services/www/src/docs/content/migrate-v1.mdx

@@ -69,13 +69,25 @@ The recommended migration path is to ask OpenCode to update the configuration fo
 
 ```text
 Migrate my OpenCode configuration, including file-based definitions, from the V1 format to the native V2 format.
-Preserve its behavior and all unrelated settings.
+Preserve its behavior and all unrelated settings. When a config file is fully converted, update its $schema to
+https://opencode.ai/v2/config.json.
 ```
 
 OpenCode can inspect the complete file, apply the relevant changes below, and avoid rewriting settings that do not need to
 change. Conversion does not need to happen all at once: supported V1 and native V2 fields may coexist at the top level.
 When both forms set the same canonical value, a valid native V2 value takes precedence regardless of JSON key order.
 
+Keep `https://opencode.ai/config.json` in files that still use V1 syntax. The native V2 schema validates native V2 fields,
+not legacy fields retained for runtime compatibility; a partially converted file may not validate against either schema.
+Once a file is fully converted, use:
+
+```jsonc title="opencode.jsonc"
+{
+  "$schema": "https://opencode.ai/v2/config.json",
+  "permissions": [{ "action": "shell", "resource": "git push *", "effect": "ask" }],
+}
+```
+
 Nested mixing is intentionally bounded. OpenCode recognizes mixed V1 and V2 members within `mcp`, `compaction`, and
 `experimental`, but it does not recursively infer formats inside individual agents, providers, commands, or models. Keep
 each of those nested entries entirely in one format. Supported V1 syntax remains quiet by itself; malformed values,

services/www/src/docs/content/models.mdx

@@ -43,7 +43,7 @@ Set `model` in `opencode.json` or `opencode.jsonc` to choose the default for new
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "model": "anthropic/claude-sonnet-4-5",
 }
 ```
@@ -73,7 +73,7 @@ Define new variants, or replace catalog variants with the same ID, in the model'
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "providers": {
     "openai": {
       "models": {
@@ -153,7 +153,7 @@ Use `modelID` to give an API model a friendlier catalog ID:
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "model": "openai/coding-default",
   "providers": {
     "openai": {
@@ -243,7 +243,7 @@ With Ollama listening at `http://127.0.0.1:11434`, select a discovered model wit
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "model": "ollama/gemma3:4b",
 }
 ```
@@ -277,7 +277,7 @@ provider ID:
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "model": "lmstudio/google/gemma-4-26b-a4b",
 }
 ```
@@ -309,7 +309,7 @@ With vLLM listening at `http://127.0.0.1:8000`, select a discovered model with t
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "model": "vllm/Qwen/Qwen3-Coder-30B-A3B-Instruct",
 }
 ```
@@ -346,7 +346,7 @@ For another OpenAI-compatible server, define its provider package, endpoint, and
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "model": "local/coder",
   "providers": {
     "local": {

services/www/src/docs/content/permissions.mdx

@@ -11,7 +11,7 @@ inspection, and always block pushes. Add these ordered rules to `opencode.jsonc`
 
 ```jsonc
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "permissions": [
     { "action": "shell", "resource": "*", "effect": "ask" },
     { "action": "shell", "resource": "git status *", "effect": "allow" },
@@ -142,7 +142,7 @@ A path outside both the active Location and its non-root project worktree needs
 
 ```jsonc
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "permissions": [
     { "action": "external_directory", "resource": "~/projects/reference/*", "effect": "allow" },
     { "action": "read", "resource": "~/projects/reference/*", "effect": "allow" },
@@ -179,7 +179,7 @@ Enable the experimental portable shell scanner with:
 
 ```jsonc
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "experimental": {
     "portable_shell_scanner": true,
   },
@@ -232,7 +232,7 @@ Put shared rules at the top level and narrower rules under
 
 ```jsonc
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "permissions": [
     { "action": "shell", "resource": "*", "effect": "ask" },
     { "action": "shell", "resource": "git status *", "effect": "allow" },

services/www/src/docs/content/plugins.mdx

@@ -8,7 +8,7 @@ Add published packages, versioned packages, scoped packages, or local plugin dir
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "plugins": [
     "opencode-acme-plugin",
     "opencode-acme-plugin@1.2.0",

services/www/src/docs/content/policies.mdx

@@ -17,7 +17,7 @@ Deny one provider everywhere by adding a statement to `opencode.jsonc`:
 
 ```jsonc
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "experimental": {
     "policies": [{ "action": "provider.use", "resource": "openai", "effect": "deny" }],
   },

services/www/src/docs/content/providers.mdx

@@ -34,7 +34,7 @@ runtime package, endpoint, and first model together.
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "providers": {
     "acme": {
       "name": "Acme",
@@ -73,7 +73,7 @@ models, and connection still apply.
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "providers": {
     "anthropic": {
       "settings": {
@@ -92,7 +92,7 @@ Use `headers` for additional HTTP headers and `body` for JSON fields that should
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "providers": {
     "openai": {
       "headers": {
@@ -112,7 +112,7 @@ Both fields can also be set on a model or variant when only part of a provider's
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "providers": {
     "openai": {
       "models": {
@@ -138,7 +138,7 @@ implement the OpenAI request format.
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "providers": {
     "acme": {
       "package": "@opencode/ai/providers/openai-compatible",
@@ -182,7 +182,7 @@ You can also use an npm package such as `@acme/opencode-provider` or an absolute
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "providers": {
     "acme": {
       "package": "@acme/opencode-provider",
@@ -199,7 +199,7 @@ ID sent to the provider.
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "model": "openai/coding",
   "providers": {
     "openai": {
@@ -240,7 +240,7 @@ once, then connect an API key or use the Microsoft Entra ID session from the Azu
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "providers": {
     "azure": {
       "settings": {
@@ -283,7 +283,7 @@ model name, map an OpenCode model ID to the deployment with `modelID`.
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "providers": {
     "azure": {
       "models": {
@@ -322,7 +322,7 @@ identity token file, or container credential URI activates the provider; a regio
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "providers": {
     "amazon-bedrock": {
       "settings": {
@@ -339,7 +339,7 @@ VPC endpoint, set `baseURL` while keeping the same profile and region.
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "providers": {
     "amazon-bedrock": {
       "settings": {
@@ -366,7 +366,7 @@ gcloud auth application-default login
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "providers": {
     "google-vertex": {
       "settings": {
@@ -436,7 +436,7 @@ model requests.
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "providers": {
     "ollama": {
       "settings": {
@@ -458,7 +458,7 @@ LM Studio and vLLM also have built-in local discovery. Their default endpoints a
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "providers": {
     "lmstudio": {
       "settings": { "baseURL": "http://gpu-host:1234/v1" },
@@ -481,7 +481,7 @@ OpenRouter account, then refer to models with the full OpenRouter model ID after
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "model": "openrouter/anthropic/claude-sonnet-4",
 }
 ```
@@ -491,7 +491,7 @@ This preserves OpenRouter request and reasoning behavior.
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "providers": {
     "openrouter": {
       "settings": {
@@ -510,7 +510,7 @@ The configuration key becomes the provider prefix and each `models` key becomes
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "model": "company/coder",
   "providers": {
     "company": {
@@ -554,7 +554,7 @@ sessions.
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "providers": {
     "openai": {
       "settings": { "transport": "http" },

services/www/src/docs/content/references.mdx

@@ -8,7 +8,7 @@ your client when you need it.
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "references": {
     "docs": {
       "path": "../product-docs",

services/www/src/docs/content/skills.mdx

@@ -67,7 +67,7 @@ Add more local directories or HTTP catalogs with the `skills` array in any `open
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "skills": [
     "./team-skills",
     "~/shared/opencode-skills",

services/www/src/docs/content/snapshots.mdx

@@ -103,7 +103,7 @@ filesystem capture.
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "snapshots": false,
 }
 ```

services/www/src/docs/content/warming.mdx

@@ -10,7 +10,7 @@ Enable warming in any [OpenCode configuration file](/config):
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "warming": true,
 }
 ```
@@ -26,7 +26,7 @@ window:
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "warming": {
     "prompt": "Do not perform any work. Reply with exactly: OK",
     "interval": "5 minutes",

services/www/src/docs/content/websearch.mdx

@@ -33,7 +33,7 @@ Set a provider in `opencode.jsonc` to skip the selection prompt.
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "websearch": {
     "provider": "tavily",
   },
@@ -44,7 +44,7 @@ Use `"random"` to choose an available provider automatically. Each session keeps
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "websearch": {
     "provider": "random",
   },
@@ -69,7 +69,7 @@ Web searches use the `websearch` permission action and the search query as the r
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "permissions": [
     {
       "action": "websearch",
@@ -88,7 +88,7 @@ Set `websearch` to `false` to remove the web search tool from model requests.
 
 ```jsonc title="opencode.jsonc"
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/v2/config.json",
   "websearch": false,
 }
 ```