Docs/json recipe support

documentation/docs/guides/codebase-analysis.md

@@ -41,7 +41,7 @@ This shows that `authenticate` is a central function in your authentication flow
 
 ## Analysis Modes
 
-The `analyze` tool operates in three modes—Structure, Semantic, and Focus—depending on whether you’re analyzing directories, files, or symbols. Invoke it through natural language or direct commands with [parameters](#parameters).
+The `analyze` tool operates in three modes—Structure, Semantic, and Focus—depending on whether you’re analyzing directories, files, or symbols. Invoke it through natural language or direct commands with [parameters](#common-parameters).
 
 ### Understanding Project Organization
 

documentation/docs/guides/environment-variables.md

@@ -309,7 +309,7 @@ OTLP is the standard protocol for sending telemetry collected by [OpenTelemetry]
 | `OTEL_EXPORTER_OTLP_TIMEOUT` | Export timeout in milliseconds | Integer (ms) | `10000` |
 
 **When to use OTLP:**
-- Diagnosing slow tool execution or LLM response times when goose 
+- Diagnosing slow tool execution or LLM response times
 - Understanding intermittent failures across multiple sessions
 - Monitoring goose performance in production or CI/CD environments
 - Tracking usage patterns, costs, and resource consumption over time

documentation/docs/guides/recipes/recipe-reference.md

@@ -1,9 +1,12 @@
 ---
 sidebar_position: 2
 title: Recipe Reference Guide
-description: Complete technical reference for creating and customizing recipes in goose via the CLI.
+description: Complete technical reference for creating and customizing recipes in goose
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 Recipes are reusable goose configurations that package up a specific setup so it can be easily shared and launched by others.
 
 ## Recipe File Format
@@ -12,11 +15,7 @@ Recipes can be defined in either:
 - `.yaml` files (recommended)
 - `.json` files 
 
-Files should be named either:
-- `recipe.yaml`/`recipe.json` 
-- `<recipe_name>.yaml`/`<recipe_name>.json`
-
-After creating recipe files, you can use the [`goose recipe` subcommands](/docs/guides/goose-cli-commands#recipe) to validate, share, and open your recipes.
+See [Shareable Recipes](/docs/guides/recipes/session-recipes) to learn how to create, use, and manage recipes.
 
 ### CLI and Desktop Formats
 
@@ -25,12 +24,18 @@ goose recipes use two formats:
 - **CLI Format**: Recipe fields (like `title`, `description`, `instructions`) are at the root level of the YAML/JSON file. This format is used when recipes are created via the CLI `/recipe` command and [Recipe Generator](/recipe-generator) YAML option.
 - **Desktop Format**: Recipe fields are nested inside a `recipe` object, with additional metadata fields at the root level. This format is used when recipes are created from goose Desktop.
 
-The CLI automatically detects and handles both formats when running `goose run --recipe <file>` and `goose recipe` commands. The Desktop can [import](/docs/guides/recipes/storing-recipes#importing-recipes) and use YAML recipes (or deeplinks) in either CLI or Desktop format.
+The CLI automatically detects and handles both formats for `.yaml` and `.json` recipe files when running `goose run --recipe <file>` and `goose recipe` commands. The Desktop can [import](/docs/guides/recipes/storing-recipes#importing-recipes) `.yaml`, `.yml`, and `.json` recipe files (or deeplinks) in either CLI or Desktop format.
 
 <details>
 <summary>Format Examples</summary>
 
-**CLI Format:**
+Recipes can be written in either YAML or JSON format. Both formats follow the same schema structure.
+
+### CLI Format
+
+<Tabs>
+  <TabItem value="yaml" label="YAML" default>
+
 ```yaml
 version: "1.0.0"
 title: "Code Review Assistant"
@@ -40,7 +45,28 @@ prompt: "Review the code in this repository"
 extensions: []
 ```
 
-**Desktop Format:**
+  </TabItem>
+  <TabItem value="json" label="JSON">
+
+```json
+{
+  "version": "1.0.0",
+  "title": "Code Review Assistant",
+  "description": "Automated code review with best practices",
+  "instructions": "You are a code reviewer...",
+  "prompt": "Review the code in this repository",
+  "extensions": []
+}
+```
+
+  </TabItem>
+</Tabs>
+
+### Desktop Format
+
+<Tabs>
+  <TabItem value="yaml" label="YAML" default>
+
 ```yaml
 name: "Code Review Assistant"
 recipe:
@@ -55,6 +81,29 @@ lastModified: 2025-07-02T03:46:46.778Z
 isArchived: false
 ```
 
+  </TabItem>
+  <TabItem value="json" label="JSON">
+
+```json
+{
+  "name": "Code Review Assistant",
+  "recipe": {
+    "version": "1.0.0",
+    "title": "Code Review Assistant",
+    "description": "Automated code review with best practices",
+    "instructions": "You are a code reviewer...",
+    "prompt": "Review the code in this repository",
+    "extensions": []
+  },
+  "isGlobal": true,
+  "lastModified": "2025-07-02T03:46:46.778Z",
+  "isArchived": false
+}
+```
+
+  </TabItem>
+</Tabs>
+
 :::note
 goose automatically adds metadata fields to recipes saved from the Desktop app.
 :::
@@ -238,6 +287,9 @@ The `extensions` field allows you to specify which Model Context Protocol (MCP)
 
 ### Example Extension Configuration
 
+<Tabs>
+  <TabItem value="yaml" label="YAML" default>
+
 ```yaml
 extensions:
   - type: stdio
@@ -268,6 +320,45 @@ extensions:
     description: "GitHub MCP extension for repository operations"
 ```
 
+  </TabItem>
+  <TabItem value="json" label="JSON">
+
+```json
+{
+  "extensions": [
+    {
+      "type": "stdio",
+      "name": "codesearch",
+      "cmd": "uvx",
+      "args": ["mcp_codesearch@latest"],
+      "timeout": 300,
+      "bundled": true,
+      "description": "Query https://codesearch.sqprod.co/ directly from goose"
+    },
+    {
+      "type": "stdio",
+      "name": "presidio",
+      "timeout": 300,
+      "cmd": "uvx",
+      "args": ["mcp_presidio@latest"],
+      "available_tools": ["query_logs"]
+    },
+    {
+      "type": "stdio",
+      "name": "github-mcp",
+      "cmd": "github-mcp-server",
+      "args": [],
+      "env_keys": ["GITHUB_PERSONAL_ACCESS_TOKEN"],
+      "timeout": 60,
+      "description": "GitHub MCP extension for repository operations"
+    }
+  ]
+}
+```
+
+  </TabItem>
+</Tabs>
+
 ### Extension Secrets
 
 This feature is only available through the CLI.
@@ -516,12 +607,15 @@ sub_recipes:
 
 ## Complete Recipe Example
 
+<Tabs>
+  <TabItem value="yaml" label="YAML" default>
+
 ```yaml
 version: "1.0.0"
 title: "Example Recipe"
 description: "A sample recipe demonstrating the format"
 instructions: "Follow these steps with {{ required_param }} and {{ optional_param }}"
-prompt: "Your task is to use {{ required_param }}"
+prompt: "Your task is to use {{ required_param }} with {{ interactive_param }}"
 parameters:
   - key: required_param
     input_type: string
@@ -576,9 +670,92 @@ response:
         description: "Additional details of steps taken"
     required:
       - result
-      - status
+      - details
 ```
 
+  </TabItem>
+  <TabItem value="json" label="JSON">
+
+```json
+{
+  "version": "1.0.0",
+  "title": "Example Recipe",
+  "description": "A sample recipe demonstrating the format",
+  "instructions": "Follow these steps with {{ required_param }} and {{ optional_param }}",
+  "prompt": "Your task is to use {{ required_param }} with {{ interactive_param }}",
+  "parameters": [
+    {
+      "key": "required_param",
+      "input_type": "string",
+      "requirement": "required",
+      "description": "A required parameter example"
+    },
+    {
+      "key": "optional_param",
+      "input_type": "string",
+      "requirement": "optional",
+      "default": "default value",
+      "description": "An optional parameter example"
+    },
+    {
+      "key": "interactive_param",
+      "input_type": "string",
+      "requirement": "user_prompt",
+      "description": "Will prompt user if not provided"
+    }
+  ],
+  "extensions": [
+    {
+      "type": "stdio",
+      "name": "codesearch",
+      "cmd": "uvx",
+      "args": ["mcp_codesearch@latest"],
+      "timeout": 300,
+      "bundled": true,
+      "description": "Query codesearch directly from goose"
+    }
+  ],
+  "settings": {
+    "goose_provider": "anthropic",
+    "goose_model": "claude-sonnet-4-20250514",
+    "temperature": 0.7
+  },
+  "retry": {
+    "max_retries": 3,
+    "timeout_seconds": 30,
+    "checks": [
+      {
+        "type": "shell",
+        "command": "echo 'Task validation check passed'"
+      }
+    ],
+    "on_failure": "echo 'Retry attempt failed, cleaning up...'"
+  },
+  "response": {
+    "json_schema": {
+      "type": "object",
+      "properties": {
+        "result": {
+          "type": "string",
+          "description": "The main result of the task"
+        },
+        "details": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Additional details of steps taken"
+        }
+      },
+      "required": ["result", "details"]
+    }
+  }
+}
+```
+
+  </TabItem>
+</Tabs>
+
 ## Template Inheritance
 
 Parent recipe (`parent.yaml`):
@@ -614,13 +791,16 @@ Recipes can be loaded from:
 
 ## Validation Rules
 
-The following rules are enforced when loading recipes:
+Recipe files must be valid YAML or JSON. In addition, the following [validation rules](https://github.com/block/goose/blob/main/crates/goose/src/recipe/validate_recipe.rs) are enforced when loading recipes and are also checked by the [`goose recipe validate` subcommand](/docs/guides/goose-cli-commands#recipe):
 
-1. All template variables must have corresponding parameter definitions
-2. Optional parameters must have default values
-3. Parameter keys must be unique
-4. Recipe files must be valid YAML or JSON
-5. Required fields (version, title, description) must be present
+- Required `title` and `description` fields must be present
+- At least one of `instructions` or `prompt` must be present
+- All template variables must have corresponding parameter definitions
+- Parameter keys must be unique (not enforced, but required for proper functionality)
+- All defined parameters must be used in template variables (no unused parameters)
+- Optional parameters must have default values
+- File parameters cannot have default values (prevents importing sensitive files)
+- `response.json_schema` must be a valid JSON schema if specified
 
 ## Error Handling
 

documentation/docs/guides/recipes/session-recipes.md

@@ -198,9 +198,11 @@ You can turn your current goose session into a reusable recipe that includes the
       - Instructions
       - Initial prompt
       - Activities
+      - Parameters
+      - Response schema
   4. When you're finished, you can:
       - Copy the recipe link to share the recipe with others
-      - Click `Save Recipe` to [save the recipe](/docs/guides/recipes/storing-recipes) locally
+      - Click `Save Recipe` to save your changes
       - Click `Create Schedule` to [schedule the recipe](#schedule-recipe)
 
   </TabItem>
@@ -245,10 +247,6 @@ You can turn your current goose session into a reusable recipe that includes the
 
   4. To run the recipe, click an activity bubble or send the prompt.
 
-  :::info Parameter Creation In Goose CLI Only
-  You can enter parameter values to use in a recipe, but you cannot add parameters to a recipe in Goose Desktop. Parameters can only be defined in recipes created via the CLI.
-  :::
-
   :::info Privacy & Isolation
   - Each person gets their own private session
   - No data is shared between users