docs: expand Factory agents third-party harness setup (DOCFAC-1787856600)

.agents/references/terminology.md

@@ -255,11 +255,20 @@ Not every "Oz" in the docs is stale. These are deliberate and correct until
 
 - **Agent API** — The HTTP API for triggering and inspecting Platform runs programmatically.
 
+- **Auth** — The agent settings field for choosing or creating the credential (a team-owned secret) a harness uses to authenticate with its provider, matched to that harness's supported credential types (Anthropic keys for Claude Code, an OpenAI key for Codex).
+  *Usage note:* Capitalize as **Auth** when referring to the settings field name.
+
+- **Harness** — The agent runtime that executes a cloud agent's work, such as Warp Agent, Claude Code, or Codex. Configurable per agent, independent of the platform features (triggers, environments, secrets, observability) around the run.
+  *Usage note:* Capitalize as **Harness** when referring to the settings field name; lowercase "harness" as a generic noun.
+
 - **Host** — Where a task executes (Warp-hosted or customer-hosted).
 
 - **Integration** / **Integrations** — Configured connections between Warp and external tools (Slack, Linear, GitHub Actions) that trigger runs and post results back.
   *Usage note:* Use for the configured connection, not "plugin."
 
+- **Model** — The agent settings field for choosing which model a harness runs. Options come from the selected harness's own catalog, not Warp's, so changing harness clears the model and auth selections.
+  *Usage note:* Capitalize as **Model** when referring to the settings field name.
+
 - **Outputs** — What a run produces (PRs, messages, reports, transcripts).
 
 - **Run** — The tracked unit of work for a run, including status and outputs.
@@ -392,6 +401,8 @@ Docs match the screen; the fix belongs in the app.
 
 ## External product names
 
+- **Codex** — OpenAI's coding agent, available in Warp as a local CLI agent and as a third-party cloud harness in the Automation Platform.
+  *Usage note:* Capitalize as the product name, matching OpenAI's own branding.
 - **GitHub Actions** — capitalize "GitHub"
 - **GitHub App** — GitHub's installation/auth mechanism used for repo access in integrations
 - **Linear** — capitalize

.agents/skills/draft_procedural/SKILL.md

@@ -24,6 +24,8 @@ See "Descriptions by content type" under Frontmatter in `AGENTS.md` for the full
 These rules are specific to procedural pages (from the "Drafting by content type" section of `AGENTS.md`):
 
 - **Keep steps focused, not artificially atomic.** Aim for one primary action per step, but group tightly related actions together when they share the same UI context. Up to ~3 related actions per step is acceptable.
+- **Move reference detail out of the step into a `:::note`.** When a step's supporting detail is a list of facts (accepted credential types, valid formats) rather than an instruction, keep the step to its one action and put the list in a `:::note` immediately after it.
+- **Orient within the step, not just on first mention.** Name the field, dropdown, or location the action happens in before naming the action itself ("In the 'Harness' dropdown, select **Claude Code**", not "Choose **Claude Code** in the **Harness** field"). A step should stand on its own for a reader who lands on it directly, not rely on referring back to an earlier section.
 - **Motivate steps before giving instructions.** Briefly explain WHY before HOW, especially for setup steps.
 - Include expected outcomes after key steps so the reader can confirm they're on track.
 - Test all instructions for accuracy.

AGENTS.md

@@ -41,6 +41,8 @@ Cut sentences that narrate the page, restate what the reader just read, or expla
   - ❌ "The container is destroyed after each run. This process ensures every run starts from the same baseline, making results reproducible and debugging straightforward."
 - **No recap lines** - Don't end a section by summarizing it ("In practice: triggers create tasks; tasks produce outputs.").
 - **Say it once** - Don't repeat a caveat or definition across multiple sections of the same page. Put it where it matters most. The same goes for sibling pages: boilerplate like validation steps or shared prerequisites lives once on the parent or reference page, linked from the rest.
