[backport] feat: improve install and first-agent onboarding

.github/workflows/ci.yaml

@@ -514,6 +514,9 @@ jobs:
         # Validate packaged runtime defaults without accessing an image registry.
         run: bash scripts/package-release-charts_test.sh
 
+      - name: Test CLI install script
+        run: bash scripts/get-kagent_test.sh
+
       - name: Run helm unit tests
         run: |
           helm unittest helm/kagent

.github/workflows/tag.yaml

@@ -7,6 +7,11 @@ on:
         description: 'Release tag to create (v prefix required, e.g. v0.1.0)'
         required: true
         type: string
+      latest:
+        description: 'Mark as GitHub latest, the release the CLI install script installs. Clear for patches to an older line.'
+        required: true
+        type: boolean
+        default: true
 
 concurrency:
   group: release
@@ -173,6 +178,10 @@ jobs:
         tag_name: ${{ needs.setup.outputs.tag }}
         target_commitish: ${{ github.sha }}
         generate_release_notes: true
+        # GitHub cannot mark a prerelease latest, so a suffixed tag (v1.0.0-rc.1)
+        # is a prerelease only when it is not released as latest.
+        prerelease: ${{ !inputs.latest && contains(inputs.version, '-') }}
+        make_latest: ${{ inputs.latest }}
         files: |
           go/core/bin/kagent-*
           dist/kagent-*.tgz

docs/architecture/configuration-and-compilation.md

@@ -65,6 +65,25 @@ new revision; create a new Session to use it. A2A task events remain streamable
 when model streaming is disabled. This setting does not configure
 the Codex or Claude harnesses.
 
+### Default Harnesses
+
+`kagent install` creates the release WorkerPool and three Harnesses in the
+release namespace: `kagent-default`, `codex-default`, and `claude-default`. Each
+selects its runtime, references the release WorkerPool, uses the snapshot
+location of Substrate's bundled object store, and omits `workload` so the release
+image is selected. Agents in that namespace can reference them without
+platform-specific values. They are ordinary Harnesses owned by the Helm release;
+the controller does not create or special-case them.
+
+The chart renders them only when `harnesses.enabled` is true. Its values
+choose the snapshot location and disable individual runtimes. Because
+`harnessRef` is namespace-local, Agents in other namespaces still need a Harness
+in their own namespace.
+
+The chart's default OpenAI ModelConfig sets `openAI.apiFormat: responses`. Codex
+requires the Responses API, and the kagent runtime supports it, so one default
+model serves both default Harnesses.
+
 ### Harness images and workload overrides
 
 For built-in kagent, Claude, and Codex Harnesses, the whole `workload` block is
@@ -298,6 +317,10 @@ A golden-snapshot failure is retried instead: the controller deletes the failed
 ActorTemplate and recreates it on the persisted schedule described in
 [Sandboxes](sandboxes.md#configuration-and-preparation), reporting `Ready=False`
 with reason `ActorTemplateRetrying` and only the failure reason in its message.
+The one allowlisted detail is an image pull failure for an image that the
+ActorTemplate itself names: the message then adds `could not pull image <ref>`.
+The reference comes from the template spec, never from the backend text, so
+configuration quoted in an error cannot reach status.
 
 ActorTemplate construction checks the size of each emitted environment value
 against Substrate's 32,768-character limit. Configuration and Agent Card
@@ -428,10 +451,11 @@ spec:
         name: default-model-config
       systemPrompt: You are a helpful assistant.
   harnessRef:
-    name: kagent
+    name: kagent-default
 ```
 
-The referenced ModelConfig and Harness must already exist.
+The referenced ModelConfig and Harness must already exist. `kagent install`
+creates both `default-model-config` and `kagent-default`.
 
 To reuse an existing AgentTemplate, replace the inline template with its reference:
 
@@ -441,7 +465,7 @@ spec:
     ref:
       name: shared-context
   harnessRef:
-    name: kagent
+    name: kagent-default
 ```
 
 Template behavior may be inline or referenced. The Harness is always referenced;

docs/architecture/installation.md

@@ -8,6 +8,8 @@ Installation has two phases. Planning resolves chart inputs and the controller s
 
 The plan installs CRDs before prerequisites, pod certificates, PostgreSQL, Substrate, and kagent. Chart settings and additional database setup are explicit inputs. Command execution and Kubernetes access are injected so tests can exercise the workflow without external services.
 
+The kagent release creates the Substrate WorkerPool and enables the chart's default Harnesses (`kagent-default`, `codex-default`, `claude-default`) on that pool, so a fresh install can run Agents without a hand-written Harness. Operator values files and `--set` overrides can disable them. See [Default Harnesses](configuration-and-compilation.md#default-harnesses).
+
 Model API keys reach Helm through temporary values files with `0600` permissions in private directories. The command runner removes them after each invocation and omits failed-command output that could contain credentials. These files override configured values files while caller `--set` overrides retain their priority. Custom runners must honor `Command.SecretValues` with the same protections. Credentials still become part of Helm release data and Kubernetes Secrets.
 
 Uninstall removes resources in the order needed for controllers to finish cleanup. It preserves external databases and the kagent namespace, and it tolerates resources removed by an earlier attempt. A namespace mismatch stops cleanup before deletion.

docs/architecture/process-configuration.md

@@ -68,6 +68,14 @@ Installation passes embedded defaults before configured chart values files.
 Files are applied in order, with the last file winning. Provider credentials
 continue to use the provider SDK environment interface.
 
+`kagent install --provider` overrides `install.defaultModelProvider` for one
+install; the protovalidate `in` rule on that field defines the accepted names.
+After a successful install the CLI prints next steps.
+
+`kagent version --client` prints only the CLI build without connecting to the
+controller. The `get-kagent` install script uses it to skip reinstalling a
+matching version.
+
 ## Controller
 
 The controller reads `/etc/kagent/controller.yaml`, or the file selected by

docs/architecture/sandboxes.md

@@ -115,10 +115,12 @@ computes the retry time from them, and the jitter comes from the failed
 template's UID, so a controller restart keeps the schedule. While a retry waits,
 `Ready` is `False` with reason `ActorTemplateRetrying`, and the message names
 the retry number, its time and the failure reason. Substrate's full error is
-logged by the controller, not copied into status, because it can quote
-configuration. While the rebuild is pending, the
-`Preparing` message names the retry number. A successful build resets the
-count. The 1-second poll wakes a waiting retry once its retry time passes;
+not copied into status, because it can quote configuration. The only detail
+added to the reason is `could not pull image <ref>` when the failure is a pull
+of an image that the template's own spec names. The controller takes that
+reference from the spec, not from the error text. It logs the full error at
+WARN once per failed attempt. While the rebuild is pending, the `Preparing`
+message names the retry number. A successful build resets the count. The 1-second poll wakes a waiting retry once its retry time passes;
 after a failed delete, queue backoff wakes it instead.
 
 Sandbox execution is enabled by default. Lifecycle calls run on the serving API