diff --git a/src/content/docs/reference/cli/index.mdx b/src/content/docs/reference/cli/index.mdx
index e6844f42..533655dc 100644
--- a/src/content/docs/reference/cli/index.mdx
+++ b/src/content/docs/reference/cli/index.mdx
@@ -231,7 +231,7 @@ oz agent run --prompt "set up a new Rust crate named warp-cli"
 * `--name <NAME>` (`-n`) — label the run for grouping and traceability.
 * `--share` — share the session with teammates (see [Collaboration](/reference/cli/#collaboration)).
 * `--profile <ID>` — use a specific agent profile (see [Using Agent Profiles](/reference/cli/#using-agent-profiles)).
-* `--model <MODEL_ID>` — override the default model (see [Model Choice](/agent-platform/inference/model-choice/)).
+* `--model <MODEL_ID>` — override the default model. Run `oz model list` to see the available IDs, or see [Model Choice](/agent-platform/inference/model-choice/).
 * `--skill <SPEC>` — use a skill as the base prompt (see [Using Skills](/reference/cli/#using-skills)).
 * `--mcp <SPEC>` — start one or more MCP servers before execution (UUID, JSON file path, or inline JSON). Can be repeated.
 * `--environment <ID>` (`-e`) — run in a specific cloud environment.
@@ -265,7 +265,7 @@ oz agent run-cloud \
 * `--name <NAME>` (`-n`) — label the run for grouping and traceability (see [Naming runs](/reference/cli/#naming-runs) below).
 * `--agent <UID>` — run as a saved [named agent](/platform/agents/), applying its configuration (skills, secrets, base model, and default environment) and attributing credit usage to it (see [Managing named agents](/reference/cli/#managing-named-agents) below).
 * `--mcp <SPEC>` — start one or more MCP servers before execution (UUID, JSON file path, or inline JSON). Can be repeated.
-* `--model <MODEL_ID>` — override the default model.
+* `--model <MODEL_ID>` — override the default model. With the default `oz` harness, use an ID from `oz model list`. With `--harness claude` or `--harness codex`, pass a harness-specific model ID instead (see [Choosing an execution harness](#choosing-an-execution-harness)).
 * `--skill <SPEC>` — use a skill from the environment's repository as the base prompt (see [Using Skills](/reference/cli/#using-skills)).
 * `--host <WORKER_ID>` — run on a specific self-hosted worker instead of Warp-hosted infrastructure.
 * `--attach <PATH>` — attach an image file to the agent query. Can be repeated (maximum 5).
@@ -274,9 +274,6 @@ oz agent run-cloud \
 * `--claude-auth-secret <NAME>` — name of the [Warp-managed secret](/platform/secrets/) that authenticates the Claude Code harness. Only valid with `--harness claude`. See [Third-party cloud agent authentication](/platform/harnesses/authentication/).
 * `--codex-auth-secret <NAME>` — name of the [Warp-managed secret](/platform/secrets/) that authenticates the Codex harness. Only valid with `--harness codex`. See [Third-party cloud agent authentication](/platform/harnesses/authentication/).
 * `--file <PATH>` (`-f`) — load run configuration from a YAML or JSON file.
-* `--harness <HARNESS>` — choose the [execution harness](/platform/harnesses/) for the run: `oz` (default, Warp's built-in agent infrastructure), `claude` (Claude Code), or `codex`.
-* `--claude-auth-secret <NAME>` — name of the [Warp-managed secret](/platform/harnesses/authentication/) that authenticates the Claude Code harness. Only valid with `--harness claude`.
-* `--codex-auth-secret <NAME>` — name of the [Warp-managed secret](/platform/harnesses/authentication/) that authenticates the Codex harness. Only valid with `--harness codex`.
 
 To run a third-party harness, first store the provider credential as a Warp-managed secret, then pass it with the matching flag:
 
@@ -348,6 +345,30 @@ oz agent run-cloud \
 
 Create the auth secret first with `oz secret create claude api-key <SECRET_NAME>` (or `oz secret create codex api-key <SECRET_NAME>` for Codex). See [Third-party cloud agent authentication](/platform/harnesses/authentication/) for the full setup.
 
+##### Selecting a model for a third-party harness
+
+`--model` accepts harness-specific model IDs. Warp passes the value straight through to the harness instead of resolving it against Warp's own model list, so use the identifier the harness expects:
+
+```sh
+# Claude Code model ID
+oz agent run-cloud \
+  --environment <ENVIRONMENT_ID> \
+  --harness claude \
+  --claude-auth-secret <SECRET_NAME> \
+  --model opus \
+  --prompt "review the latest PR"
+
+# Codex model ID
+oz agent run-cloud \
+  --environment <ENVIRONMENT_ID> \
+  --harness codex \
+  --codex-auth-secret <SECRET_NAME> \
+  --model gpt-5.5 \
+  --prompt "review the latest PR"
+```
+
+`oz model list` only reports models for the built-in `oz` harness. For the accepted values with `--harness claude` or `--harness codex`, consult that harness's own documentation. An unrecognized ID is rejected by the harness, not by Warp.
+
 ## Using agent profiles
 
 Agent profiles control what the agent can do, how it behaves, and where it can act. Use the `--profile` flag with `oz agent run` to apply a specific profile.