Document .env discovery improvements

app/en/get-started/quickstarts/mcp-server-quickstart/page.mdx

@@ -80,17 +80,17 @@ This generates a Python module with the following structure:
 
 ```bash
 my_server/
+├── .env.example
 ├── src/
 │   └── my_server/
 │       ├── __init__.py
-│       ├── .env.example
 │       └── server.py
 └── pyproject.toml
 ```
 
 - **server.py** Entrypoint file with MCPApp and example tools
 - **pyproject.toml** Dependencies and project configuration
-- **.env.example** Example `.env` file containing a secret required by one of the generated tools in `server.py`
+- **.env.example** Example `.env` file at the project root containing a secret required by one of the generated tools in `server.py`. Arcade automatically discovers `.env` files by traversing upward from the current directory.
 
 `server.py` includes proper structure with command-line argument handling. It creates an `MCPApp` with three sample tools:
 
@@ -106,17 +106,17 @@ Secrets are sensitive strings like passwords, API keys, or other tokens that gra
 
 <Tabs items={[".env file", "Environment Variable"]}>
 <Tabs.Tab>
-You can create a `.env` file at the same directory as your entrypoint file (`server.py`) and add your secret:
+You can create a `.env` file at your project root directory and add your secret:
 
 ```env filename=".env"
 MY_SECRET_KEY="my-secret-value"
 ```
 
-The generated project includes a `.env.example` file with the secret key name and example value.
+The generated project includes a `.env.example` file at the project root with the secret key name and example value.
 You can rename it to `.env` to start using it.
 
 ```bash
-mv .env.example .env
+mv ../../.env.example ../../.env
 ```
 
 </Tabs.Tab>

app/en/guides/create-tools/tool-basics/build-mcp-server/page.mdx

@@ -76,17 +76,17 @@ This generates a Python module with the following structure:
 
 ```bash
 my_server/
+├── .env.example
 ├── src/
 │   └── my_server/
 │       ├── __init__.py
-│       ├── .env.example
 │       └── server.py
 └── pyproject.toml
 ```
 
 1. **server.py** Main server file with MCPApp and example tools. It creates an `MCPApp`, defines tools with `@app.tool`, and will start the server with `app.run()` when the file is executed directly.
 1. **pyproject.toml** Dependencies and project configuration
-1. **.env.example** Example `.env` file containing a secret required by one of the generated tools in `server.py`. Environments are loaded on server start, so **if you update the `.env` file, you will need to restart your server.**
+1. **.env.example** Example `.env` file at the project root containing a secret required by one of the generated tools in `server.py`. Arcade automatically discovers `.env` files by traversing upward from the current directory, so placing it at the project root makes it accessible from any subdirectory. Environments are loaded on server start, so **if you update the `.env` file, you will need to restart your server.**
 
 ```python filename="server.py" showLineNumbers
 #!/usr/bin/env python3
@@ -171,17 +171,19 @@ Secrets are sensitive strings like passwords, API keys, or other tokens that gra
 
 <Tabs items={[".env file", "Environment Variable"]}>
 <Tabs.Tab>
-You can create a `.env` file at the same directory as your entrypoint file (`server.py`) and add your secret:
+You can create a `.env` file at your project root directory and add your secret:
 
 ```env filename=".env"
 MY_SECRET_KEY="my-secret-value"
 ```
 
-The generated project includes a `.env.example` file with the secret key name and example value.
+Arcade automatically discovers `.env` files by traversing upward from the current directory through parent directories. This means you can place your `.env` file at the project root (`my_server/`), and it will be found even when running your server from a subdirectory like `src/my_server/`.
+
+The generated project includes a `.env.example` file at the project root with the secret key name and example value.
 You can rename it to `.env` to start using it.
 
 ```bash
