agentgateway · kristin-kronstain-brown · Jun 29, 2026 · Jun 29, 2026 · Jun 29, 2026 · Jun 29, 2026
diff --git a/.claude/skills/doc-tests/SKILL.md b/.claude/skills/doc-tests/SKILL.md
@@ -73,11 +73,20 @@ Use this skill when adding tests to documentation guides in the `agentgateway/we
 title: ...
 test:
   <scenario-name>:
-  - file: content/docs/standalone/main/quickstart/<page>.md
+  - file: ${versionRoot}/quickstart/<page>.md   # same-version prereq
     path: <path-name>
+  - path: <path-name>                           # file: omitted -> this page itself
 ---
 ```
 
+**Write `file:` values version-relative so a page can be copied between `main` and `latest` with no front-matter edits:**
+
+- **Omit `file:`** when the source is the page that declares the test — it defaults to the declaring page.
+- **Use `${versionRoot}/...`** for prerequisites in the **same version** (e.g. `${versionRoot}/quickstart/install.md`). `${versionRoot}` expands to the version dir of the page declaring the test (`content/docs/kubernetes/main`, `.../latest`, etc.); `${version}` expands to just the segment (`main`/`latest`).
+- Use a **literal path** only when an entry must point at a *different* version on purpose.
+
+Token resolution covers the `kubernetes` and `standalone` sections; a `file:` that doesn't match the `content/docs/<section>/<version>/` layout is left as-is.
+
 **Pages with no testable content** (no code blocks, landing pages, concept pages, `_index.md` files without ordered steps, etc.) should be marked with `test: skip` instead of a scenario dict. This counts the page as covered in the test coverage report without generating any test cases:
 
 ```yaml
@@ -98,19 +107,19 @@ test: skip
 
 **Key principle:** The existing framework already supports every content type except pure link validation. Most "non-runnable" pages can become testable through content changes alone — adding hidden `{{< doc-test >}}` blocks that write configs, start services in the background, and run lightweight assertions. 
 
-Or for the latest (stable) version:
+Because the example above uses `${versionRoot}` and omits `file:` for the declaring page, the **same** front matter works under `latest/` without changes. Only when you deliberately mix versions do you write a literal path:
 
 ```yaml
 ---
 title: ...
 test:
   <scenario-name>:
-  - file: content/docs/standalone/latest/quickstart/<page>.md
+  - file: content/docs/standalone/latest/quickstart/<page>.md   # literal: pin a specific version
     path: <path-name>
 ---
 ```
 
-- Use the **content** path for `file`. List sources in dependency order if chaining (install → … → feature).
+- Prefer version-relative `file:` values (see above). List sources in dependency order if chaining (install → … → feature).
 - One scenario can list only the current page with one path if the guide is self-contained.
 - For Kubernetes docs, prerequisite files often come from `latest` (e.g. `content/docs/kubernetes/latest/quickstart/install.md`) while the feature page may be in `main` or `latest`.
 
@@ -299,7 +308,7 @@ When in doubt, flag the failure to the user rather than silently adjusting the t
 - [ ] If the guide has a long-running server, a **hidden** doc-test block starts it in the background (and optional trap/sleep); visible "start server" block has **no** path.
 - [ ] Placeholders in shell blocks are quoted or use `${VAR:-default}` so the script has no syntax errors.
 - [ ] `test:` front matter on the **content** page lists the right `file` and `path`; file path is the content path (extractor follows reuse). For pages with no testable content (index pages, no code blocks), use `test: skip` instead — counts toward coverage without generating test cases.
-- [ ] When copying a test chain between `main` and `latest`, **update every `file:` path** in front matter to match the target version directory.
+- [ ] `file:` values are **version-relative** (`${versionRoot}/...`, or omitted for the declaring page) so copying a page between `main` and `latest` needs **no** front-matter edits. Use a literal path only to point at a different version on purpose.
 - [ ] Prerequisite `file:` paths come from the guide's actual **Before you begin** links — don't guess; check the links to confirm exact paths.
 - [ ] No `kubectl port-forward` in any visible block — replace with YAMLTest HTTP assertions using `${INGRESS_GW_ADDRESS}`.
 - [ ] Host headers in YAMLTest `http.headers` use bare hostnames — no port suffix (e.g. `host: "example.com"`, not `host: "example.com:80"`). Including a port causes ECONNRESET, not an HTTP error.

diff --git a/.cursor/skills/doc-tests/SKILL.md b/.cursor/skills/doc-tests/SKILL.md
@@ -68,24 +68,19 @@ Use this skill when adding tests to documentation guides in the `website` repo s
 title: ...
 test:
   <scenario-name>:
-  - file: content/docs/standalone/main/quickstart/<page>.md
+  - file: ${versionRoot}/quickstart/<page>.md   # same-version prereq
     path: <path-name>
+  - path: <path-name>                           # file: omitted -> this page itself
 ---
 ```
 
