docs: custom context file names (#4077)

documentation/docs/guides/environment-variables.md

@@ -107,6 +107,7 @@ These variables control how Goose manages conversation sessions and context.
 |----------|---------|---------|---------|
 | `GOOSE_CONTEXT_STRATEGY` | Controls how Goose handles context limit exceeded situations | "summarize", "truncate", "clear", "prompt" | "prompt" (interactive), "summarize" (headless) |
 | `GOOSE_MAX_TURNS` | [Maximum number of turns](/docs/guides/smart-context-management#maximum-turns) allowed without user input | Integer (e.g., 10, 50, 100) | 1000 |
+| `CONTEXT_FILE_NAMES` | Specifies custom filenames for [hint/context files](/docs/guides/using-goosehints#custom-context-files) | JSON array of strings (e.g., `["CLAUDE.md", ".goosehints"]`) | `[".goosehints"]` |
 | `GOOSE_CLI_THEME` | [Theme](/docs/guides/goose-cli-commands#themes) for CLI response  markdown | "light", "dark", "ansi" | "dark" |
 | `GOOSE_SCHEDULER_TYPE` | Controls which scheduler Goose uses for [scheduled recipes](/docs/guides/recipes/session-recipes.md#schedule-recipe) | "legacy" or "temporal" | "legacy" (Goose's built-in cron scheduler) | 
 | `GOOSE_TEMPORAL_BIN` | Optional custom path to your Temporal binary | /path/to/temporal-service | None |
@@ -131,6 +132,9 @@ export GOOSE_MAX_TURNS=25
 # Set a reasonable limit for production
 export GOOSE_MAX_TURNS=100
 
+# Use multiple context files
+export CONTEXT_FILE_NAMES='["CLAUDE.md", ".goosehints", "project_rules.txt"]'
+
 # Set the ANSI theme for the session
 export GOOSE_CLI_THEME=ansi
 

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

@@ -339,7 +339,7 @@ You can turn your current Goose session into a reusable recipe that includes the
 
        **Basic Usage** - Run once and exit (see [run options](/docs/guides/goose-cli-commands#run-options) and [recipe commands](/docs/guides/goose-cli-commands#recipe) for more):
        ```sh
-       # Using recipe file in current directory
+       # Using recipe file in current directory or GOOSE_RECIPE_PATH directories
        goose run --recipe recipe.yaml
 
        # Using full path

documentation/docs/guides/using-goosehints.md

@@ -35,12 +35,10 @@ Goose supports two types of hint files:
 - **Global hints file** - These hints will apply to all your sessions with Goose, regardless of directory.
 - **Local hints file** -  These hints will only apply when working in a specific directory.
 
-:::tip
 You can use both global and local hints at the same time. When both exist, Goose will consider both your global preferences and project-specific requirements. If the instructions in your local hints file conflict with your global preferences, Goose will prioritize the local hints.
-:::
 
-:::tip
-You can name your context files differently -- e.g. `AGENTS.md` -- and Goose can still pick them up. Configure the `CONTEXT_FILE_NAMES` setting!
+:::tip Custom Context File
+You can [customize context file names](#custom-context-files) using the `CONTEXT_FILE_NAMES` environment variable.
 :::
 
 <Tabs groupId="interface">
@@ -126,4 +124,28 @@ Like prompts, this is not an extensive list to shape your `.goosehints` file. Yo
 - **Keep file updated**: Regularly update the `.goosehints` file to reflect any changes in project protocols or priorities.
 - **Be concise**: Make sure the content is straightforward and to the point, ensuring Goose can quickly parse and act on the information.
 - **Start small**: Create a small set of clear, specific hints and gradually expand them based on your needs. This makes it easier to understand how Goose interprets and applies your instructions.
-**Reference other files**: Point Goose to relevant files like /docs/style.md or /scripts/validation.js to reduce repetition and keep instructions lightweight.
+- **Reference other files**: Point Goose to relevant files like /docs/style.md or /scripts/validation.js to reduce repetition and keep instructions lightweight.
+
+## Custom Context Files
+
+Goose looks for `.goosehints` files by default, but you can configure a different filename or multiple context files using the `CONTEXT_FILE_NAMES` environment variable. This is useful for:
+
+- **Tool compatibility**: Use conventions from other AI tools (`AGENTS.md`, `CLAUDE.md`)
+- **Organization**: Separate frequently-used rules into multiple files that load automatically
+- **Project conventions**: Use context files from your project's established toolchain (`.cursorrules`)
+
+Here's how it works:
+1. Goose looks for each configured filename in both global (~/.config/goose/) and local (current directory) locations
+2. All found files are loaded and combined into the context
+
+### Configuration
+
+Set the `CONTEXT_FILE_NAMES` environment variable to a JSON array of filenames. If not set, it defaults to `[".goosehints"]`.
+
+```bash
+# Single custom file
+export CONTEXT_FILE_NAMES='["AGENTS.md"]'
+
+# Multiple files (loaded in order)
+export CONTEXT_FILE_NAMES='["CLAUDE.md", ".goosehints", "project_rules.txt"]'
+```