+  - ✅ State a plan-tier requirement once in a `:::note` near the top of the section, then let a later procedure that depends on it link back rather than restating it.
+  - ❌ Repeating the same "requires a Build plan or higher" caveat both in a section-level note and again inside a numbered step further down the page.
 
 #### Words to avoid
 These words are the strongest tell of an AI-generated draft and rarely add meaning. Replace them with the specific fact they're hiding, or delete them.
@@ -436,18 +438,21 @@ Keyboard keys and shortcuts use backticks. Use `+` as the separator between keys
 - ❌ **System Settings** > **Privacy & Security** > **Local Network** (macOS path missing the Apple icon — `U+F8FF` must appear before the first `>`)
 
 ### UI elements
-- Use bold for interactive UI elements (e.g., buttons, toggles, dropdowns)
+- Use bold for interactive UI elements (e.g., buttons, toggles, dropdowns, and the option you select from one)
 - Describe UI elements by name, not just appearance or location. Prefer "In the sidebar, click **Platform**" over "Click the button on the left."
 - Format checkbox names in bold. Omit the word "checkbox." Use "select" or "deselect," not "check" or "uncheck."
+- Use quotation marks, not bold, for a field or label name that is not itself clickable. The interactive control next to it (the dropdown, the input, the option you choose from it) still gets bold.
 
 **Use:**
 - ✅ Click your profile photo in the top-right corner, then click **Settings**.
 - ✅ In the sidebar, click **Platform**.