-Or for the latest (stable) version:
+Write `file:` values **version-relative** so a page can be copied between `main` and `latest` with no front-matter edits:
 
-```yaml
----
-title: ...
-test:
-  <scenario-name>:
-  - file: content/docs/standalone/latest/quickstart/<page>.md
-    path: <path-name>
----
-```
+- **Omit `file:`** when the source is the page declaring the test (it defaults to that page).
+- **Use `${versionRoot}/...`** for same-version prerequisites. `${versionRoot}` expands to the version dir of the declaring page (`content/docs/kubernetes/main`, `.../latest`); `${version}` expands to just the segment. Covers the `kubernetes` and `standalone` sections.
+- Use a **literal path** only to point at a *different* version on purpose, e.g. `content/docs/standalone/latest/quickstart/<page>.md`.
 
-- Use the **content** path for `file`. List sources in dependency order if chaining (install → … → feature).
+- List sources in dependency order if chaining (install → … → feature).
 - One scenario can list only the current page with one path if the guide is self-contained.
 - For Kubernetes docs, prerequisite files often come from `latest` (e.g. `content/docs/kubernetes/latest/quickstart/install.md`) while the feature page may be in `main` or `latest`.
 

diff --git a/assets/agw-docs/versions/helm-version-flag.md b/assets/agw-docs/versions/helm-version-flag.md
@@ -1 +1 @@
-v{{< reuse "agw-docs/versions/n-patch.md" >}}
+{{< version exclude-if="main" >}}v{{< /version >}}{{< reuse "agw-docs/versions/n-patch.md" >}}
diff --git a/content/docs/kubernetes/latest/agent/a2a.md b/content/docs/kubernetes/latest/agent/a2a.md
@@ -4,9 +4,9 @@ weight: 40
 description: Route to A2A servers and securely expose their skills through agentgateway.
 test:
   a2a:
-  - file: content/docs/kubernetes/latest/quickstart/install.md
+  - file: ${versionRoot}/quickstart/install.md
     path: standard
-  - file: content/docs/kubernetes/latest/agent/a2a.md
+  - file: ${versionRoot}/agent/a2a.md
     path: a2a
 ---
 

diff --git a/content/docs/kubernetes/latest/install/helm.md b/content/docs/kubernetes/latest/install/helm.md
@@ -4,10 +4,10 @@ weight: 5
 description: Install agentgateway and related components.
 test:
   helm-install:
-  - file: content/docs/kubernetes/latest/install/helm.md
+  - file: ${versionRoot}/install/helm.md
     path: standard
   helm-install-experimental:
-  - file: content/docs/kubernetes/latest/install/helm.md
+  - file: ${versionRoot}/install/helm.md
     path: experimental
 ---
 

diff --git a/content/docs/kubernetes/latest/install/sample-app.md b/content/docs/kubernetes/latest/install/sample-app.md
@@ -4,11 +4,11 @@ weight: 20
 description: Set up the httpbin sample app to try traffic management, security, and resiliency guides.
 test:
   install-httpbin:
-  - file: content/docs/kubernetes/latest/quickstart/install.md
+  - file: ${versionRoot}/quickstart/install.md
     path: standard
-  - file: content/docs/kubernetes/latest/setup/gateway.md
+  - file: ${versionRoot}/setup/gateway.md
     path: all
-  - file: content/docs/kubernetes/latest/install/sample-app.md
+  - file: ${versionRoot}/install/sample-app.md
     path: install-httpbin
 ---
 

diff --git a/content/docs/kubernetes/latest/integrations/llm-clients/_index.md b/content/docs/kubernetes/latest/integrations/llm-clients/_index.md
@@ -4,11 +4,11 @@ weight: 10
 description: Configure AI coding tools and applications to use agentgateway running in Kubernetes
 test:
   llm-clients-k8s-gateway-url:
