sebbycorp · Nov 10, 2026 · Nov 7, 2026 · Nov 7, 2026 · Nov 10, 2026 · Nov 10, 2026
diff --git a/docs-site/assets/kagent-docs/snippets/grpcurl-prerequisites.md b/docs-site/assets/kagent-docs/snippets/grpcurl-prerequisites.md
@@ -1,4 +1,9 @@
+{{% version include-if="latest" %}}
 1. [Install kagent]({{< link path="setup/installation" >}}), and confirm that your installation sets `config.server.grpcReflection=true`. Reflection lets grpcurl discover the controller's methods without a local copy of kagent's protocol buffer definitions.
+{{% /version %}}
+{{% version include-if="main" %}}
+1. [Install kagent]({{< link path="setup/installation" >}}). {{< reuse "kagent-docs/snippets/grpcurl-reflection.md" >}}
+{{% /version %}}
 
 2. [Create your first agent]({{< link path="get-started/your-first-agent" >}}), then save the Agent's namespace and name to an environment variable, in the `<namespace>/<name>` form that the A2A `tenant` field takes. To list your Agents, run `kagent agent list`.
    ```bash

diff --git a/docs-site/assets/kagent-docs/snippets/grpcurl-reflection.md b/docs-site/assets/kagent-docs/snippets/grpcurl-reflection.md
@@ -0,0 +1 @@
+grpcurl uses gRPC server reflection to discover the controller's methods without a local copy of kagent's protocol buffer definitions. `kagent install` turns reflection on. A Helm installation must set `config.server.grpcReflection=true`. Reflection requires the same authentication as the other gRPC calls. In the default `insecure` [authentication mode]({{< link path="about/substrate-runtime/identity#controller-authentication-modes" >}}), grpcurl needs no credentials. When authentication is on, pass credentials on every grpcurl command, even one that only lists services, such as `-H "authorization: Bearer <token>"`.
diff --git a/docs-site/assets/kagent-docs/snippets/install-cli.md b/docs-site/assets/kagent-docs/snippets/install-cli.md
@@ -1,5 +1,7 @@
-Download the kagent CLI. The `--version` flag matches the CLI to the release that these docs cover.
+Download the kagent CLI.
 
 ```bash
-curl https://raw.githubusercontent.com/kagent-dev/kagent/refs/heads/main/scripts/get-kagent | bash -s -- --version v{{< reuse "kagent-docs/versions/kagent.md" >}}
+curl -sL https://kagent.dev/install | bash
 ```
+
+The script installs the newest kagent release. To install the release that these docs cover instead, run `curl -sL https://kagent.dev/install | bash -s -- --version v{{< reuse "kagent-docs/versions/kagent.md" >}}`.
diff --git a/docs-site/content/kagent/main/about/substrate-runtime/identity.md b/docs-site/content/kagent/main/about/substrate-runtime/identity.md
@@ -57,7 +57,7 @@ config:
         authority: prod-cluster
 ```
 
-The workload sends a ServiceAccount token whose audience is `kagent-invocation` as a bearer token in the `Authorization` header. A workload usually mounts the token as a projected volume. To test from a terminal, create a token with `kubectl`, port-forward the controller's port `8083`, and call the API. The `grpcurl` command relies on gRPC reflection, so your installation must set `config.server.grpcReflection=true`.
+The workload sends a ServiceAccount token whose audience is `kagent-invocation` as a bearer token in the `Authorization` header. A workload usually mounts the token as a projected volume. To test from a terminal, create a token with `kubectl`, port-forward the controller's port `8083`, and call the API. The `grpcurl` command relies on gRPC reflection, which `kagent install` turns on and a Helm installation turns on with `config.server.grpcReflection=true`. Reflection requires the same authentication as the other gRPC calls, and the `-H` flag sends the token on the reflection requests as well as on the call.
 
 ```bash
 kubectl create namespace ci-bots
