From 92d86c08026394b303ce9d3be9ed2a8e906ca87c Mon Sep 17 00:00:00 2001
From: Rizel Scarlett <rizel@squareup.com>
Date: Tue, 11 Nov 2025 12:06:13 -0500
Subject: [PATCH] docs: add GOOSE_PATH_ROOT environment variable documentation
 (#5678)

Signed-off-by: Rizel Scarlett <rizel@squareup.com>
---
 CONTRIBUTING.md                               | 15 +++++++++
 .../docs/guides/environment-variables.md      | 31 +++++++++++++++++++
 2 files changed, 46 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7ec7a08c82..9e873d74a6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -252,6 +252,21 @@ reuse it. For things like automations or to test without doing official setup, y
 set the relevant env vars for that provider. For example `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
 or `DATABRICKS_HOST`. Refer to the provider details for more info on required keys.
 
+### Isolating Test Environments
+
+When testing changes or running multiple goose configurations, use `GOOSE_PATH_ROOT` to isolate your data:
+
+```bash
+# Test with a clean environment
+export GOOSE_PATH_ROOT="/tmp/goose-test"
+./target/debug/goose session
+
+# Or for a single command
+GOOSE_PATH_ROOT="/tmp/goose-dev" cargo run -p goose-cli -- session
+```
+
+This creates isolated `config/`, `data/`, and `state/` directories under the specified path, preventing your test sessions from affecting your main goose installation. See the [environment variables guide](./documentation/docs/guides/environment-variables.md#development--testing) for more details.
+
 ## Enable traces in goose with [locally hosted Langfuse](https://langfuse.com/docs/deployment/self-host)
 
 - Start a local Langfuse using the docs [here](https://langfuse.com/self-hosting/docker-compose). Create an organization and project and create API credentials.
diff --git a/documentation/docs/guides/environment-variables.md b/documentation/docs/guides/environment-variables.md
index 0b19b03a45..37485532c2 100644
--- a/documentation/docs/guides/environment-variables.md
+++ b/documentation/docs/guides/environment-variables.md
@@ -380,6 +380,37 @@ export ALPHA_FEATURES=true
 ALPHA_FEATURES=true goose session
 ```
 
+## Development & Testing
+
+These variables are primarily used for development, testing, and debugging goose itself.
+
+| Variable | Purpose | Values | Default |
+|----------|---------|---------|---------|
+| `GOOSE_PATH_ROOT` | Override the root directory for all goose data, config, and state files | Absolute path to directory | Platform-specific defaults |
+
+**Default locations:**
+- macOS: `~/Library/Application Support/Block/goose/`
+- Linux: `~/.local/share/goose/`
+- Windows: `%APPDATA%\Block\goose\`
+
+When set, goose creates `config/`, `data/`, and `state/` subdirectories under the specified path. Useful for isolating test environments, running multiple configurations, or CI/CD pipelines.
+
+**Examples**
+
+```bash
+# Temporary test environment
+export GOOSE_PATH_ROOT="/tmp/goose-test"
+
+# Isolated environment for a single command
+GOOSE_PATH_ROOT="/tmp/goose-isolated" goose run --recipe my-recipe.yaml
+
+# CI/CD usage
+GOOSE_PATH_ROOT="$(mktemp -d)" goose run --recipe integration-test.yaml
+
+# Use with developer tools
+GOOSE_PATH_ROOT="/tmp/goose-test" ./scripts/goose-db-helper.sh status
+```
+
 ## Variables Controlled by goose
 
 These variables are automatically set by goose during command execution.