-  - file: content/docs/kubernetes/latest/install/helm.md
+  - file: ${versionRoot}/install/helm.md
     path: standard
-  - file: content/docs/kubernetes/latest/setup/gateway.md
+  - file: ${versionRoot}/setup/gateway.md
     path: all
-  - file: content/docs/kubernetes/latest/integrations/llm-clients/_index.md
+  - file: ${versionRoot}/integrations/llm-clients/_index.md
     path: llm-clients-k8s-gateway-url
 ---
 

diff --git a/content/docs/kubernetes/latest/integrations/llm-clients/claude-code.md b/content/docs/kubernetes/latest/integrations/llm-clients/claude-code.md
@@ -4,11 +4,11 @@ weight: 10
 description: Configure Claude Code CLI to use agentgateway running in Kubernetes
 test:
   claude-code-k8s:
-  - file: content/docs/kubernetes/latest/install/helm.md
+  - file: ${versionRoot}/install/helm.md
     path: standard
-  - file: content/docs/kubernetes/latest/setup/gateway.md
+  - file: ${versionRoot}/setup/gateway.md
     path: all
-  - file: content/docs/kubernetes/latest/integrations/llm-clients/claude-code.md
+  - file: ${versionRoot}/integrations/llm-clients/claude-code.md
     path: claude-code-k8s
 ---
 

diff --git a/content/docs/kubernetes/latest/integrations/mcp-clients/_index.md b/content/docs/kubernetes/latest/integrations/mcp-clients/_index.md
@@ -4,13 +4,13 @@ weight: 10
 description: Connect AI coding assistants to MCP servers exposed through agentgateway on Kubernetes
 test:
   mcp-clients-k8s:
-  - file: content/docs/kubernetes/latest/install/helm.md
+  - file: ${versionRoot}/install/helm.md
     path: standard
-  - file: content/docs/kubernetes/latest/setup/gateway.md
+  - file: ${versionRoot}/setup/gateway.md
     path: all
-  - file: content/docs/kubernetes/latest/mcp/static-mcp.md
+  - file: ${versionRoot}/mcp/static-mcp.md
     path: setup-mcp-server
-  - file: content/docs/kubernetes/latest/integrations/mcp-clients/_index.md
+  - file: ${versionRoot}/integrations/mcp-clients/_index.md
     path: mcp-clients-k8s
 ---
 

diff --git a/content/docs/kubernetes/latest/llm/budget-limits.md b/content/docs/kubernetes/latest/llm/budget-limits.md
@@ -4,13 +4,13 @@ weight: 75
 description: Control LLM spending by enforcing token budget limits per API key or user.
 test:
   budget-limits-apikey-auth:
-  - file: content/docs/kubernetes/latest/quickstart/install.md
+  - file: ${versionRoot}/quickstart/install.md
     path: standard
-  - file: content/docs/kubernetes/latest/setup/gateway.md
+  - file: ${versionRoot}/setup/gateway.md
     path: all
-  - file: content/docs/kubernetes/latest/llm/providers/openai.md
+  - file: ${versionRoot}/llm/providers/openai.md
     path: openai-setup
-  - file: content/docs/kubernetes/latest/llm/budget-limits.md
+  - file: ${versionRoot}/llm/budget-limits.md
     path: budget-limits
 ---
 

diff --git a/content/docs/kubernetes/latest/llm/content-routing.md b/content/docs/kubernetes/latest/llm/content-routing.md
@@ -4,11 +4,11 @@ weight: 45
 description: Route requests to different LLM backends based on request body content, such as the requested model name.
 test:
   content-routing-model:
-  - file: content/docs/kubernetes/latest/quickstart/install.md
+  - file: ${versionRoot}/quickstart/install.md
     path: standard
-  - file: content/docs/kubernetes/latest/setup/gateway.md
+  - file: ${versionRoot}/setup/gateway.md
     path: all
-  - file: content/docs/kubernetes/latest/llm/content-routing.md
+  - file: ${versionRoot}/llm/content-routing.md
     path: content-routing
 ---
 

