docs: add guides for agctl installation and request tracing

assets/agw-docs/pages/operations/agctl-install.md

@@ -0,0 +1,89 @@
+`agctl` is the CLI tool for controlling and debugging agentgateway. Use it to inspect configuration, trace live requests, and interact with running gateway instances.
+
+## Install agctl
+
+Download the `agctl` binary for your platform from the [agentgateway releases page](https://github.com/agentgateway/agentgateway/releases).
+
+{{< tabs tabTotal="3" items="Linux,macOS,Windows" >}}
+{{% tab tabName="Linux" %}}
+
+```sh
+curl -sL https://github.com/agentgateway/agentgateway/releases/latest/download/agctl-linux-amd64 -o agctl
+chmod +x agctl
+sudo mv agctl /usr/local/bin/agctl
+```
+
+{{% /tab %}}
+{{% tab tabName="macOS" %}}
+
+```sh
+# Intel
+curl -sL https://github.com/agentgateway/agentgateway/releases/latest/download/agctl-darwin-amd64 -o agctl
+
+# Apple Silicon
+curl -sL https://github.com/agentgateway/agentgateway/releases/latest/download/agctl-darwin-arm64 -o agctl
+
+chmod +x agctl
+sudo mv agctl /usr/local/bin/agctl
+```
+
+{{% /tab %}}
+{{% tab tabName="Windows" %}}
+
+Download `agctl-windows-amd64.exe` from the [releases page](https://github.com/agentgateway/agentgateway/releases) and add it to your `PATH`.
+
+{{% /tab %}}
+{{< /tabs >}}
+
+## Verify the installation
+
+```sh
+agctl --help
+```
+
+Example output:
+
+```
+agctl controls and inspects Agentgateway resources
+
+Usage:
+  agctl [command]
+
+Available Commands:
+  config      Retrieve Agentgateway configuration for a resource
+  trace       Trace the next request handled by an Agentgateway pod or local instance
+  help        Help about any command
+
+Flags:
+  -h, --help   help for agctl
+```
+
+## Upgrade agctl
+
+To upgrade, download the new binary from the [releases page](https://github.com/agentgateway/agentgateway/releases) and replace the existing binary following the same steps as installation.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| [`agctl config`](#agctl-config) | Retrieve agentgateway configuration for a resource. |
+| [`agctl trace`]({{< link-hextra path="/operations/agctl-trace/" >}}) | Trace the next request handled by an agentgateway pod or local instance. |
+
+### agctl config
+
+Retrieve the current configuration from a running agentgateway instance.
+
+```sh
+# All configuration
+agctl config all
+
+# Backend configuration only
+agctl config backends
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `-n, --namespace` | | Namespace for resource resolution. |
+| `-f, --file` | | Path to an agentgateway config dump JSON file. |
+| `--proxy-admin-port` | `15000` | Admin port. |
+| `-o, --output` | `short` | Output format: `short`, `json`, or `yaml`. |

assets/agw-docs/pages/operations/agctl-trace.md

@@ -0,0 +1,101 @@
+Use `agctl trace` to inspect the next request handled by agentgateway in real time. The command connects to the admin API and streams trace events — showing the route matched, policies applied, filters evaluated, and the final response — either in an interactive TUI or as raw JSONL.
+
+## Before you begin
+
+- Install `agctl`. See [Install agctl]({{< link-hextra path="/operations/agctl/" >}}).
+- Have a running agentgateway instance.
+
+## Trace a request
+
+Run `agctl trace` to watch for the next incoming request. The command blocks until a request arrives, then renders the trace in an interactive TUI.
+
+{{< tabs tabTotal="2" items="Kubernetes,Standalone" >}}
+{{% tab tabName="Kubernetes" %}}
+
+Watch for the next request on the auto-detected gateway pod:
+
+```sh
+agctl trace
+```
+
+Target a specific gateway resource:
+
+```sh
+agctl trace gateway/my-gateway
+```
+
+Watch in a specific namespace:
+
+```sh
+agctl trace gateway/my-gateway -n my-namespace
+```
+
+{{% /tab %}}
+{{% tab tabName="Standalone" %}}
+
+Trace against a local agentgateway instance:
+
+```sh
+agctl trace --local
+```
+
+If agentgateway is listening on a non-default admin port:
+
+```sh
+agctl trace --local --proxy-admin-port 15001
+```
+
+{{% /tab %}}
+{{< /tabs >}}
+
+## Trigger a request as part of the trace
+
+Pass a URL after `--` to have `agctl` both enable tracing and send the request. Use `--port` to specify the gateway listener port.
+
+{{< tabs tabTotal="2" items="Kubernetes,Standalone" >}}
+{{% tab tabName="Kubernetes" %}}
+
+```sh
+agctl trace gateway/my-gateway --port 80 -- http://host/some/path
+```
+
+With additional curl arguments (for example, a bearer token):
+
+```sh
+agctl trace gateway/my-gateway --port 80 -- http://host/some/path -H "Authorization: Bearer sk-123"
+```
+
+{{% /tab %}}
+{{% tab tabName="Standalone" %}}
+
+```sh
+agctl trace --local --port 8080 -- http://host/some/path
+```
+
+With additional curl arguments:
+
+```sh
+agctl trace --local --port 8080 -- http://host/some/path -H "Authorization: Bearer sk-123"
+```
+
+{{% /tab %}}
+{{< /tabs >}}
+
+## Output raw JSONL instead of the TUI
+
+Use `--raw` to print trace events as newline-delimited JSON (JSONL) instead of opening the interactive TUI. This is useful for scripting or piping to tools like `jq`.
+
+```sh
+agctl trace --raw
+agctl trace gateway/my-gateway --raw --port 80 -- http://host/some/path | jq .
+```
+
+## Reference
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `-n, --namespace` | | Namespace to use when resolving resources. |
+| `--proxy-admin-port` | `15000` | Agentgateway admin port. |
+| `--raw` | `false` | Print trace events as JSONL instead of opening the TUI. |
+| `--port` | | Gateway listener port to use when triggering a request. Required when a request URL is provided. |
+| `--local` | `false` | Trace against a local agentgateway instance on `127.0.0.1`. Cannot be combined with a resource argument. |

assets/agw-docs/pages/operations/debug-standalone.md

@@ -1,5 +1,9 @@
 Use built-in tools to troubleshoot issues in your standalone agentgateway setup.
 
+## Trace live requests {#trace}
+
+Use `agctl trace` to inspect the next request handled by agentgateway in real time, including the route matched, policies applied, and the final response. See [Trace requests]({{< link-hextra path="/operations/agctl-trace/" >}}) for full details.
+
 ## Enable debug logs {#debug-logs}
 
 Enable debug logs in agentgateway. You can choose between two methods: using the logging endpoint or updating the config file.

assets/agw-docs/pages/operations/debug.md

@@ -1,5 +1,9 @@
 Use built-in tools to troubleshoot issues in your {{< reuse "/agw-docs/snippets/kgateway.md" >}} setup.
 
+## Trace live requests {#trace}
+
+Use `agctl trace` to inspect the next request handled by agentgateway in real time, including the route matched, policies applied, and the final response. See [Trace requests]({{< link-hextra path="/operations/agctl-trace/" >}}) for full details.
+
 {{< reuse "/agw-docs/snippets/agentgateway-capital.md" >}} consists of the control plane and an {{< reuse "/agw-docs/snippets/data-plane.md" >}} data plane. If you experience issues in your environment, such as policies that are not applied or traffic that is not routed correctly, in a lot of cases, these errors can be observed at the proxy.
 
 ## Debug the control plane {#control-plane}

content/docs/kubernetes/latest/operations/agctl-trace.md

@@ -0,0 +1,7 @@
+---
+title: Trace requests
+weight: 30
+description: Use agctl trace to inspect live requests flowing through your agentgateway deployment.
+---
+
+{{< reuse "agw-docs/pages/operations/agctl-trace.md" >}}

content/docs/kubernetes/latest/operations/agctl.md

@@ -0,0 +1,7 @@
+---
+title: agctl CLI
+weight: 25
+description: Install and use the agctl CLI to debug and inspect your agentgateway deployment.
+---
+
+{{< reuse "agw-docs/pages/operations/agctl-install.md" >}}

content/docs/kubernetes/main/operations/agctl-trace.md

@@ -0,0 +1,7 @@
+---
+title: Trace requests
+weight: 30
+description: Use agctl trace to inspect live requests flowing through your agentgateway deployment.
+---
+
+{{< reuse "agw-docs/pages/operations/agctl-trace.md" >}}

content/docs/kubernetes/main/operations/agctl.md

@@ -0,0 +1,7 @@
+---
+title: agctl CLI
+weight: 25
+description: Install and use the agctl CLI to debug and inspect your agentgateway deployment.
+---
+
+{{< reuse "agw-docs/pages/operations/agctl-install.md" >}}

content/docs/standalone/latest/operations/agctl-trace.md

@@ -0,0 +1,7 @@
+---
+title: Trace requests
+weight: 25
+description: Use agctl trace to inspect live requests flowing through your standalone agentgateway.
+---
+
+{{< reuse "agw-docs/pages/operations/agctl-trace.md" >}}

content/docs/standalone/latest/operations/agctl.md

@@ -0,0 +1,7 @@
+---
+title: agctl CLI
+weight: 20
+description: Install and use the agctl CLI to debug and inspect your standalone agentgateway.
+---
+
+{{< reuse "agw-docs/pages/operations/agctl-install.md" >}}

content/docs/standalone/main/operations/agctl-trace.md

@@ -0,0 +1,7 @@
+---
+title: Trace requests
+weight: 25
+description: Use agctl trace to inspect live requests flowing through your standalone agentgateway.
+---
+
+{{< reuse "agw-docs/pages/operations/agctl-trace.md" >}}

content/docs/standalone/main/operations/agctl.md

@@ -0,0 +1,7 @@
+---
+title: agctl CLI
+weight: 20
+description: Install and use the agctl CLI to debug and inspect your standalone agentgateway.
+---
+
+{{< reuse "agw-docs/pages/operations/agctl-install.md" >}}