docs: add Codex and Claude Harness examples and a codex runtime-image conref

.github/workflows/update-ref-docs.yaml

@@ -432,25 +432,27 @@ jobs:
       # ---------------------------------------------------------------------
       # Runtime image conrefs.
       #
-      # versions/runtime-image.md and versions/runtime-image-claude.md hold a
-      # FULL digest-pinned reference (repository@sha256:...), not a version,
-      # because a Harness `workload.image` rejects a bare tag -- a revision has
-      # to be reproducible. Pages reuse the whole string, so the repository name
-      # is not hardcoded on any page either.
+      # versions/runtime-image.md, versions/runtime-image-claude.md and
+      # versions/runtime-image-codex.md hold a FULL digest-pinned reference
+      # (repository@sha256:...), not a version, because a Harness
+      # `workload.image` rejects a bare tag -- a revision has to be
+      # reproducible. Pages reuse the whole string, so the repository name is
+      # not hardcoded on any page either.
       #
       # A digest exists only once the image is pushed, so unlike every value
       # above this one is read from the REGISTRY rather than from a file in the
       # kagent tree. The tag to resolve comes from versions/kagent.md, not from
       # `git describe` on main: that conref names the release the docs describe,
       # so resolving against it is what keeps the image a reader pins consistent
       # with the chart version the install page tells them to install. It also
-      # means these two follow automatically whenever kagent.md is bumped by
+      # means these three follow automatically whenever kagent.md is bumped by
       # hand, which is the reason that one stays editorial.
       #
       # Image names are NOT the ones the kagent tree suggests. The kagent
       # runtime is golang-adk (values.yaml calls it `agentImage`); the claude
-      # runtime is claude-harness. The `claude-adk` and `codex-adk` strings in
-      # kagent are build stages, and nothing is published under those names.
+      # and codex runtimes are claude-harness and codex-harness. The
+      # `claude-adk` and `codex-adk` strings in kagent are build stages, and
+      # nothing is published under those names.
       #
       # 0.x needs no equivalent: it predates Harness and pins no runtime image.
       # ---------------------------------------------------------------------
@@ -486,7 +488,8 @@ jobs:
 
           # conref basename : GHCR repository
           RUNTIME_IMAGES="runtime-image:kagent-dev/kagent/golang-adk
-          runtime-image-claude:kagent-dev/kagent/claude-harness"
+          runtime-image-claude:kagent-dev/kagent/claude-harness
+          runtime-image-codex:kagent-dev/kagent/codex-harness"
 
           UNRESOLVED=""
           while IFS= read -r line; do
@@ -698,6 +701,11 @@ jobs:
             else
               echo "  runtime-image-claude.md: SKIPPED, unresolved digest. Left at $(cat "$VERSIONS_DIR/runtime-image-claude.md")"
             fi
+            if [ -n "${RUNTIME_IMAGE_CODEX:-}" ]; then
+              write_conref "$VERSIONS_DIR/runtime-image-codex.md" "$RUNTIME_IMAGE_CODEX"
+            else
+              echo "  runtime-image-codex.md: SKIPPED, unresolved digest. Left at $(cat "$VERSIONS_DIR/runtime-image-codex.md")"
+            fi
           fi
 
       # Three fragments of the PR body that exist only on a 1.x run. Built here
@@ -717,6 +725,7 @@ jobs:
               echo "| \`kagent-tools\` | \`${KAGENT_TOOLS_VERSION}\` | \`helm/kagent/Chart-template.yaml\` |"
               echo "| \`runtime-image\` | \`${RUNTIME_IMAGE:-unresolved}\` | GHCR, at \`${KAGENT_TAG}\` |"
               echo "| \`runtime-image-claude\` | \`${RUNTIME_IMAGE_CLAUDE:-unresolved}\` | GHCR, at \`${KAGENT_TAG}\` |"
+              echo "| \`runtime-image-codex\` | \`${RUNTIME_IMAGE_CODEX:-unresolved}\` | GHCR, at \`${KAGENT_TAG}\` |"
               echo "ROWS_EOF"
             } >> $GITHUB_ENV
           else

docs-site/assets/kagent-docs/versions/runtime-image-codex.md

@@ -0,0 +1 @@
+ghcr.io/kagent-dev/kagent/codex-harness@sha256:aef1e913671c65721af8003494afbeacc6c81e41309afbbb1e8d888e1868d8ce

docs-site/content/kagent/1.x/agents/agent-harness.md