@@ -181,7 +181,7 @@ actorJwt:
   audiences: [ticket-api, kagent-agent-info]
 ```
 
-The service sends the token that it received as a bearer token, with an empty request. In the following command, `$ACTOR_TOKEN` holds that token. The `grpcurl` command relies on gRPC reflection, so your installation must set `config.server.grpcReflection=true`. The `-rpc-header` flag keeps the token off the reflection requests.
+The service sends the token that it received as a bearer token, with an empty request. In the following command, `$ACTOR_TOKEN` holds that token. The `grpcurl` command relies on gRPC reflection, which `kagent install` turns on and a Helm installation turns on with `config.server.grpcReflection=true`. The `-rpc-header` flag sends the Actor token on the call only, so the reflection requests that grpcurl makes first carry no token. Reflection requires the same authentication as the other user calls. In the default `insecure` mode it needs no credentials. When authentication is on, also pass a user credential with `-reflect-header`, such as `-reflect-header "authorization: Bearer <token>"`.
 
 ```bash
 grpcurl -plaintext -rpc-header "Authorization: Bearer $ACTOR_TOKEN" -d '{}' \

diff --git a/docs-site/content/kagent/main/agents/agent-memory.md b/docs-site/content/kagent/main/agents/agent-memory.md
@@ -220,7 +220,7 @@ No CLI command manages memories, so these examples call the service with [grpcur
 
 Each call also takes the `agent_name` exactly as the memory table stores it. An incorrect name fails silently, so copy the value from the table instead of typing it by hand.
 
-1. Port-forward the controller's gRPC port, and confirm that your kagent installation sets `config.server.grpcReflection=true`.
+1. Port-forward the controller's gRPC port. {{< reuse "kagent-docs/snippets/grpcurl-reflection.md" >}}
    ```bash
    kubectl port-forward -n kagent svc/kagent-controller 8083:8083
    ```

diff --git a/docs-site/content/kagent/main/agents/scheduled-runs.md b/docs-site/content/kagent/main/agents/scheduled-runs.md
@@ -11,7 +11,7 @@ kagent stores schedules in its database, not as Kubernetes resources. You manage
 
 ## Before you begin
 
-1. [Install kagent]({{< link path="setup/installation" >}}). To call the API with grpcurl, set `config.server.grpcReflection=true`. grpcurl uses server reflection to find the `ScheduledRunService` methods.
+1. [Install kagent]({{< link path="setup/installation" >}}). If you call the `ScheduledRunService` API with grpcurl rather than the UI, note the following. {{< reuse "kagent-docs/snippets/grpcurl-reflection.md" >}}
 2. Create an Agent that answers a prompt, such as the one in [Your first agent]({{< link path="get-started/your-first-agent" >}}).
 
 ## Create a schedule in the UI

diff --git a/docs-site/content/kagent/main/examples/agents-via-mcp.md b/docs-site/content/kagent/main/examples/agents-via-mcp.md
@@ -23,7 +23,7 @@ The MCP server runs on the controller's HTTP port, so a default installation alr
 
 ## Before you begin
 
-1. [Install kagent]({{< link path="setup/installation" >}}), and confirm that your installation sets `config.server.grpcReflection=true`. Reflection lets a gRPC client discover the controller's methods without a local copy of kagent's protocol buffer definitions.
+1. [Install kagent]({{< link path="setup/installation" >}}). {{< reuse "kagent-docs/snippets/grpcurl-reflection.md" >}}
 
 2. [Create your first agent]({{< link path="get-started/your-first-agent" >}}), so that the cluster has an {{< gloss "Agent" >}}Agent{{< /gloss >}} to invoke.
 

diff --git a/docs-site/content/kagent/main/get-started/your-first-agent.md b/docs-site/content/kagent/main/get-started/your-first-agent.md
@@ -42,6 +42,9 @@ Three resources define a runnable agent: a Harness holds the runtime, an AgentTe
          location: s3://ate-snapshots/kagent/
    ```
 
+   > [!TIP]
+   > Your installation also comes with the `kagent-default`, `codex-default`, and `claude-default` Harnesses in the kagent namespace, for the kagent, Codex, and Claude runtimes. An Agent in the kagent namespace can name one of them in `spec.harnessRef` instead of a Harness of your own. `spec.harnessRef` is namespace-local, so an Agent in another namespace needs its own Harness. This guide creates its own Harness so that you can see each field, and because later guides build on it.
+
 2. Apply an `AgentTemplate`. The `modelConfig` field references the `default-model-config` {{< gloss "ModelConfig" >}}ModelConfig{{< /gloss >}} that was automatically created for the model provider API key that you provided during kagent installation.
    ```yaml
    apiVersion: api.kagent.dev/v1alpha3

diff --git a/docs-site/content/kagent/main/operations/debug.md b/docs-site/content/kagent/main/operations/debug.md
@@ -72,7 +72,7 @@ Compatible=False  Blocked: blocked by ResolvedRefs
 Ready=False  Blocked: blocked by ResolvedRefs
 ```
 
-A failed golden snapshot is not final. When Agent Substrate fails to build the golden snapshot, kagent deletes the failed ActorTemplate and rebuilds it after about 15 seconds, 1 minute, and 4 minutes, and then about every 10 minutes indefinitely. While a rebuild waits, `Ready` is `False` with the reason `ActorTemplateRetrying` and a message such as `golden build failed (GoldenActorCrashed), retry 1 at <time>`. The message omits Agent Substrate's full error, because that error can quote your configuration. Read the full error in the controller log. When a configuration fault causes the failure, kagent retries until you edit the Agent or the SandboxTemplate.
+A failed golden snapshot is not final. When Agent Substrate fails to build the golden snapshot, kagent deletes the failed ActorTemplate and rebuilds it after about 15 seconds, 1 minute, and 4 minutes, and then about every 10 minutes indefinitely. While a rebuild waits, `Ready` is `False` with the reason `ActorTemplateRetrying` and a message such as `golden build failed (GoldenActorCrashed), retry 1 at <time>`. When the build failed because a node could not pull an image, the message names the image, such as `golden build failed (GoldenActorCrashed): could not pull image ghcr.io/example/agent:v1, retry 1 at <time>`. Check that the image reference is correct and that the cluster can pull it. Otherwise, the message omits Agent Substrate's full error, because that error can quote your configuration. Read the full error in the controller log. When a configuration fault causes the failure, kagent retries until you edit the Agent or the SandboxTemplate.
 
 ```bash
 kubectl logs -n kagent deploy/kagent-controller | grep "golden build failed"

diff --git a/docs-site/content/kagent/main/operations/export-to-helm.md b/docs-site/content/kagent/main/operations/export-to-helm.md
@@ -15,7 +15,7 @@ The export contains only the Helm releases. `kagent install` also creates the Ag
 
 ## Before you begin
 
-1. Install kagent with the kagent CLI, as described in [Install with the CLI]({{< link path="setup/installation#install-kagent" >}}). Keep the CLI configuration file that passes Helm values to `kagent install`, and the values files that it references. The CLI reads the configuration file from one of the following locations:
+1. Install kagent with the kagent CLI, as described in [Install with the CLI]({{< link path="setup/installation#install-kagent" >}}). If you [passed your own Helm values]({{< link path="setup/installation#cli-helm-values" >}}), keep the CLI configuration file that passes Helm values to `kagent install`, and the values files that it references. The CLI reads the configuration file from one of the following locations:
    * The path that you passed with the `--config` flag, such as `kagent-config.yaml`.
    * When you omit `--config`, `$XDG_CONFIG_HOME/kagent/config.yaml` on Linux, or `~/.config/kagent/config.yaml` when `XDG_CONFIG_HOME` is not set. On macOS, `~/Library/Application Support/kagent/config.yaml`.
 

diff --git a/docs-site/content/kagent/main/operations/tune-agent-substrate.md b/docs-site/content/kagent/main/operations/tune-agent-substrate.md
@@ -11,7 +11,7 @@ The single Worker reports capacity for 1000 Actors, so a default pool serves man
 
 ## Before you begin
 
-1. [Install kagent]({{< link path="setup/installation" >}}), and confirm that your installation sets `config.server.grpcReflection=true`. Reflection lets a gRPC client discover the controller's methods without a local copy of kagent's protocol buffer definitions.
+1. [Install kagent]({{< link path="setup/installation" >}}). {{< reuse "kagent-docs/snippets/grpcurl-reflection.md" >}}
 
 2. Confirm that you have administrative access to the cluster, because this guide scales WorkerPools and reads cluster-scoped resources.
 

diff --git a/docs-site/content/kagent/main/operations/upgrade-from-0x.md b/docs-site/content/kagent/main/operations/upgrade-from-0x.md
@@ -66,7 +66,7 @@ Export your resources before you uninstall 0.10.x. Some resources convert to 1.0
 
 Install 1.0 against the empty database that you provisioned. kagent and Agent Substrate both store their state in that database, each with an owner login that applies migrations and a read/write login that serves runtime queries. `kagent install` normally creates a development database for both. When you pass `--skip-database-setup`, `kagent install` does not create the development database. The kagent and Agent Substrate charts then read the connection Secrets that you create in this section.
 
-Before you start, complete the [Before you begin]({{< link path="setup/installation#before-you-begin" >}}) steps of the installation guide. Those steps prepare a cluster at Kubernetes 1.37 or later and your provider API key. Then install the CLI tools in step 1 of [Install with the CLI]({{< link path="setup/installation#install-kagent" >}}).
+Before you start, complete the [Before you begin]({{< link path="setup/installation#before-you-begin" >}}) steps of the installation guide, which prepare a cluster at Kubernetes 1.37 or later and the `kubectl` and `helm` tools. Then set your provider API key and install the kagent CLI as described in [Install with the CLI]({{< link path="setup/installation#install-kagent" >}}), without running `kagent install` yet.
 
 1. Create the namespaces that contain the connection Secrets. If a namespace already exists, `kagent install` uses it.
    ```bash
@@ -129,7 +129,7 @@ Before you start, complete the [Before you begin]({{< link path="setup/installat
    | `database.postgres.ownerConnectionStringSecretRef.name` and `database.postgres.readWriteConnectionStringSecretRef.name` | Read the two connection strings from the Secrets that you created. The keys default to `ownerConnectionString` and `readWriteConnectionString`. |
    | `config.database.owner.role` and `config.database.readWrite.role` | The roles that the kagent setup script created. If you passed other role names to the script, set those names instead. |
    | `config.database.vectorEnabled` | Applies the pgvector migrations, which [long-term memory]({{< link path="agents/agent-memory" >}}) depends on. If your database does not have the pgvector extension installed, omit the value. |
-   | `config.server.grpcReflection` | Lets the guides that use `grpcurl` discover the controller API, as in the installation guide. |
+   | `config.server.grpcReflection` | Lets the guides that use `grpcurl` discover the controller API. `kagent install` enables it by default, so this value only keeps the setting explicit in the values file. |
 
 6. Save a CLI configuration file that references `kagent-values.yaml`. The `kagent db` commands read `database.vectorEnabled` from this file, not from the Helm values. Set `database.vectorEnabled` to match `config.database.vectorEnabled`. If you omitted `config.database.vectorEnabled`, omit `database.vectorEnabled` too.
    ```bash
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		grpcurl uses gRPC server reflection to discover the controller's methods without a local copy of kagent's protocol buffer definitions. `kagent install` turns reflection on. A Helm installation must set `config.server.grpcReflection=true`. Reflection requires the same authentication as the other gRPC calls. In the default `insecure` [authentication mode]({{< link path="about/substrate-runtime/identity#controller-authentication-modes" >}}), grpcurl needs no credentials. When authentication is on, pass credentials on every grpcurl command, even one that only lists services, such as `-H "authorization: Bearer <token>"`.