doc: updated the goose doc with recent new features of goose recipe (#2612)

Co-authored-by: Rizel Scarlett <rizel@tbd.email>
Co-authored-by: dianed-square <73617011+dianed-square@users.noreply.github.com>
Co-authored-by: Angie Jones <jones.angie@gmail.com>

documentation/docs/guides/session-recipes.md

@@ -91,45 +91,48 @@ You'll need to provide both instructions and activities for your Recipe.
    To add parameters, edit your recipe file to include template variables using `{{ variable_name }}` syntax and define each of them in your yaml using `parameters`.
 
    <details>
-      <summary>Example recipe with parameters</summary>
+   <summary>Example recipe with parameters</summary>
       
-      ```yaml title="code-review.yaml"
-      version: 1.0.0
-      title: {{ project_name }} Code Review
-      description: Automated code review for {{ project_name }} with {{ language }} focus
-      parameters:
-         - key: project_name
-           input_type: string
-           description: Name of the project
-           requirement: required
-         - key: language
-           input_type: string
-           description: Language of the code change
-           requirement: required
-         - key: complexity_threshold
-           input_type: number
-           description: The complexity threshold
-           requirement: optional
-         - key: test_coverage
-           input_type: number
-           description: Percentage Test coverage 
-           requirement: optional
-         - key: style_guide
-           input_type: string
-           description: Style guide to use
-           requirement: user_prompt
-      instructions: |
+   ```yaml title="code-review.yaml"
+   version: 1.0.0
+   title: "{{ project_name }} Code Review" # Wrap the value in quotes if it starts with template syntax to avoid YAML parsing errors
+   description: Automated code review for {{ project_name }} with {{ language }} focus
+   instructions: |
       You are a code reviewer specialized in {{ language }} development.
-         Apply the following standards:
-         - Complexity threshold: {{ complexity_threshold }}
-         - Required test coverage: {{ test_coverage }}%
-         - Style guide: {{ style_guide }}
-      activities:
-         - "Review {{ language }} code for complexity"
-         - "Check test coverage against {{ test_coverage }}% requirement"
-         - "Verify {{ style_guide }} compliance"
-      ```
-  
+      Apply the following standards:
+      - Complexity threshold: {{ complexity_threshold }}
+      - Required test coverage: {{ test_coverage }}%
+      - Style guide: {{ style_guide }}
+   activities:
+   - "Review {{ language }} code for complexity"
+   - "Check test coverage against {{ test_coverage }}% requirement"
+   - "Verify {{ style_guide }} compliance"
+   parameters:
+   - key: project_name
+     input_type: string
+     requirement: required # could be required, optional or user_prompt
+     description: name of the project
+   - key: language
+     input_type: string
+     requirement: required
+     description: language of the code
+   - key: complexity_threshold
+     input_type: number
+     requirement: optional
+     default: 20 # default is required for optional parameters
+     description: a threshold that defines the maximum allowed complexity
+   - key: test_coverage
+     input_type: number
+     requirement: optional
+     default: 80
+     description: the minimum test coverage threshold in percentage
+   - key: style_guide
+     input_type: string
+     description: style guide name
+     requirement: user_prompt
+     # If style_guide param value is not specified in the command, user will be prompted to provide a value, even in non-interactive mode
+   ```
+
    </details>
 
    When someone runs a recipe that contains template parameters, they will need to provide the parameters:
@@ -201,10 +204,37 @@ You'll need to provide both instructions and activities for your Recipe.
    goose run --recipe recipe.yaml --interactive --params language=Spanish --params style=formal --params name=Alice
    ```
 
-   :::info
-   Be sure to use the exact filename of the recipe.
-   :::
+   - Explain the recipe with description and parameters
 
+   ```sh
+   goose run --recipe recipe.yaml --explain
+   ```
+
+   #### Discover recipes
+   When using recipe-related CLI commands, there are a few ways to specify which recipe to use:
+   ##### Options 1: Provide the full file path
+   Use the exact path to the recipe file:
+      
+   ```sh
+   goose run --recipe ~/my_recipe.yaml
+   goose recipe validate ~/my_recipe.yaml
+   goose recipe deeplink ~/my_recipe.yaml
+   ```
+   ##### Option 2: Use the recipe name
+   If your recipe is named my_recipe, you can simply use the name:
+
+   ```sh
+   goose run --recipe my_recipe
+   goose recipe validate my_recipe
+   goose recipe deeplink my_recipe
+   ```
+   When you use the recipe name, Goose will search for the file in the following order:
+   1. Local search:
+      Goose will search for `my_recipe.yaml` or `my_recipe.json` in the current working directory
+      
+   2. Remote search (GitHub):
+      - If the `GOOSE_RECIPE_GITHUB_REPO` environment variable is set or configured in the `Goose Settings` via `goose configure`, Goose will search the specified GitHub repo. (eg: my_org/goose-recipes).
+      - Goose will look for `my_recipe/recipe.yaml` or `my_recipe/recipe.json` within that GitHub repository.
    </TabItem> 
 </Tabs>