From 54b0e17c61b098d8f76d8c8359e3397535c64a2a Mon Sep 17 00:00:00 2001
From: Christopher Tso <christso@gmail.com>
Date: Sat, 4 Apr 2026 00:37:07 +0000
Subject: [PATCH] docs: clarify env var fallback for eval interpolation

---
 .../docs/docs/getting-started/quickstart.mdx  |  7 +++--
 .../docs/docs/targets/configuration.mdx       |  7 +++--
 .../interpolation-integration.test.ts         | 27 +++++++++++++++++++
 3 files changed, 37 insertions(+), 4 deletions(-)

diff --git a/apps/web/src/content/docs/docs/getting-started/quickstart.mdx b/apps/web/src/content/docs/docs/getting-started/quickstart.mdx
index 81b35127c..f4e4bc9f8 100644
--- a/apps/web/src/content/docs/docs/getting-started/quickstart.mdx
+++ b/apps/web/src/content/docs/docs/getting-started/quickstart.mdx
@@ -28,11 +28,14 @@ agentv init
 
 ## 3. Configure environment variables
 
-The init command creates a `.env.example` file in your project root.
+The init command creates a `.env.example` file in your project root. You can either export these
+variables in your shell/CI environment directly or copy `.env.example` to `.env` for local
+development.
 
 1. Copy `.env.example` to `.env`
 2. Fill in your API keys, endpoints, and other configuration values
-3. Update the environment variable names in `.agentv/targets.yaml` to match those defined in your `.env` file
+3. Update the environment variable names in `.agentv/targets.yaml` to match the variables you
+   exported or defined in `.env`
 
 ## 4. Create an eval
 
diff --git a/apps/web/src/content/docs/docs/targets/configuration.mdx b/apps/web/src/content/docs/docs/targets/configuration.mdx
index 31fd57bb2..113c03122 100644
--- a/apps/web/src/content/docs/docs/targets/configuration.mdx
+++ b/apps/web/src/content/docs/docs/targets/configuration.mdx
@@ -30,7 +30,9 @@ targets:
 
 ## Environment Variables
 
-Use `${{ VARIABLE_NAME }}` syntax to reference values from your `.env` file:
+Use `${{ VARIABLE_NAME }}` syntax to reference values from your environment. AgentV reads
+exported process environment variables directly, and it also loads `.env` files from the
+eval directory hierarchy when present:
 
 ```yaml
 targets:
@@ -40,7 +42,8 @@ targets:
     model: ${{ ANTHROPIC_MODEL }}
 ```
 
-This keeps secrets out of version-controlled files.
+This keeps secrets out of version-controlled files and avoids requiring a CI step that rewrites
+already-exported secrets into `.env`.
 
 ## Supported Providers
 
diff --git a/packages/core/test/evaluation/interpolation-integration.test.ts b/packages/core/test/evaluation/interpolation-integration.test.ts
index aa30799f3..5a6a3cdb6 100644
--- a/packages/core/test/evaluation/interpolation-integration.test.ts
+++ b/packages/core/test/evaluation/interpolation-integration.test.ts
@@ -36,6 +36,33 @@ describe('env interpolation in YAML loading', () => {
     expect(cases[0].criteria).toBe('Must return correct answer');
   });
 
+  it('uses exported process.env values even when no .env file exists', async () => {
+    const evalFile = path.join(testDir, 'interp-process-env.eval.yaml');
+    await writeFile(
+      evalFile,
+      [
+        'workspace:',
+        '  repos:',
+        '    - path: ./RepoA',
+        '      source:',
+        '        type: local',
+        '        path: "${{ AGENTV_TEST_PATH }}"',
+        'tests:',
+        '  - id: test-1',
+        '    input: "hello"',
+        '    criteria: "${{ AGENTV_TEST_CRITERIA }}"',
+        '',
+      ].join('\n'),
+    );
+
+    const cases = await loadTests(evalFile, testDir);
+    expect(cases[0].criteria).toBe('Must return correct answer');
+    expect(cases[0].workspace?.repos?.[0]?.source).toEqual({
+      type: 'local',
+      path: '/abs/path/to/repo',
+    });
+  });
+
   it('interpolates ${{ VAR }} in workspace repo source path', async () => {
     const evalFile = path.join(testDir, 'interp-workspace.eval.yaml');
     await writeFile(