+- ✅ In the "Harness" dropdown, select **Claude Code** or **Codex**. ("Harness" labels the field but isn't itself clickable; the dropdown and its options are)
 
 **Don't use:**
 - ❌ In the API Keys section, click `+ Create API Key`.
 - ❌ In the API Keys section, click `+ Create API Key`. (use bold, not backticks)
 - ❌ Click `Create key`. (use bold, not backticks)
+- ❌ Choose **Claude Code** or **Codex** in the **Harness** field. (the field label isn't interactive, so it shouldn't be bold)
 
 #### Verbs for UI interactions
 Use consistent verbs that match the type of UI element:
@@ -548,9 +553,15 @@ These rules apply regardless of content type:
 - **Keep steps focused, not artificially atomic.** Aim for one primary action per step, but group tightly related actions together when they share the same UI context and doing so keeps the procedure at a readable length. Up to ~3 related actions per step is acceptable. Use judgment: a simple task shouldn't require 10+ steps, but a single step shouldn't be a mini-procedure either.
   - Acceptable groupings: actions on the same form (entering a name and choosing an expiration date), a click that reveals the next target (clicking to expand a section, then clicking the revealed item), or a short natural sequence within the same UI area.
   - Avoid grouping actions that span different areas of the UI or that would make a step hard to scan at a glance.
+  - **Move reference detail out of the step into a `:::note`.** When a step's supporting detail is a list of facts a reader might check rather than an instruction (accepted credential types, valid formats), keep the step to its one action and put the list in a `:::note` immediately after it.
+    - ✅ A step reading "In the **Auth** field, choose a compatible, team-owned secret from the list or click **New auth secret** to create one," followed by a `:::note` listing which credential type each option accepts.
+    - ❌ Folding the full list of accepted credential types into the same sentence as the instruction, so the action is buried in reference detail.
 - **Motivate steps before giving instructions.** Briefly explain WHY before HOW, especially for setup steps. A single sentence of motivation prevents the reader from wondering "why am I doing this?"
   - ✅ "Export your API key so the CLI can authenticate your requests automatically."
   - ❌ "Export your API key as an environment variable." (why?)
+- **Orient within the step, not just on first mention.** The page-level rule above ("Orient the reader before UI, CLI, or URL instructions") also applies inside a single step: name the field, dropdown, or location the action happens in before naming the action itself. Don't rely on referring the reader back to an earlier section instead — a step should stand on its own for a reader who lands on it directly.
+  - ✅ "In the 'Harness' dropdown, select **Claude Code** or **Codex**."
+  - ❌ "Choose **Claude Code** or **Codex** in the **Harness** field." (names the action before the location)
 - Include expected outcomes after key steps so the reader can confirm they're on track.
 - Test all instructions for accuracy.
 - Provide troubleshooting for common failure points.

src/content/docs/factories/factory-agents.mdx

@@ -63,21 +63,25 @@ Every default agent comes with GitHub skills, and the foreman also comes with a
 
 ## Configure agent behavior
 
-1. In the [factory dashboard](/factories/factory-dashboard/), select your factory and click **Agents** in the sidebar.
+1. From the [factory dashboard](/factories/factory-dashboard/) sidebar, select your factory and click **Agents**.
 
    <figure style={{ maxWidth: "563px" }}>
    ![The Agents page in the factory dashboard, listing a foreman agent and its four default agents: triage, spec, implement, and review.](../../../assets/factories/factory-agents-list.png)
    <figcaption>The Agents page lists a factory's foreman and default agents.</figcaption>
    </figure>
 
-2. Click an agent to open its settings, where you can change its description, model, runner, host, [MCP servers](/platform/mcp/), [secrets](/platform/secrets/), and instructions.
+2. Click an agent to open its settings page. From here, you can edit the agent description, harness, model, runner, host, [MCP servers](/platform/mcp/), [secrets](/platform/secrets/), and instructions.
 
    <figure style={{ maxWidth: "563px" }}>
    ![An agent's settings page, showing its description, MCPs, secrets, harness, model, runner, and host fields.](../../../assets/factories/factory-agent-settings.png)
    <figcaption>An agent's settings page, where you configure its model, harness, runner, and host.</figcaption>
    </figure>
 
-You can also manage the whole factory as version-controlled code, with [factory definition files](/factories/factory-as-code/) in a Git repository. A few agent settings, such as harness and credential strategy, can only be set in the files. See [where the definition lives](/factories/factory-as-code/#where-the-definition-lives) for how Warp-managed and GitHub-backed factories differ in what you can edit from the factory dashboard.
+You can also manage the factory as version-controlled code with [factory definition files](/factories/factory-as-code/) in a Git repository. A factory's settings live in one of two places:
+* A **Warp-managed factory** lets you edit everything, including harness, auth, and credential strategy, from the dashboard.
+* A **GitHub-backed factory** keeps those settings in its definition files. The dashboard shows them read-only, and you edit the files to make changes.
+
+For more information about the two locations, see [where the definition lives](/factories/factory-as-code/#where-the-definition-lives).
 
 Factory setup doesn't choose models for you. To change the model an agent uses, edit that agent.
 
@@ -86,7 +90,7 @@ Factory setup doesn't choose models for you. To change the model an agent uses,
 Each agent can run on its own model and harness. Supported harnesses include the Warp Agent harness, Claude Code, and Codex, and any agent can use any of them. A foreman running on Claude Code or Codex can still dispatch the factory's other agents, and the runs it starts are still tracked as its children.
 
 :::note
-Third-party harnesses require a Build plan or higher; on the Free plan every agent runs on the Warp Agent harness. See [harnesses](/platform/harnesses/#plan-requirements).
+Third-party harnesses require a Build plan or higher; on the Free plan every agent runs on the Warp Agent harness. See [Warp pricing](https://www.warp.dev/pricing) for what each plan includes.
 :::
 
 Default model IDs change over time, so choose based on what each agent has to do well:
@@ -99,7 +103,31 @@ Default model IDs change over time, so choose based on what each agent has to do
 | Implement | Coding strength, with a harness that fits your repositories and toolchain |
 | Review | A different model or harness from the implement agent, so the two don't share blind spots |
 
-See [model choice for agents](/agents/inference/model-choice/) and [harnesses for cloud agents](/platform/harnesses/) for available options. For a definition that gives each agent its own harness, see [`03-multi-harness`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/03-multi-harness).
+See [model choice for agents](/agents/inference/model-choice/) and [harnesses for cloud agents](/platform/harnesses/) for available options.
+
+### Configuring a third-party harness
+
+Change an agent's harness to Claude Code or Codex to run it with that provider's own coding tool instead of the Warp Agent.
+
+1. From the [factory dashboard](/factories/factory-dashboard/) sidebar, select your factory and click **Agents**.
+2. Click an agent to open its settings page. In the "Harness" dropdown, select **Claude Code** or **Codex**.
+3. In the **Auth** field, choose a compatible, team-owned secret from the list or click **New auth secret** to create one.
+
+   <figure style={{ maxWidth: "563px" }}>
+   ![An agent's settings page with the Harness dropdown set to Claude Code and the Auth field's dropdown open, showing a team-owned secret and the option to create a new one.](../../../assets/factories/factory-agent-auth-secret.png)
+   <figcaption>The Auth field's dropdown, showing a team-owned secret and the option to add a new one.</figcaption>
+   </figure>
+
+   :::note
+   * Claude Code accepts an Anthropic API key, Anthropic Bedrock API key, or Anthropic Bedrock access key.
+   * Codex accepts an OpenAI API key.
+
+   See [connecting Claude Code credentials](/platform/harnesses/authentication/#connecting-claude-code-credentials) and [connecting Codex credentials](/platform/harnesses/authentication/#connecting-codex-credentials) for how to obtain each key.
+   :::
+4. Choose a **Model** from that harness's own catalog.
+5. In the top-right corner, click **Save**.
+
+With a Warp-managed factory, you can edit harness, auth, and model from the dashboard. A GitHub-backed factory sets them through [`agentDefaults.harness` or a per-agent `harness` override](/factories/factory-as-code/#agentdefaultsharness) in the definition files. For an example, see [`03-multi-harness`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/03-multi-harness).
 
 ## Add custom agents and automations
 

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

@@ -181,7 +181,7 @@ harness:
 
 For a third-party harness, `auth` sets where credentials come from: `source: managedSecret` reads the [managed secret](/platform/secrets/) named by `secretName`, and `source: workerEnvironment` reads them from your self-hosted worker's environment (and requires a self-hosted `workerHost`). The `oz` harness supplies its own credentials and takes no `auth` or `reasoningLevel`.
 
-For a definition that runs a different harness per agent, with managed-secret auth for Claude Code and Codex, see [`03-multi-harness`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/03-multi-harness).
+For a definition that runs a different harness per agent, with managed-secret auth for Claude Code and Codex, see [`03-multi-harness`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/03-multi-harness). To configure the same third-party harness from the dashboard instead, see [configuring a third-party harness](/factories/factory-agents/#configuring-a-third-party-harness).
 
 ### `agentDefaults.runner`
 

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

@@ -10,7 +10,7 @@ import { VARS } from '@data/vars';
 
 Third-party cloud agent authentication in the {VARS.WARP_AUTOMATION_PLATFORM} stores provider credentials for cloud runs as Warp-managed secrets. Third-party cloud agents, like [Claude Code](#connecting-claude-code-credentials) and [Codex](#connecting-codex-credentials), call their providers directly, so set up an Anthropic or OpenAI credential once before launching a third-party harness.
 
-Auth secrets can be scoped to a **team** (available to all teammates' runs) or **personal** (only your own runs), like any other Warp-managed secret.
+Auth secrets can be scoped to a **team** (available to all teammates' runs) or **personal** (only your own runs), like any other Warp-managed secret. A [factory agent](/factories/factory-agents/#configuring-a-third-party-harness) can only select team-scoped secrets, since a factory's runs aren't tied to one person. Personal secrets remain available when you start an ad hoc cloud run.
 
 :::note
 [Bring Your Own Key (BYOK)](/agents/inference/bring-your-own-api-key/) configured in the Warp desktop app applies to local agent runs only. Cloud runs of Claude Code and Codex always use Warp-managed secrets.

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

@@ -54,3 +54,4 @@ For setup steps, see [Connecting Claude Code credentials](/platform/harnesses/au
 * [Warp Agent with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/warp-agent/) — the {VARS.WARP_AUTOMATION_PLATFORM}'s default harness, the only one that can orchestrate Claude Code subagents.
 * [Codex with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/codex/) — Codex as a cloud harness.
 * [Claude Code in Warp](/agents/cli-agents/claude-code/) — Claude Code in your local Warp terminal.
+* [Factory agents](/factories/factory-agents/#configuring-a-third-party-harness) — configure Claude Code as a factory agent's harness.