docs: desktop recipe format (#3594)

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

@@ -18,6 +18,49 @@ Files should be named either:
 
 After creating recipe files, you can use [`goose` CLI commands](/docs/guides/goose-cli-commands) to run or validate the files and to manage recipe sharing.
 
+### CLI and Desktop Formats
+
+The Goose CLI supports CLI and Desktop recipe formats:
+
+- **CLI Format**: Recipe fields (like `title`, `description`, `instructions`) are at the root level of the YAML/JSON file
+- **Desktop Format**: Recipe fields are nested inside a `recipe` object, with additional metadata fields at the root level
+
+The CLI automatically detects and handles both formats when running `goose run --recipe <file>` and `goose recipe` commands.
+
+<details>
+<summary>Format Examples</summary>
+
+**CLI Format:**
+```yaml
+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: []
+```
+
+**Desktop Format:**
+```yaml
+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
+```
+
+:::note
+Goose automatically adds metadata fields to recipes saved from the Desktop app.
+:::
+
+</details>
+
 ## Recipe Structure
 
 ### Required Fields
@@ -40,6 +83,17 @@ After creating recipe files, you can use [`goose` CLI commands](/docs/guides/goo
 | `response` | Object | Configuration for structured output validation |
 | `retry` | Object | Configuration for automated retry logic with success validation |
 
+### Desktop Format Metadata Fields
+
+When recipes are saved from Goose Desktop, additional metadata fields are included at the top level (outside the `recipe` key). These fields are used by the Desktop app for organization and management but are ignored by CLI operations.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | String | Display name used in Desktop Recipe Library |
+| `isGlobal` | Boolean | Whether the recipe is available globally or locally to a project |
+| `lastModified` | String | ISO timestamp of when the recipe was last modified |
+| `isArchived` | Boolean | Whether the recipe is archived in the Desktop interface |
+
 ## Parameters
 
 Each parameter in the `parameters` array has the following structure:

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

@@ -588,5 +588,14 @@ To protect your privacy and system integrity, Goose excludes:
 
 This means others may need to supply their own credentials or memory context if the recipe depends on those elements.
 
+## CLI and Desktop Formats
+
+The Goose CLI supports both CLI and Desktop recipe formats:
+
+- **CLI Format**: Recipe fields are at the root level. This format is used when recipes are created via the CLI `/recipe` command and Recipe Generator YAML option.
+- **Desktop Format**: Recipe fields are nested under a `recipe` key. This format is used when recipes are saved in Goose Desktop.
+
+Both formats work seamlessly with `goose run --recipe <file>` and `goose recipe` CLI commands - you don't need to convert between them. For more details, see [CLI and Desktop Formats](/docs/guides/recipes/recipe-reference#cli-and-desktop-formats).
+
 ## Learn More
 Check out the [Goose Recipes](/docs/guides/recipes) guide for more docs, tools, and resources to help you master Goose recipes.

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

@@ -124,5 +124,9 @@ Set up [custom recipe paths](/docs/guides/recipes/session-recipes#configure-reci
 
 Once you've located your recipe file, [run the recipe](/docs/guides/recipes/session-recipes#run-a-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.
+:::
+
   </TabItem>
 </Tabs>