add schema descriptions to config fields

Enhance configuration schema with descriptive text for all fields to improve developer experience and auto-generated documentation.

🤖 Generated with [opencode](https://opencode.ai)

Co-Authored-By: opencode <[email protected]>

2 files changed, 112 insertions, 74 deletions

diff --git a/packages/opencode/config.schema.json b/packages/opencode/config.schema.json
index a57a4824e..99845c53d 100644
--- a/packages/opencode/config.schema.json
+++ b/packages/opencode/config.schema.json
@@ -2,97 +2,127 @@
   "type": "object",
   "properties": {
     "$schema": {
-      "type": "string"
+      "type": "string",
+      "description": "JSON schema reference for configuration validation"
     },
     "theme": {
-      "type": "string"
+      "type": "string",
+      "description": "Theme name to use for the interface"
     },
     "keybinds": {
       "type": "object",
       "properties": {
         "leader": {
-          "type": "string"
+          "type": "string",
+          "description": "Leader key for keybind combinations"
         },
         "help": {
-          "type": "string"
+          "type": "string",
+          "description": "Show help dialog"
         },
         "editor_open": {
-          "type": "string"
+          "type": "string",
+          "description": "Open external editor"
         },
         "session_new": {
-          "type": "string"
+          "type": "string",
+          "description": "Create a new session"
         },
         "session_list": {
-          "type": "string"
+          "type": "string",
+          "description": "List all sessions"
         },
         "session_share": {
-          "type": "string"
+          "type": "string",
+          "description": "Share current session"
         },
         "session_interrupt": {
-          "type": "string"
+          "type": "string",
+          "description": "Interrupt current session"
         },
         "session_compact": {
-          "type": "string"
+          "type": "string",
+          "description": "Toggle compact mode for session"
         },
         "tool_details": {
-          "type": "string"
+          "type": "string",
+          "description": "Show tool details"
         },
         "model_list": {
-          "type": "string"
+          "type": "string",
+          "description": "List available models"
         },
         "theme_list": {
-          "type": "string"
+          "type": "string",
+          "description": "List available themes"
         },
         "project_init": {
-          "type": "string"
+          "type": "string",
+          "description": "Initialize project configuration"
         },
         "input_clear": {
-          "type": "string"
+          "type": "string",
+          "description": "Clear input field"
         },
         "input_paste": {
-          "type": "string"
+          "type": "string",
+          "description": "Paste from clipboard"
         },
         "input_submit": {
-          "type": "string"
+          "type": "string",
+          "description": "Submit input"
         },
         "input_newline": {
-          "type": "string"
+          "type": "string",
+          "description": "Insert newline in input"
         },
         "history_previous": {
-          "type": "string"
+          "type": "string",
+          "description": "Navigate to previous history item"
         },
         "history_next": {
-          "type": "string"
+          "type": "string",
+          "description": "Navigate to next history item"
         },
         "messages_page_up": {
-          "type": "string"
+          "type": "string",
+          "description": "Scroll messages up by one page"
         },
         "messages_page_down": {
-          "type": "string"
+          "type": "string",
+          "description": "Scroll messages down by one page"
         },
         "messages_half_page_up": {
-          "type": "string"
+          "type": "string",
+          "description": "Scroll messages up by half page"
         },
         "messages_half_page_down": {
-          "type": "string"
+          "type": "string",
+          "description": "Scroll messages down by half page"
         },
         "messages_previous": {
-          "type": "string"
+          "type": "string",
+          "description": "Navigate to previous message"
         },
         "messages_next": {
-          "type": "string"
+          "type": "string",
+          "description": "Navigate to next message"
         },
         "messages_first": {
-          "type": "string"
+          "type": "string",
+          "description": "Navigate to first message"
         },
         "messages_last": {
-          "type": "string"
+          "type": "string",
+          "description": "Navigate to last message"
         },
         "app_exit": {
-          "type": "string"
+          "type": "string",
+          "description": "Exit the application"
         }
       },
-      "additionalProperties": false
+      "additionalProperties": false,
+      "description": "Custom keybind configurations"
     },
     "autoshare": {
       "type": "boolean",
@@ -207,7 +237,8 @@
           "models"
         ],
         "additionalProperties": false
-      }
+      },
+      "description": "Custom provider configurations and model overrides"
     },
     "mcp": {
       "type": "object",
@@ -218,19 +249,22 @@
             "properties": {
               "type": {
                 "type": "string",
-                "const": "local"
+                "const": "local",
+                "description": "Type of MCP server connection"
               },
               "command": {
                 "type": "array",
                 "items": {
                   "type": "string"
-                }
+                },
+                "description": "Command and arguments to run the MCP server"
               },
               "environment": {
                 "type": "object",
                 "additionalProperties": {
                   "type": "string"
-                }
+                },
+                "description": "Environment variables to set when running the MCP server"
               }
             },
             "required": [
@@ -244,10 +278,12 @@
             "properties": {
               "type": {
                 "type": "string",
-                "const": "remote"
+                "const": "remote",
+                "description": "Type of MCP server connection"
               },
               "url": {
-                "type": "string"
+                "type": "string",
+                "description": "URL of the remote MCP server"
               }
             },
             "required": [
@@ -257,7 +293,8 @@
             "additionalProperties": false
           }
         ]
