Docs/json recipe support (#5492)

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

@@ -313,7 +313,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:
+See [Shareable Recipes](/docs/guides/recipes/session-recipes) to learn how to create, use, and manage recipes.
-- `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.
 
 ### 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
+- Required `title` and `description` fields must be present
-2. Optional parameters must have default values
+- At least one of `instructions` or `prompt` must be present
-3. Parameter keys must be unique
+- All template variables must have corresponding parameter definitions
-4. Recipe files must be valid YAML or JSON
+- Parameter keys must be unique (not enforced, but required for proper functionality)
-5. Required fields (version, title, description) must be present
+- 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

@@ -199,9 +199,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)
 
   :::tip
@@ -250,10 +252,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

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

@@ -8,11 +8,11 @@ import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import { PanelLeft, Bot } from 'lucide-react';
 
-This guide covers storing, organizing, and finding Goose recipes when you need to access them again later. 
+This guide covers storing, organizing, and finding goose recipes when you need to access them again later. 
 
 :::info Desktop UI vs CLI
-- **Goose Desktop** has a visual Recipe Library for browsing and managing saved recipes
+- **goose Desktop** has a visual Recipe Library for browsing and managing saved recipes
-- **Goose CLI** stores recipes as files that you find using file paths or environment variables
+- **goose CLI** stores recipes as files that you find using file paths or environment variables
 :::
 
 ## Understanding Recipe Storage
@@ -45,15 +45,15 @@ Before saving recipes, it's important to understand where they can be stored and
 **Save New Recipe:**
 
 1. To create a recipe from your chat session, see: [Create Recipe](/docs/guides/recipes/session-recipes#create-recipe)
-2. Once in the Recipe Editor, click **Save Recipe** to save it to your Recipe Library
+2. Once in the Recipe Editor, click `Save Recipe` to save it to your Recipe Library
 
 **Save Modified Recipe:**
 
 If you're already using a recipe and want to save a modified version:
 1. Click the <Bot className="inline" size={16}/> button with your current model at the bottom of the window
-2. Click **View Recipe**
+2. Click `View Recipe`
 3. Make any desired edits to the description, instructions, or initial prompts
-5. Click **Save Recipe**
+5. Click `Save Recipe`
 
 :::info
 When you modify and save a recipe with a new name, a new recipe and new link are generated. You can still run the original recipe from the recipe library, or using the original link. If you edit a recipe without changing its name, the version in the recipe library is updated, but you can still run the original recipe via link.
@@ -68,6 +68,10 @@ When you modify and save a recipe with a new name, a new recipe and new link are
     * Any path you specify: `/recipe /path/to/my-recipe.yaml`  
     * Local project recipes: `/recipe .goose/recipes/my-recipe.yaml`
 
+    :::note
+    The CLI saves recipes as `.yaml` files. While the CLI can run recipes in `.json` format, it does not provide an option to save recipes as JSON.
+    :::
+
   </TabItem>
 </Tabs>
 
@@ -75,29 +79,25 @@ When you modify and save a recipe with a new name, a new recipe and new link are
 
 <Tabs groupId="interface">
   <TabItem value="desktop" label="goose Desktop" default>
-    Import a recipe using its deeplink or YAML file:
+    Import a recipe using its deeplink or recipe file:
 
-    **Import via Recipe Link:**
     1. Click the <PanelLeft className="inline" size={16} /> button in the top-left to open the sidebar
     2. Click `Recipes` in the sidebar
-    3. Click **Import Recipe**
+    3. Click `Import Recipe`
-    4. Under **Recipe Deeplink**, paste in the [recipe link](/docs/guides/recipes/session-recipes#share-via-recipe-link)
+    4. Choose your import method:
-    5. Add a name and choose the [storage location](#recipe-storage-locations)
+       - To import via a link: Under `Recipe Deeplink`, paste in the [recipe link](/docs/guides/recipes/session-recipes#share-via-recipe-link)
-    6. Click **Import Recipe**
+       - To import via a file: Under `Recipe File`, click `Choose File`, select a recipe file, and click `Open`
+    5. Click `Import Recipe` to save a copy of the recipe to your Recipe Library
 
-    **Import via Recipe File:**
+  :::warning Recipe File Format
-    1. Click the <PanelLeft className="inline" size={16} /> button in the top-left to open the sidebar
+  goose Desktop accepts `.yaml`, `.yml`, and `.json` files, but **the CLI only supports `.yaml` and `.json`**. For full compatibility across both interfaces, avoid `.yml` extensions.
-    2. Click `Recipes` in the sidebar
-    3. Click **Import Recipe**
-    4. Under **Recipe YAML File**, click **Choose File**, select the YAML recipe file, and click `Open`
-    5. Add a name and choose the [storage location](#recipe-storage-locations)
-    6. Click **Import Recipe**
 
-    Importing JSON recipe files isn't currently supported.
+  All recipe formats follow the same [schema structure](/docs/guides/recipes/recipe-reference#recipe-structure).
+  :::
 
   </TabItem>
   <TabItem value="cli" label="goose CLI">
-    Recipe import is only available in Goose Desktop.
+    Recipe import is only available in goose Desktop.
   </TabItem>
 </Tabs>
 
@@ -138,7 +138,7 @@ goose recipe list --format json
 
 **Recipe Discovery Process**
 
-Goose searches for recipes in the following locations (in order):
+goose searches for recipes in the following locations (in order):
 
 1. **Current directory**: `.` (looks for `*.yaml` and `*.json` files)
 2. **Custom paths**: Directories specified in [`GOOSE_RECIPE_PATH`](/docs/guides/environment-variables#recipe-configuration) environment variable
@@ -162,7 +162,7 @@ job-finder - Find software engineering positions - local: ~/.config/goose/recipe
 $ goose recipe list --verbose
 Available recipes:
   goose-self-test - A comprehensive meta-testing recipe - local: ./goose-self-test.yaml
-    Title: Goose Self-Testing Integration Suite
+    Title: goose Self-Testing Integration Suite
     Path: ./goose-self-test.yaml
   hello-world - A sample recipe demonstrating basic usage - local: ~/.config/goose/recipes/hello-world.yaml
     Title: Hello World Recipe
@@ -176,7 +176,7 @@ Available recipes:
     "name": "goose-self-test",
     "source": "Local",
     "path": "./goose-self-test.yaml",
-    "title": "Goose Self-Testing Integration Suite",
+    "title": "goose Self-Testing Integration Suite",
     "description": "A comprehensive meta-testing recipe"
   },
   {
@@ -242,10 +242,10 @@ The `goose recipe list` command is the recommended way to find recipes as it aut
   </TabItem>
   <TabItem value="cli" label="goose CLI">
 
-Once you've located your recipe file, [run the recipe](/docs/guides/recipes/session-recipes#run-a-recipe) or [open it in goose desktop](/docs/guides/goose-cli-commands#recipe).
+Once you've located your recipe file, [run the recipe](/docs/guides/recipes/session-recipes#run-a-recipe) or [open it in goose Desktop](/docs/guides/goose-cli-commands#recipe).
 
 :::tip Format Compatibility
-The CLI can run recipes saved from Goose Desktop without any conversion. Both CLI-created and Desktop-saved recipes work with all recipe commands.
+The CLI can run recipes saved from goose Desktop without any conversion. Both CLI-created and Desktop-saved recipes work with all recipe commands.
 :::
 
   </TabItem>