docs: Clarify harness identifiers (claude vs claude-code) and dedupe run-cloud flags

[hongyi-chen]

Summary

A user hit Task ... was created with the unknown harness, but --harness claude was requested after a GitHub-synced factory definition mixed the claude and claude-code spellings, and the agent editing the files concluded from the docs/schema that the two were interchangeable everywhere. The identifiers were documented inconsistently across pages, and nothing stated which spelling is canonical on which surface. The server now normalizes the alias before emitting CLI args (warp-server #16769), and this PR makes the docs unambiguous about the identifier strings.

Changes

src/content/docs/platform/harnesses/index.mdx

• Added a "Harness identifiers" section listing the exact strings per surface: API/SDK (oz, claude, codex), CLI --harness (same, plus claude-code as an alias for claude), and factory definition files (same, plus the alias).
• Pointed the "API and SDK" switching instructions at the new section.

src/content/docs/reference/cli/index.mdx

• Removed the duplicated --harness, --claude-auth-secret, and --codex-auth-secret bullets in the oz agent run-cloud key-flags list (each was documented twice with diverging wording).
• The merged --harness bullet now names the accepted values and the claude-code alias, and links to the harness identifiers section.

src/content/docs/factories/factory-as-code.mdx

• agentDefaults.harness: clarified that claude-code is an alias and that claude is the canonical identifier shared with the CLI and the Agent API.

src/content/docs/platform/harnesses/claude-code.mdx

• The API/SDK bullet now states the identifier is claude, not claude-code.

Content design plan

Audience and JTBD: An engineer or agent writing a harness value into a factory definition file, an oz agent run-cloud --harness flag, or an API agent config, who needs the exact accepted string.

Problem: claude and claude-code both appear across surfaces with no statement of which is canonical where; a GitHub-backed factory misconfiguration produced runtime "unknown harness" failures, and the CLI reference listed the harness flags twice.

Goals:

• The reader can look up the accepted harness identifiers for the API, the CLI, and factory files in one place.
• The reader knows claude is canonical and where claude-code is accepted as an alias.

Purpose and value: Prevents misconfigured harness strings from GitHub-synced definitions and scripts; no existing page listed identifiers per surface.

Content type: Reference — small identifier lookup added to the existing harnesses feature page, plus corrections to existing reference content.

Skill and template: Inline edits to existing pages; no new page.

High-impact scenarios:

• Covers: API harness.type, CLI --harness, factory file harness.type.
• Excludes: gemini/opencode (not generally available; factory-as-code already lists gemini where the schema accepts it) and internal orchestration tool-call labels, which users never type.

Unverified claims

None — all identifier and flag claims were verified against source: the harness enum and config names (warp-server:model/types/enums/agent_harness.go), the factory file schema generator and published JSON schema (warp-server:logic/factoryfile/schema/common.go, v1alpha1/common.schema.json), the public API enum (warp-server:public_api/openapi.yaml, Harness.type), the CLI value enum and claude-code alias (warp:crates/warp_cli/src/agent.rs), and the alias normalization fix (warp-server #16769).

Documentation risk

Risk: engineering-review-required
Rationale: Documents exact harness identifier strings and CLI flag values (claude vs claude-code) across API, CLI, and factory files; verified against warp-server enums/schema/OpenAPI and the warp CLI, but identifier claims are engineering-owned.
Source files consulted: warp-server:model/types/enums/agent_harness.go@6f30a16fc8b5, warp-server:logic/factoryfile/schema/common.go@6f30a16fc8b5, warp-server:public_api/openapi.yaml@6f30a16fc8b5, warp-server:logic/ai/ambient_agents/workers/common/task_utils.go@6f30a16fc8b5, warp:crates/warp_cli/src/agent.rs@5a6ded1e8413
Requested engineering reviewers: bnavetta, ianhodge
Engineering review status: pending
Docs override: none

Co-Authored-By: Warp agent@warp.dev

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Sep 8, 2026 5:21am UTC

[hongyi-chen]

This PR was generated with Warp.

Comment @warp-agent on this PR to send it follow-up work.

 

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• technical-accuracy (1)

Verdict

Request changes

[warp-for-oss]

@hongyi-chen

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[warp-for-oss]

Overview

This PR clarifies harness identifier spelling across the harness overview, Claude Code page, CLI reference, and factory-as-code docs while removing duplicated oz agent run-cloud flag bullets.

Concerns

• The new harness identifier section conflicts with the factory-as-code page by saying factory definition files accept only the shared identifiers plus the claude-code alias, while the same PR keeps gemini documented as a schema-validated factory value.
• The CLI --harness bullet now documents claude-code as an alias, but the adjacent --claude-auth-secret bullet still says it is only valid with --harness claude, leaving alias users with contradictory guidance.
• Security pass: no security-relevant code, auth, secret-handling, dependency, or runtime configuration changes were introduced.
• Spec check: no approved or repository spec context was provided, so there is no spec contract to enforce.
• Comment/test audit: no code comments or tests were added or changed.

Verdict

Found: 0 critical, 2 important, 0 suggestions

Request changes

Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[warp-for-oss]

⚠️ [IMPORTANT] This list says factory definition files accept only the shared identifiers plus the alias, but factory-as-code.mdx still documents gemini as schema-validated; include that factory-only value or readers get conflicting accepted-value guidance.

Suggested change

	Surfaces that take the harness as a string all use the same identifiers: `oz` for the Warp Agent, `claude` for Claude Code, and `codex` for Codex. Write `claude` for Claude Code — not `claude-code`:
	* **API and SDK** — the agent config's `harness.type` accepts `oz`, `claude`, or `codex`.
	* **CLI** — `oz agent run-cloud --harness` accepts the same identifiers, plus `claude-code` as an alias for `claude`.
	* **Factory definition files** — [`harness.type`](/factories/factory-as-code/#agentdefaultsharness) accepts the same identifiers, plus the `claude-code` alias.
	Surfaces that take the harness as a string use `oz` for the Warp Agent, `claude` for Claude Code, and `codex` for Codex. Write `claude` for Claude Code — not `claude-code` — unless the surface explicitly accepts that alias:
	* **API and SDK** — the agent config's `harness.type` accepts `oz`, `claude`, or `codex`.
	* **CLI** — `oz agent run-cloud --harness` accepts the same identifiers, plus `claude-code` as an alias for `claude`.
	* **Factory definition files** — [`harness.type`](/factories/factory-as-code/#agentdefaultsharness) accepts `oz`, `claude`, `codex`, or `gemini`, plus `claude-code` as an alias for `claude`.

[warp-factories]

Fixed — factory definition files now list gemini alongside the shared identifiers, matching factory-as-code.mdx.

[warp-for-oss]

⚠️ [IMPORTANT] Now that the previous bullet documents claude-code as an accepted alias, this auth-secret line should not say the flag is only valid with --harness claude.

Suggested change

	* `--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/).
	* `--claude-auth-secret <NAME>` — name of the [Warp-managed secret](/platform/secrets/) that authenticates the Claude Code harness. Use with `--harness claude` or the `--harness claude-code` alias. See [Third-party cloud agent authentication](/platform/harnesses/authentication/).

[warp-factories]

Fixed — the auth-secret bullet now notes it also applies with the --harness claude-code alias.

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• style-em-dash-in-procedural-text (1)
• sentence-density (1)

Verdict

Approve with nits

[warp-factories]

Reviewed this PR as part of an ad hoc request (linear.app/warpdotdev/issue/QUALITY-2036). The two outstanding "important" findings from the automated review were valid:

1. The new "Harness identifiers" section omitted gemini from the factory definition file's accepted values, contradicting factory-as-code.mdx.
2. The --claude-auth-secret bullet said it was "only valid with --harness claude", which became inconsistent once --harness claude-code was documented as an accepted alias on the preceding bullet.

Pushed a small follow-up commit applying the reviewer's suggested fixes for both. Local npm run build succeeds with the changes. No other issues found — looks good to merge once CI is green.