-      }
+      },
+      "description": "MCP (Model Context Protocol) server configurations"
     }
   },
   "additionalProperties": false,
diff --git a/packages/opencode/src/config/config.ts b/packages/opencode/src/config/config.ts
index 5d98d5794..4fc6c0213 100644
--- a/packages/opencode/src/config/config.ts
+++ b/packages/opencode/src/config/config.ts
@@ -44,9 +44,9 @@ export namespace Config {
 
   export const McpLocal = z
     .object({
-      type: z.literal("local"),
-      command: z.string().array(),
-      environment: z.record(z.string(), z.string()).optional(),
+      type: z.literal("local").describe("Type of MCP server connection"),
+      command: z.string().array().describe("Command and arguments to run the MCP server"),
+      environment: z.record(z.string(), z.string()).optional().describe("Environment variables to set when running the MCP server"),
     })
     .openapi({
       ref: "Config.McpLocal",
@@ -54,8 +54,8 @@ export namespace Config {
 
   export const McpRemote = z
     .object({
-      type: z.literal("remote"),
-      url: z.string(),
+      type: z.literal("remote").describe("Type of MCP server connection"),
+      url: z.string().describe("URL of the remote MCP server"),
     })
     .openapi({
       ref: "Config.McpRemote",
@@ -66,42 +66,42 @@ export namespace Config {
 
   export const Keybinds = z
     .object({
-      leader: z.string().optional(),
-      help: z.string().optional(),
-      editor_open: z.string().optional(),
-      session_new: z.string().optional(),
-      session_list: z.string().optional(),
-      session_share: z.string().optional(),
-      session_interrupt: z.string().optional(),
-      session_compact: z.string().optional(),
-      tool_details: z.string().optional(),
-      model_list: z.string().optional(),
-      theme_list: z.string().optional(),
-      project_init: z.string().optional(),
-      input_clear: z.string().optional(),
-      input_paste: z.string().optional(),
-      input_submit: z.string().optional(),
-      input_newline: z.string().optional(),
-      history_previous: z.string().optional(),
-      history_next: z.string().optional(),
-      messages_page_up: z.string().optional(),
-      messages_page_down: z.string().optional(),
-      messages_half_page_up: z.string().optional(),
-      messages_half_page_down: z.string().optional(),
-      messages_previous: z.string().optional(),
-      messages_next: z.string().optional(),
-      messages_first: z.string().optional(),
-      messages_last: z.string().optional(),
-      app_exit: z.string().optional(),
+      leader: z.string().optional().describe("Leader key for keybind combinations"),
+      help: z.string().optional().describe("Show help dialog"),
+      editor_open: z.string().optional().describe("Open external editor"),
+      session_new: z.string().optional().describe("Create a new session"),
+      session_list: z.string().optional().describe("List all sessions"),
+      session_share: z.string().optional().describe("Share current session"),
+      session_interrupt: z.string().optional().describe("Interrupt current session"),
+      session_compact: z.string().optional().describe("Toggle compact mode for session"),
+      tool_details: z.string().optional().describe("Show tool details"),
+      model_list: z.string().optional().describe("List available models"),
+      theme_list: z.string().optional().describe("List available themes"),
+      project_init: z.string().optional().describe("Initialize project configuration"),
+      input_clear: z.string().optional().describe("Clear input field"),
+      input_paste: z.string().optional().describe("Paste from clipboard"),
+      input_submit: z.string().optional().describe("Submit input"),
+      input_newline: z.string().optional().describe("Insert newline in input"),
+      history_previous: z.string().optional().describe("Navigate to previous history item"),
+      history_next: z.string().optional().describe("Navigate to next history item"),
+      messages_page_up: z.string().optional().describe("Scroll messages up by one page"),
+      messages_page_down: z.string().optional().describe("Scroll messages down by one page"),
+      messages_half_page_up: z.string().optional().describe("Scroll messages up by half page"),
+      messages_half_page_down: z.string().optional().describe("Scroll messages down by half page"),
+      messages_previous: z.string().optional().describe("Navigate to previous message"),
+      messages_next: z.string().optional().describe("Navigate to next message"),
+      messages_first: z.string().optional().describe("Navigate to first message"),
+      messages_last: z.string().optional().describe("Navigate to last message"),
+      app_exit: z.string().optional().describe("Exit the application"),
     })
     .openapi({
       ref: "Config.Keybinds",
     })
   export const Info = z
     .object({
-      $schema: z.string().optional(),
-      theme: z.string().optional(),
-      keybinds: Keybinds.optional(),
+      $schema: z.string().optional().describe("JSON schema reference for configuration validation"),
+      theme: z.string().optional().describe("Theme name to use for the interface"),
+      keybinds: Keybinds.optional().describe("Custom keybind configurations"),
       autoshare: z
         .boolean()
         .optional()
@@ -127,8 +127,9 @@ export namespace Config {
             options: z.record(z.any()).optional(),
           }),
         )
-        .optional(),
-      mcp: z.record(z.string(), Mcp).optional(),
+        .optional()
+        .describe("Custom provider configurations and model overrides"),
+      mcp: z.record(z.string(), Mcp).optional().describe("MCP (Model Context Protocol) server configurations"),
     })
     .openapi({
       ref: "Config.Info",