diff --git a/content/docs/kubernetes/latest/llm/failover.md b/content/docs/kubernetes/latest/llm/failover.md
@@ -4,13 +4,13 @@ weight: 40
 description: Priority-based failover across LLM providers (automatic fallback when models fail or are rate-limited).
 test:
   failover:
-  - file: content/docs/kubernetes/latest/install/helm.md
+  - file: ${versionRoot}/install/helm.md
     path: standard
-  - file: content/docs/kubernetes/latest/setup/gateway.md
+  - file: ${versionRoot}/setup/gateway.md
     path: all
-  - file: content/docs/kubernetes/latest/llm/providers/httpbun.md
+  - file: ${versionRoot}/llm/providers/httpbun.md
     path: setup-httpbun-llm
-  - file: content/docs/kubernetes/latest/llm/failover.md
+  - file: ${versionRoot}/llm/failover.md
     path: failover
 ---
 

diff --git a/content/docs/kubernetes/latest/llm/load-balancing.md b/content/docs/kubernetes/latest/llm/load-balancing.md
@@ -4,11 +4,11 @@ weight: 35
 description: Distribute requests across multiple LLM providers automatically (Power of Two Choices, P2C).
 test:
   load-balancing-multi-provider:
-  - file: content/docs/kubernetes/latest/quickstart/install.md
+  - file: ${versionRoot}/quickstart/install.md
     path: standard
-  - file: content/docs/kubernetes/latest/setup/gateway.md
+  - file: ${versionRoot}/setup/gateway.md
     path: all
-  - file: content/docs/kubernetes/latest/llm/load-balancing.md
+  - file: ${versionRoot}/llm/load-balancing.md
     path: load-balancing
 ---
 

diff --git a/content/docs/kubernetes/latest/llm/observability.md b/content/docs/kubernetes/latest/llm/observability.md
@@ -4,13 +4,13 @@ weight: 95
 description: View LLM-specific metrics and access logs for token usage and request monitoring.
 test:
   llm-observability:
-  - file: content/docs/kubernetes/latest/quickstart/install.md
+  - file: ${versionRoot}/quickstart/install.md
     path: standard
-  - file: content/docs/kubernetes/latest/setup/gateway.md
+  - file: ${versionRoot}/setup/gateway.md
     path: all
-  - file: content/docs/kubernetes/latest/llm/providers/openai.md
+  - file: ${versionRoot}/llm/providers/openai.md
     path: openai-setup
-  - file: content/docs/kubernetes/latest/llm/observability.md
+  - file: ${versionRoot}/llm/observability.md
     path: llm-observability
 ---
 

diff --git a/content/docs/kubernetes/latest/llm/providers/httpbun.md b/content/docs/kubernetes/latest/llm/providers/httpbun.md
@@ -4,11 +4,11 @@ weight: 100
 description: Set up httpbun as a mock OpenAI-compatible LLM backend for testing without API keys.
 test:
   setup-httpbun-llm:
-  - file: content/docs/kubernetes/latest/install/helm.md
+  - file: ${versionRoot}/install/helm.md
     path: standard
-  - file: content/docs/kubernetes/latest/setup/gateway.md
+  - file: ${versionRoot}/setup/gateway.md
     path: all
-  - file: content/docs/kubernetes/latest/llm/providers/httpbun.md
+  - file: ${versionRoot}/llm/providers/httpbun.md
     path: setup-httpbun-llm
 ---
 

diff --git a/content/docs/kubernetes/latest/llm/providers/ollama.md b/content/docs/kubernetes/latest/llm/providers/ollama.md
@@ -4,11 +4,11 @@ weight: 25
 description: Configure agentgateway to route LLM traffic to Ollama for local model inference
 test:
   ollama-provider-setup:
-  - file: content/docs/kubernetes/latest/install/helm.md
+  - file: ${versionRoot}/install/helm.md
     path: standard
-  - file: content/docs/kubernetes/latest/setup/gateway.md
+  - file: ${versionRoot}/setup/gateway.md
     path: all
-  - file: content/docs/kubernetes/latest/llm/providers/ollama.md
+  - file: ${versionRoot}/llm/providers/ollama.md
     path: ollama-provider-setup
 ---
 

diff --git a/content/docs/kubernetes/latest/llm/providers/openai.md b/content/docs/kubernetes/latest/llm/providers/openai.md
@@ -4,11 +4,11 @@ weight: 20
 description: Configure OpenAI as an LLM provider for agentgateway.
 test:
   openai-setup:
