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 4, 2026 11:43pm 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