@@ -87,6 +87,122 @@ Setting `memory` gives every agent on this Harness memory that persists across c
 
 Setting `compaction` summarizes older session events so an agent's prompt stays bounded as a conversation grows. For the two strategies and the rules the API server enforces, see [Context management]({{< link path="agents/context-management" >}}).
 
+### Codex and Claude examples
+
+A `codex` or `claude` Harness has the same shape as a `kagent` one, and differs in the runtime block, the image, and the ModelConfigs that it accepts. For the providers and settings that each runtime accepts, see [Model provider support](#model-provider-support), and for the limits each one places on an AgentTemplate, see [Tool and skill support](#tool-and-skill-support).
+
+{{< tabs >}}
+{{% tab name="Codex" %}}
+The ModelConfig reads its API key from the `kagent-openai` Secret that the [OpenAI]({{< link path="setup/model-providers/openai#create-the-modelconfig" >}}) guide creates. The key must be entitled to the model that you name. A key without access to it fails the turn with `Codex execution failed`.
+```yaml
+kubectl apply -f - <<EOF
+apiVersion: api.kagent.dev/v1alpha3
+kind: ModelConfig
+metadata:
+  name: codex-model-config
+  namespace: kagent
+spec:
+  apiKeySecret: kagent-openai
+  apiKeySecretKey: OPENAI_API_KEY
+  model: gpt-5.2-codex
+  provider: OpenAI
+  openAI:
+    apiFormat: responses
+---
+apiVersion: api.kagent.dev/v1alpha3
+kind: Harness
+metadata:
+  name: codex-harness
+  namespace: kagent
+spec:
+  codex: {}
+  workload:
+    image: {{< reuse "kagent-docs/versions/runtime-image-codex.md" >}}
+  substrate:
+    workerPoolRef:
+      name: kagent-default
+    snapshotPolicy:
+      location: s3://ate-snapshots/kagent/
+---
+apiVersion: api.kagent.dev/v1alpha3
+kind: AgentTemplate
+metadata:
+  name: codex-template
+  namespace: kagent
+spec:
+  modelConfig:
+    name: codex-model-config
+  systemPrompt: You are a concise, helpful coding assistant.
+---
+apiVersion: api.kagent.dev/v1alpha3
+kind: Agent
+metadata:
+  name: codex-agent
+  namespace: kagent
+spec:
+  templateRef:
+    name: codex-template
+  harnessRef:
+    name: codex-harness
+EOF
+```
+{{% /tab %}}
+{{% tab name="Claude" %}}
+The ModelConfig reads its API key from the `kagent-anthropic` Secret that the [Anthropic]({{< link path="setup/model-providers/anthropic#create-the-modelconfig" >}}) guide creates.
+```yaml
+kubectl apply -f - <<EOF
+apiVersion: api.kagent.dev/v1alpha3
+kind: ModelConfig
+metadata:
+  name: claude-model-config
+  namespace: kagent
+spec:
+  apiKeySecret: kagent-anthropic
+  apiKeySecretKey: ANTHROPIC_API_KEY
+  model: claude-sonnet-5
+  provider: Anthropic
+  anthropic: {}
+---
+apiVersion: api.kagent.dev/v1alpha3
+kind: Harness
+metadata:
+  name: claude-harness
+  namespace: kagent
+spec:
+  claude: {}
+  workload:
+    image: {{< reuse "kagent-docs/versions/runtime-image-claude.md" >}}
+  substrate:
+    workerPoolRef:
+      name: kagent-default
+    snapshotPolicy:
+      location: s3://ate-snapshots/kagent/
+---
+apiVersion: api.kagent.dev/v1alpha3
+kind: AgentTemplate
+metadata:
+  name: claude-template
+  namespace: kagent
+spec:
+  modelConfig:
+    name: claude-model-config
+  systemPrompt: You are a concise, helpful coding assistant.
+---
+apiVersion: api.kagent.dev/v1alpha3
+kind: Agent
+metadata:
+  name: claude-agent
+  namespace: kagent
+spec:
+  templateRef:
+    name: claude-template
+  harnessRef:
+    name: claude-harness
+EOF
+```
+{{% /tab %}}
+{{< /tabs >}}
+
 ## Model provider support
 
 The runtime that a Harness selects decides which ModelConfig an Agent that runs on it can use. This table covers every value that the ModelConfig `provider` field accepts, including the four that kagent 1.0 rejects on every runtime.