-mv .env.example .env
+mv ../../.env.example ../../.env
 ```
 
 </Tabs.Tab>

app/en/guides/create-tools/tool-basics/create-tool-secrets/page.mdx

@@ -68,13 +68,13 @@ Depending on where you're running your server, you can store your secret in a fe
 
 <Tabs items={[".env file", "Arcade Dashboard", "Arcade CLI", "Environment Variable"]}>
 <Tabs.Tab>
-You can create a `.env` file in the same directory as your entrypoint file (typically `server.py` by default) and add your secret:
+You can create a `.env` file in your project root directory and add your secret:
 
 ```env filename=".env"
 MY_SECRET_KEY="my-secret-value"
 ```
 
-The project includes a `.env.example` file with the secret key name and example value.
+The project includes a `.env.example` file at the project root with the secret key name and example value.
 You can rename it to `.env` to start using it.
 
 ```bash
@@ -206,7 +206,7 @@ When your tool is executed, it will return: `"Got SECRET_KEY of length..."`. In
 ## Key Concepts
 
 - **Secure Access:** Secrets are accessed through context, not imported directly
-- **Environment Integration:** Works with both environment variables and .env files
+- **Environment Integration:** Works with both environment variables and `.env` files
 - **Error Handling:** Always handle the case where a secret might be missing
 - **Masking:** Never expose full secret values in logs or return values
 - **Declaration:** Use `requires_secrets` to make dependencies explicit
@@ -221,7 +221,7 @@ SECRET_KEY="supersecret"
 
 <Callout type="warning">
 
-For the code to work, you must define your environment variables locally or in a `.env` file.
+For the code to work, you must define your environment variables locally or in a `.env` file. Arcade will automatically search upward from the current directory to find your `.env` file.
 
 </Callout>
 

app/en/guides/deployment-hosting/arcade-deploy/page.mdx

@@ -105,7 +105,7 @@ Validating user is logged in...
 Validating pyproject.toml exists in current directory...
 ✓ pyproject.toml found at /path/to/your/project/pyproject.toml
 
-Loading .env file from current directory if it exists...
+Searching for .env file...
 ✓ Loaded environment from /path/to/your/project/.env
 
 Validating server is healthy and extracting metadata before deploying...

app/en/references/mcp/python/settings/page.mdx

@@ -7,6 +7,42 @@ description: Global configuration and environment-driven settings for the Arcade
 
 Global configuration and environment-driven settings.
 
+## find_env_file()
+
+```python
+arcade_mcp_server.settings.find_env_file(
+    start_dir: Path | None = None,
+    stop_at: Path | None = None,
+    filename: str = ".env"
+) -> Path | None
+```
+
+Find a `.env` file by traversing upward through parent directories.
+
+Starts at the specified directory (or current working directory) and traverses upward through parent directories until a `.env` file is found or the filesystem root (or `stop_at` directory) is reached.
+
+**Parameters:**
+- `start_dir` - Directory to start searching from. Defaults to current working directory.
+- `stop_at` - Directory to stop traversal at (inclusive). If specified, the search will not continue past this directory. The `stop_at` directory itself is still checked for the `.env` file.
+- `filename` - Name of the env file to find. Defaults to `.env`.
+
+**Returns:** Path to the `.env` file if found, `None` otherwise.
+
+**Example:**
+
+```python
+from arcade_mcp_server.settings import find_env_file
+
+# Find .env starting from current directory
+env_path = find_env_file()
+
+# Find .env starting from a specific directory
+env_path = find_env_file(start_dir=Path("/path/to/project/src"))
+
+# Find .env but don't search above project root
+env_path = find_env_file(stop_at=Path("/path/to/project"))
+```
+
 ## MCPSettings
 
 ```python
@@ -25,6 +61,10 @@ from_env() classmethod
 
 Create settings from environment variables.
 
+Automatically discovers and loads a `.env` file by traversing upward from the current directory through parent directories until a `.env` file is found or the filesystem root is reached.
+
+The `.env` file is loaded with `override=False`, meaning existing environment variables take precedence. Multiple calls are safe.
+
 ### to_dict()
 
 ```python