-  - file: content/docs/kubernetes/latest/quickstart/install.md
+  - file: ${versionRoot}/quickstart/install.md
     path: standard
-  - file: content/docs/kubernetes/latest/setup/gateway.md
+  - file: ${versionRoot}/setup/gateway.md
     path: all
-  - file: content/docs/kubernetes/latest/llm/providers/openai.md
+  - file: ${versionRoot}/llm/providers/openai.md
     path: openai-setup
 ---
 

diff --git a/content/docs/kubernetes/latest/llm/providers/vllm.md b/content/docs/kubernetes/latest/llm/providers/vllm.md
@@ -4,11 +4,11 @@ weight: 30
 description: Configure agentgateway to route traffic to vLLM for self-hosted model inference
 test:
   vllm-provider-setup:
-  - file: content/docs/kubernetes/latest/install/helm.md
+  - file: ${versionRoot}/install/helm.md
     path: standard
-  - file: content/docs/kubernetes/latest/setup/gateway.md
+  - file: ${versionRoot}/setup/gateway.md
     path: all
-  - file: content/docs/kubernetes/latest/llm/providers/vllm.md
+  - file: ${versionRoot}/llm/providers/vllm.md
     path: vllm-provider-setup
 ---
 

diff --git a/content/docs/kubernetes/latest/llm/rate-limit.md b/content/docs/kubernetes/latest/llm/rate-limit.md
@@ -4,13 +4,13 @@ weight: 80
 description: Control LLM costs with token-based rate limiting and request-based limits.
 test:
   llm-token-rate-limit:
-  - file: content/docs/kubernetes/latest/install/helm.md
+  - file: ${versionRoot}/install/helm.md
     path: standard
-  - file: content/docs/kubernetes/latest/setup/gateway.md
+  - file: ${versionRoot}/setup/gateway.md
     path: all
-  - file: content/docs/kubernetes/latest/llm/providers/httpbun.md
+  - file: ${versionRoot}/llm/providers/httpbun.md
     path: setup-httpbun-llm
-  - file: content/docs/kubernetes/latest/llm/rate-limit.md
+  - file: ${versionRoot}/llm/rate-limit.md
     path: llm-token-rate-limit
 ---
 

diff --git a/content/docs/kubernetes/latest/llm/realtime.md b/content/docs/kubernetes/latest/llm/realtime.md
@@ -4,13 +4,13 @@ weight: 47
 description: Proxy OpenAI Realtime API WebSocket traffic and track token usage.
 test:
   realtime:
-  - file: content/docs/kubernetes/latest/quickstart/install.md
+  - file: ${versionRoot}/quickstart/install.md
     path: standard
-  - file: content/docs/kubernetes/latest/setup/gateway.md
+  - file: ${versionRoot}/setup/gateway.md
     path: all
-  - file: content/docs/kubernetes/latest/llm/providers/openai.md
+  - file: ${versionRoot}/llm/providers/openai.md
     path: openai-setup
-  - file: content/docs/kubernetes/latest/llm/realtime.md
+  - file: ${versionRoot}/llm/realtime.md
     path: realtime
 ---
 

diff --git a/content/docs/kubernetes/latest/llm/streaming.md b/content/docs/kubernetes/latest/llm/streaming.md
@@ -4,13 +4,13 @@ weight: 45
 description: Stream responses from the LLM to the end user through agentgateway.
 test:
   streaming-openai:
-  - file: content/docs/kubernetes/latest/quickstart/install.md
+  - file: ${versionRoot}/quickstart/install.md
     path: standard
-  - file: content/docs/kubernetes/latest/setup/gateway.md
+  - file: ${versionRoot}/setup/gateway.md
     path: all
-  - file: content/docs/kubernetes/latest/llm/providers/openai.md
+  - file: ${versionRoot}/llm/providers/openai.md
     path: openai-setup
-  - file: content/docs/kubernetes/latest/llm/streaming.md
+  - file: ${versionRoot}/llm/streaming.md
     path: streaming-openai
 ---
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		v{{< reuse "agw-docs/versions/n-patch.md" >}}
		{{< version exclude-if="main" >}}v{{< /version >}}{{< reuse "agw-docs/versions/n-patch.md" >}}