From 0433204fe67c7c197730dcc6c951e7c401bfc492 Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Wed, 16 Sep 2026 20:51:47 +0000 Subject: [PATCH 1/4] docs: cover published Factory schema fields Co-Authored-By: Oz --- .../references/docs-worthiness-criteria.md | 5 +- .../references/changelog_decisions.md | 4 +- .../docs/factories/factory-as-code.mdx | 52 +++++++++++++++++-- 3 files changed, 53 insertions(+), 8 deletions(-) diff --git a/.agents/references/docs-worthiness-criteria.md b/.agents/references/docs-worthiness-criteria.md index a495cef37..0212f09d8 100644 --- a/.agents/references/docs-worthiness-criteria.md +++ b/.agents/references/docs-worthiness-criteria.md @@ -20,6 +20,8 @@ These criteria govern the **weekly release stream** — changes that reached use Major launches (Warp Factories, for example) are planned in advance and documented by the docs team on a proactive, human-led path. They do not run through these gates. If you encounter a change that is clearly part of an announced launch, defer it rather than gating it. +The Factory definition reference is exhaustive. A key in the production Factory schema registry has passed Gate 0 and must be covered there. A prior `deferred` ledger row cannot suppress a key after publication. + ### How much applies depends on who is asking **Automated runs apply the full gate.** A scheduled agent has no context beyond what it can read, and unattended drafting at scale is what this reference exists to control. Default to no docs; make the change earn the page. @@ -149,6 +151,8 @@ Drawn from the `v0.2026.07.29.09.05.stable_02` changelog. These calibrate the bo **Agent execution profiles configurable from settings files** ([#14418](https://github.com/warpdotdev/warp/pull/14418)) — **Gate 1, update existing page.** Named settings-file configuration, previously unavailable to all users. +**`agentDefaults.computerUseModel`** (docs PR [#754](https://github.com/warpdotdev/docs/pull/754)) — **Gate 0 and Gate 1, update existing reference.** The key appears in the production Factory schema registry, which is the release gate for the exhaustive Factory definition reference. The older deferred verdict from docs PR #581 stopped applying when publication cleared Gate 0. + **Drag and drop image files into an active CLI agent session** ([#9553](https://github.com/warpdotdev/warp/pull/9553)) — **Gate 4, update existing page.** The job — attaching a screenshot to a Claude Code session — was not possible before, not merely slower. There is no knob, so Gate 1 does not fire; nothing fails, so Gate 2 does not; behavior the reader relied on did not change, so Gate 3 does not. Checked for an affordance and found none: no Command Palette entry, no menu item, no toolbar control, no hint in the session UI. A reader who does not already know will never try it. One sentence on the CLI agent page; the Gate 4 cap rules out a new page. ### Fails @@ -163,7 +167,6 @@ Drawn from the `v0.2026.07.29.09.05.stable_02` changelog. These calibrate the bo **MCP tool confirmations show the tool and source server** ([#14298](https://github.com/warpdotdev/warp/pull/14298)) — **Disqualified: small and intuitive.** The confirmation dialog now shows more context. A reader encountering it understands it immediately. -**`agentDefaults.computerUseModel`** (docs PR [#581](https://github.com/warpdotdev/docs/pull/581)) — **Gate 0 failure: deferred, not documented.** This is the regression case. A drafting agent wrote the page and labeled it "(unreleased feature)" in the PR title, which is the gate failing out loud. An unreleased setting key is a real knob and would pass Gate 1 — but Gate 0 comes first and is a hard prerequisite. Defer with the blocking reason and re-surface it when the feature ships. ## Related references diff --git a/.agents/skills/missing_docs/references/changelog_decisions.md b/.agents/skills/missing_docs/references/changelog_decisions.md index d9d0ec5d6..3327fdc2d 100644 --- a/.agents/skills/missing_docs/references/changelog_decisions.md +++ b/.agents/skills/missing_docs/references/changelog_decisions.md @@ -152,7 +152,7 @@ Newest first. One row per PR number — usually a `warpdotdev/warp` changelog it | POST /factory/{uid}/runs | 2026-08-25 | deferred | Gate 0 | New public_api route in warp-server. Sibling factory routes are mapped internal; released public OpenAPI (`developers/agent-api-openapi.yaml`) has zero `/factory` paths. EA docs already describe dispatch on `factories/factory-api.mdx`. Map `-> internal`; re-check when factory routes are published via sync-openapi-spec. | | POST /factory/automations/{id}/run | 2026-08-25 | deferred | Gate 0 | Manual run endpoint for factory automations (`RunFactoryAutomationHandler`). Same Gate 0 boundary as other factory automations routes already mapped `-> internal`. Not in released OpenAPI. Re-check with factory API publish. | | [docs#582](https://github.com/warpdotdev/docs/pull/582) | 2026-08-20 | yes | Gate 3 | Factory Dashboard metric definitions (APP-5546). The counting rules are non-obvious and currently live only in hover tooltips: the By-model view caps at eight and folds the rest into Other, there is an Unknown bucket, and opened/merged pull request counts can legitimately disagree. A reader reading the dashboard without them draws wrong conclusions. New reference page justified — no existing page carries per-metric detail. | -| [docs#581](https://github.com/warpdotdev/docs/pull/581) | 2026-08-20 | deferred | Gate 0 | `agentDefaults.computerUseModel` is unreleased — the drafting PR said so in its own title. Real knob, would pass Gate 1, but Gate 0 is a hard prerequisite. Re-check when the setting ships to GA. | +| [docs#581](https://github.com/warpdotdev/docs/pull/581) | 2026-09-16 | yes | Gate 0 + Gate 1 | The production Factory schema registry now publishes `agentDefaults.computerUseModel`, clearing the prior Gate 0 deferral. The exhaustive Factory definition reference documents the key in merged docs PR #754. | | [#14418](https://github.com/warpdotdev/warp/pull/14418) | 2026-08-20 | yes | Gate 1 | Agent execution profiles configurable from settings files for all users. Named settings-file configuration. Update the existing agent profiles page. | | [#14344](https://github.com/warpdotdev/warp/pull/14344) | 2026-08-20 | no | Disqualified: pure UI affordance | Armadillo icon replaced with the theme-adaptive Warp "W" logo. Nothing configurable, nothing to get stuck on. | | [#14298](https://github.com/warpdotdev/warp/pull/14298) | 2026-08-20 | no | Disqualified: small and intuitive | MCP tool confirmations now show the running tool and its source server. Understood on sight. | @@ -166,7 +166,7 @@ Newest first. One row per PR number — usually a `warpdotdev/warp` changelog it The `warpdotdev/warp` rows come from the `v0.2026.07.29.09.05.stable_02` changelog and double as the calibration set in `.agents/references/docs-worthiness-criteria.md`. Rows marked `yes` record the verdict, not that the docs change has shipped — several are still open PRs. -The two `warpdotdev/docs` rows were the regression cases used to validate the gate when it was introduced: docs#581 must fail Gate 0 because it documents an unreleased setting, and docs#582 must pass, because a gate that rejects everything is as broken as one that accepts everything. +The two `warpdotdev/docs` rows were the regression cases used to validate the gate when it was introduced. Docs PR #581 was correctly deferred while the key was unreleased, then moved to `yes` when the production Factory schema registry published it. Docs PR #582 passed independently. ### Audit blind spot: provider subcommands under `oz secret create` diff --git a/src/content/docs/factories/factory-as-code.mdx b/src/content/docs/factories/factory-as-code.mdx index 5b3138258..34ff90481 100644 --- a/src/content/docs/factories/factory-as-code.mdx +++ b/src/content/docs/factories/factory-as-code.mdx @@ -60,6 +60,7 @@ For a CI job built on the script, see the example repository's [validation workf * **Anywhere else** - Have the agent run the [validator script](#validate-locally-or-in-ci). ## JSON Schema +{/* factory-schema-coverage: common.schema.json */} Warp publishes the definition format as JSON Schema documents for editor completion and validation. Each field has a description, and the schema flags unknown fields. The endpoints are unauthenticated: @@ -116,6 +117,7 @@ webhooks/ Only `factory.yaml` and at least one agent are required. For a complete working definition, see the [example factory definition](#example-factory-definition) below. The smallest complete example tree is [`01-single-repo-quickstart`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/01-single-repo-quickstart); the fullest is [`02-sdlc-issue-to-pr`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/02-sdlc-issue-to-pr). ## `factory.yaml` +{/* factory-schema-coverage: factory.schema.json */} The factory's root document. It names the factory, scopes it to repositories, and sets the execution defaults every agent inherits. @@ -151,7 +153,7 @@ Optional. Whose credentials the factory's runs execute with: `EXECUTOR` (the pri ### `repositories` -Required. The repositories the factory works in, as `owner` and `name` pairs. On a GitLab-backed factory these are the projects you selected under the connected group. +Required. The repositories the factory works in, as `owner` and `name` pairs. The optional `codeForge` is `GITHUB`, `GITLAB`, or `AZURE_DEVOPS`; omit it to use the factory's primary forge. ```yaml repositories: @@ -161,13 +163,25 @@ repositories: name: payments-docs ``` +### `codeForges` + +Optional. The forges connected to the factory: `GITHUB`, `GITLAB`, or `AZURE_DEVOPS`. Omit the key to keep the stored set. An empty list disables all forges, and a list with more than one forge requires `codeForge` on every [`repositories`](#repositories) entry. + +### `benchmarkRepoSubstitutions` + +Optional. Repository replacements used only for benchmark runs. Each entry requires `source` and `target`; both identify a GitHub repository with `codeForge: GITHUB`, `owner`, and `name`. + ### `secrets` Optional. Names of [managed secrets](/platform/secrets/) granted to every agent in the factory, in addition to anything individual agents declare. ### `mcpServers` -Optional. [MCP servers](/platform/mcp/) granted to every agent, keyed by the name the agent sees. Each entry references a Warp-managed MCP server by `warpId`. +Optional. [MCP servers](/platform/mcp/) granted to every agent, keyed by the name the agent sees. Each entry selects exactly one transport: + +* `warpId` - A Warp-managed MCP server ID. +* `command` - A stdio command. Optional `args` and `env` apply only to this transport. +* `url` - An absolute HTTP or HTTPS URL. Optional `headers` apply only to this transport. ```yaml mcpServers: @@ -187,7 +201,7 @@ cloudProviders: ### `integrations` -Optional. The integration providers attached to the factory. `type` accepts `slack`, `linear`, or `jira`. Declare at most one issue tracker: `linear` and `jira` are mutually exclusive, and omitting a tracker is also valid. GitHub is not declared here; repository access comes from `repositories` and the connected GitHub App. +Optional. The integration providers attached to the factory. `type` accepts `slack`, `linear`, or `jira`. The optional provider settings are `slack.autoRespondToThreadReplies`, `linear.teamIds`, and `jira.projectKeys`. Declare at most one issue tracker: `linear` and `jira` are mutually exclusive, and omitting a tracker is also valid. GitHub is not declared here; repository access comes from `repositories` and the connected GitHub App. ```yaml integrations: @@ -195,6 +209,8 @@ integrations: - type: linear ``` +The legacy `providers` key is accepted when reading older definitions. Use `cloudProviders`; when Warp rewrites the definition, it emits `cloudProviders`. + ### `agentDefaults` Required. The execution defaults every agent inherits. Declare exactly one of `model` or `harness`; the other keys are optional. An agent that sets one of these keys for itself overrides the default. @@ -294,6 +310,7 @@ The selected value must be available to your plan and workspace. See [model choi An agent or automation can declare `computerUseModel` to override the inherited value for its runs. For an agent, omitting the key or setting it to `null` inherits `agentDefaults.computerUseModel`. For an automation, omitting the key or setting it to `null` inherits the selected agent's effective value, including an agent-level override. The setting applies only to Computer Use on the Warp Agent harness (`type: oz`); Warp keeps but ignores it for a third-party harness or when Computer Use is disabled. It can appear alongside either `model` or `harness` because it doesn't select the agent's main model. ## `agents//agent.md` +{/* factory-schema-coverage: agent.schema.json */} One file per agent. The YAML frontmatter configures how the agent runs, and the Markdown body is the agent's prompt: the durable instructions for its role. The agent's name comes from its directory. @@ -319,6 +336,7 @@ The frontmatter accepts: The agent's role: `CUSTOM` (the default), `FOREMAN` (alias `MAIN`), `TRIAGE`, `SPEC`, `IMPLEMENT`, `REVIEW`, or `VERIFY`. Every definition declares exactly one foreman — the factory's entry point and the default target for automations. See [factory agents](/factories/factory-agents/) for what each role does. ## `automations//automation.md` +{/* factory-schema-coverage: automation.schema.json */} One file per automation. The frontmatter declares when runs start and how they execute, and the Markdown body is the prompt each run starts with. The automation's name comes from its directory. @@ -368,6 +386,15 @@ Optional. Narrows which events start runs. The keys a filter accepts depend on t A `webhook` trigger with the `received` event requires `webhook_ids` in its filter, a list of webhook UIDs (`in` only; the file name isn't accepted), and takes an optional `payload` pattern that mirrors the delivery's JSON body. See [payload filters for webhook triggers](/factories/automations/#payload-filters-for-webhook-triggers) for the pattern grammar. +The published trigger catalog currently uses these filter keys across its provider and event combinations: + +* GitHub and GitLab: `actions`, `assignees`, `assignee_ids`, `authors`, `base_branches`, `branches`, `conclusions`, `labels`, `paths`, `pr_numbers`, `repos`, `review_states`, `reviewer_teams`, `reviewers`, and `workflows`. +* Linear and Jira: `creator_ids`, `issue_ids`, `project_ids`, `project_keys`, `stages`, `state_ids`, `status_ids`, and `team_ids`. +* Slack: `channel_ids`, `emojis`, `item_user_ids`, `keywords`, `mentioned`, `mentioned_user_ids`, and `user_ids`. +* Schedule and webhook: `schedule_ids`, `webhook_ids`, and `payload`. Payload patterns also accept `exists`. + +`baseBranches` and `prNumbers` are authoring aliases for `base_branches` and `pr_numbers`. `teams`, `projects`, `states`, `issues`, `channels`, `users`, and `itemUsers` are name-based aliases for their `_ids` counterparts. An alias and its canonical key are mutually exclusive. + ```yaml triggers: - provider: webhook @@ -396,6 +423,7 @@ triggers: An automation may also declare `model` or `harness`, `runner`, `environmentId`, `secrets`, `mcpServers`, `workerHost`, and `computerUseModel` (the same keys as [`agentDefaults`](#agentdefaults)) to override the target agent's settings for the runs it starts. ## `runners/.yaml` +{/* factory-schema-coverage: runner.schema.json */} Optional. Each file defines a runner: the compute a run executes on. The runner's name comes from the file name, and agents and automations select it by that name. See [cloud agent runners](/platform/runners/) for how runners behave. For three runners selected per agent, including a macOS runner, see [`02-sdlc-issue-to-pr`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/02-sdlc-issue-to-pr). @@ -417,6 +445,10 @@ platform: Optional. Shell commands run in order while the sandbox is prepared. +### `failureSessionRetentionMinutes` + +Optional. Keeps a failed run's session open for 1 to 60 minutes so you can inspect it. Omit the key to use the environment's setting. + ### `instanceShape` Optional. The compute size, as `vcpus` and `memoryGb`. Omit it to take the workspace default. @@ -425,7 +457,10 @@ Optional. The compute size, as `vcpus` and `memoryGb`. Omit it to take the works The operating system and architecture. `os` is `linux` (the default) or `macos`, and `arch` is `x86_64` (the default on Linux) or `aarch64` (the only option on macOS). Linux runners require `linux.dockerImage`, the container image the sandbox boots, so every Linux runner declares a `platform` section. macOS runners accept an optional `mac.version` (`"14"`, `"15"`, `"26"`, or `"27"`; quote it, and it defaults to `"26"`). +For a private Linux image, set `linux.registryCredentialSecretName` to a managed `docker_registry` secret whose registry host matches `linux.dockerImage`. + ## `benchmarks//suite.yaml` +{/* factory-schema-coverage: benchmark_suite.schema.json */} Optional. This file defines a [benchmark suite](/factories/benchmarks/): one agent, optional reusable configurations, and an ordered set of reusable tasks. The suite slug is its stable file location, not its display name, so renaming `name` does not move the file or change the suite's identity. @@ -471,6 +506,7 @@ The optional `agents` list pins named factory agents to the models and harnesses Optional. An ordered list of unique task slugs. Each slug must match exactly one file under `benchmarks//tasks/`, and every task file must appear once in this list. A suite without tasks saves successfully but cannot run. ## `benchmarks//tasks/.yaml` +{/* factory-schema-coverage: benchmark_suite_task.schema.json */} Optional. Each file defines one task in its parent suite. The task slug is the file name without `.yaml` and stays stable when you change the task's title. @@ -500,9 +536,14 @@ Optional. The ID of the prior run the task came from. This records provenance on ### `startingRepoRefs` -Optional. The GitHub or GitLab repositories and exact commits the task starts from. Use either `github.com:OWNER/REPO@COMMIT_SHA` or `gitlab.com:OWNER/REPO@COMMIT_SHA`; `COMMIT_SHA` must be a full 40-character commit SHA, not a branch or tag. Omit this key to use the agent's normal checkout defaults. +Optional. The GitHub or GitLab repositories and exact commits the task starts from. Each entry can use `github.com:OWNER/REPO@COMMIT_SHA` or `gitlab.com:OWNER/REPO@COMMIT_SHA`. It can instead use an object with `codeForge` (`GITHUB` or `GITLAB`), `owner`, `repo`, and `ref`. `COMMIT_SHA` and `ref` must be full 40-character commit SHAs, not branches or tags. Omit this key to use the agent's normal checkout defaults. + +### `linearSeed` + +Optional. JSON-compatible starting state for the isolated Linear sandbox used by the benchmark trial. ## `scorers//scorer.md` +{/* factory-schema-coverage: scorer.schema.json */} Optional. Each file defines a scorer: an LLM judge that classifies a sample of an agent's finished runs against a rubric. The directory segment is only a stable filesystem slug — the required `name` field is the scorer's identity. The YAML frontmatter declares the classification contract, and the Markdown body after the closing `---` fence is the rubric. See [Configuring Scorers](/factories/measure-and-improve/scorers/) for how scores are used. @@ -536,7 +577,7 @@ Optional. A short summary of what the scorer checks. ### `agents` -Required. The agents whose runs this scorer evaluates, as a list of one or more agent names. Each name matches an agent defined under [`agents/`](#agentsnameagentmd). +Required. The agents whose runs this scorer evaluates, as a list of one or more agent names. Each name matches an agent defined under [`agents/`](#agentsnameagentmd). Use an object with `name` and `includeDescendants: true` to include scoring evidence from the agent's descendant runs; `includeDescendants` defaults to `false`. ### `output` @@ -563,6 +604,7 @@ Required. The model that judges the runs. Optional. When `true`, failing scores can feed the factory's self-improvement flow, which proposes definition changes as pull requests. Defaults to `false`. ## `webhooks/.yaml` +{/* factory-schema-coverage: webhook.schema.json */} Optional. Each file defines a [custom webhook](/factories/webhooks/): an authenticated URL that external systems POST JSON to, which `webhook` triggers on automations subscribe to. The webhook's name comes from the file name. The file never holds the secret itself: `secretName` references a [managed secret](/platform/secrets/) that already exists on the team, and Warp never generates one for a file-declared webhook. From 8c112cdb148d0f7428b05507e2cbb5b85ff1e918 Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Thu, 17 Sep 2026 05:03:00 +0000 Subject: [PATCH 2/4] docs: publish production Factory fields only --- .../references/docs-worthiness-criteria.md | 5 +-- .../references/changelog_decisions.md | 4 +-- .../docs/factories/factory-as-code.mdx | 32 ++++--------------- 3 files changed, 9 insertions(+), 32 deletions(-) diff --git a/.agents/references/docs-worthiness-criteria.md b/.agents/references/docs-worthiness-criteria.md index 0212f09d8..a495cef37 100644 --- a/.agents/references/docs-worthiness-criteria.md +++ b/.agents/references/docs-worthiness-criteria.md @@ -20,8 +20,6 @@ These criteria govern the **weekly release stream** — changes that reached use Major launches (Warp Factories, for example) are planned in advance and documented by the docs team on a proactive, human-led path. They do not run through these gates. If you encounter a change that is clearly part of an announced launch, defer it rather than gating it. -The Factory definition reference is exhaustive. A key in the production Factory schema registry has passed Gate 0 and must be covered there. A prior `deferred` ledger row cannot suppress a key after publication. - ### How much applies depends on who is asking **Automated runs apply the full gate.** A scheduled agent has no context beyond what it can read, and unattended drafting at scale is what this reference exists to control. Default to no docs; make the change earn the page. @@ -151,8 +149,6 @@ Drawn from the `v0.2026.07.29.09.05.stable_02` changelog. These calibrate the bo **Agent execution profiles configurable from settings files** ([#14418](https://github.com/warpdotdev/warp/pull/14418)) — **Gate 1, update existing page.** Named settings-file configuration, previously unavailable to all users. -**`agentDefaults.computerUseModel`** (docs PR [#754](https://github.com/warpdotdev/docs/pull/754)) — **Gate 0 and Gate 1, update existing reference.** The key appears in the production Factory schema registry, which is the release gate for the exhaustive Factory definition reference. The older deferred verdict from docs PR #581 stopped applying when publication cleared Gate 0. - **Drag and drop image files into an active CLI agent session** ([#9553](https://github.com/warpdotdev/warp/pull/9553)) — **Gate 4, update existing page.** The job — attaching a screenshot to a Claude Code session — was not possible before, not merely slower. There is no knob, so Gate 1 does not fire; nothing fails, so Gate 2 does not; behavior the reader relied on did not change, so Gate 3 does not. Checked for an affordance and found none: no Command Palette entry, no menu item, no toolbar control, no hint in the session UI. A reader who does not already know will never try it. One sentence on the CLI agent page; the Gate 4 cap rules out a new page. ### Fails @@ -167,6 +163,7 @@ Drawn from the `v0.2026.07.29.09.05.stable_02` changelog. These calibrate the bo **MCP tool confirmations show the tool and source server** ([#14298](https://github.com/warpdotdev/warp/pull/14298)) — **Disqualified: small and intuitive.** The confirmation dialog now shows more context. A reader encountering it understands it immediately. +**`agentDefaults.computerUseModel`** (docs PR [#581](https://github.com/warpdotdev/docs/pull/581)) — **Gate 0 failure: deferred, not documented.** This is the regression case. A drafting agent wrote the page and labeled it "(unreleased feature)" in the PR title, which is the gate failing out loud. An unreleased setting key is a real knob and would pass Gate 1 — but Gate 0 comes first and is a hard prerequisite. Defer with the blocking reason and re-surface it when the feature ships. ## Related references diff --git a/.agents/skills/missing_docs/references/changelog_decisions.md b/.agents/skills/missing_docs/references/changelog_decisions.md index 3327fdc2d..d9d0ec5d6 100644 --- a/.agents/skills/missing_docs/references/changelog_decisions.md +++ b/.agents/skills/missing_docs/references/changelog_decisions.md @@ -152,7 +152,7 @@ Newest first. One row per PR number — usually a `warpdotdev/warp` changelog it | POST /factory/{uid}/runs | 2026-08-25 | deferred | Gate 0 | New public_api route in warp-server. Sibling factory routes are mapped internal; released public OpenAPI (`developers/agent-api-openapi.yaml`) has zero `/factory` paths. EA docs already describe dispatch on `factories/factory-api.mdx`. Map `-> internal`; re-check when factory routes are published via sync-openapi-spec. | | POST /factory/automations/{id}/run | 2026-08-25 | deferred | Gate 0 | Manual run endpoint for factory automations (`RunFactoryAutomationHandler`). Same Gate 0 boundary as other factory automations routes already mapped `-> internal`. Not in released OpenAPI. Re-check with factory API publish. | | [docs#582](https://github.com/warpdotdev/docs/pull/582) | 2026-08-20 | yes | Gate 3 | Factory Dashboard metric definitions (APP-5546). The counting rules are non-obvious and currently live only in hover tooltips: the By-model view caps at eight and folds the rest into Other, there is an Unknown bucket, and opened/merged pull request counts can legitimately disagree. A reader reading the dashboard without them draws wrong conclusions. New reference page justified — no existing page carries per-metric detail. | -| [docs#581](https://github.com/warpdotdev/docs/pull/581) | 2026-09-16 | yes | Gate 0 + Gate 1 | The production Factory schema registry now publishes `agentDefaults.computerUseModel`, clearing the prior Gate 0 deferral. The exhaustive Factory definition reference documents the key in merged docs PR #754. | +| [docs#581](https://github.com/warpdotdev/docs/pull/581) | 2026-08-20 | deferred | Gate 0 | `agentDefaults.computerUseModel` is unreleased — the drafting PR said so in its own title. Real knob, would pass Gate 1, but Gate 0 is a hard prerequisite. Re-check when the setting ships to GA. | | [#14418](https://github.com/warpdotdev/warp/pull/14418) | 2026-08-20 | yes | Gate 1 | Agent execution profiles configurable from settings files for all users. Named settings-file configuration. Update the existing agent profiles page. | | [#14344](https://github.com/warpdotdev/warp/pull/14344) | 2026-08-20 | no | Disqualified: pure UI affordance | Armadillo icon replaced with the theme-adaptive Warp "W" logo. Nothing configurable, nothing to get stuck on. | | [#14298](https://github.com/warpdotdev/warp/pull/14298) | 2026-08-20 | no | Disqualified: small and intuitive | MCP tool confirmations now show the running tool and its source server. Understood on sight. | @@ -166,7 +166,7 @@ Newest first. One row per PR number — usually a `warpdotdev/warp` changelog it The `warpdotdev/warp` rows come from the `v0.2026.07.29.09.05.stable_02` changelog and double as the calibration set in `.agents/references/docs-worthiness-criteria.md`. Rows marked `yes` record the verdict, not that the docs change has shipped — several are still open PRs. -The two `warpdotdev/docs` rows were the regression cases used to validate the gate when it was introduced. Docs PR #581 was correctly deferred while the key was unreleased, then moved to `yes` when the production Factory schema registry published it. Docs PR #582 passed independently. +The two `warpdotdev/docs` rows were the regression cases used to validate the gate when it was introduced: docs#581 must fail Gate 0 because it documents an unreleased setting, and docs#582 must pass, because a gate that rejects everything is as broken as one that accepts everything. ### Audit blind spot: provider subcommands under `oz secret create` diff --git a/src/content/docs/factories/factory-as-code.mdx b/src/content/docs/factories/factory-as-code.mdx index 34ff90481..9c428ca88 100644 --- a/src/content/docs/factories/factory-as-code.mdx +++ b/src/content/docs/factories/factory-as-code.mdx @@ -60,7 +60,6 @@ For a CI job built on the script, see the example repository's [validation workf * **Anywhere else** - Have the agent run the [validator script](#validate-locally-or-in-ci). ## JSON Schema -{/* factory-schema-coverage: common.schema.json */} Warp publishes the definition format as JSON Schema documents for editor completion and validation. Each field has a description, and the schema flags unknown fields. The endpoints are unauthenticated: @@ -117,7 +116,6 @@ webhooks/ Only `factory.yaml` and at least one agent are required. For a complete working definition, see the [example factory definition](#example-factory-definition) below. The smallest complete example tree is [`01-single-repo-quickstart`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/01-single-repo-quickstart); the fullest is [`02-sdlc-issue-to-pr`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/02-sdlc-issue-to-pr). ## `factory.yaml` -{/* factory-schema-coverage: factory.schema.json */} The factory's root document. It names the factory, scopes it to repositories, and sets the execution defaults every agent inherits. @@ -153,7 +151,7 @@ Optional. Whose credentials the factory's runs execute with: `EXECUTOR` (the pri ### `repositories` -Required. The repositories the factory works in, as `owner` and `name` pairs. The optional `codeForge` is `GITHUB`, `GITLAB`, or `AZURE_DEVOPS`; omit it to use the factory's primary forge. +Required. The repositories the factory works in, as `owner` and `name` pairs. The optional `codeForge` is `GITHUB` or `GITLAB`; omit it to use the factory's primary forge. ```yaml repositories: @@ -165,11 +163,7 @@ repositories: ### `codeForges` -Optional. The forges connected to the factory: `GITHUB`, `GITLAB`, or `AZURE_DEVOPS`. Omit the key to keep the stored set. An empty list disables all forges, and a list with more than one forge requires `codeForge` on every [`repositories`](#repositories) entry. - -### `benchmarkRepoSubstitutions` - -Optional. Repository replacements used only for benchmark runs. Each entry requires `source` and `target`; both identify a GitHub repository with `codeForge: GITHUB`, `owner`, and `name`. +Optional. The forges connected to the factory: `GITHUB` or `GITLAB`. Omit the key to keep the stored set. An empty list disables all forges, and a list with more than one forge requires `codeForge` on every [`repositories`](#repositories) entry. ### `secrets` @@ -201,7 +195,7 @@ cloudProviders: ### `integrations` -Optional. The integration providers attached to the factory. `type` accepts `slack`, `linear`, or `jira`. The optional provider settings are `slack.autoRespondToThreadReplies`, `linear.teamIds`, and `jira.projectKeys`. Declare at most one issue tracker: `linear` and `jira` are mutually exclusive, and omitting a tracker is also valid. GitHub is not declared here; repository access comes from `repositories` and the connected GitHub App. +Optional. The integration providers attached to the factory. `type` accepts `slack`, `linear`, or `jira`. Use `linear.teamIds` or `jira.projectKeys` to limit the teams or projects available to the factory. Declare at most one issue tracker: `linear` and `jira` are mutually exclusive, and omitting a tracker is also valid. GitHub is not declared here; repository access comes from `repositories` and the connected GitHub App. ```yaml integrations: @@ -310,7 +304,6 @@ The selected value must be available to your plan and workspace. See [model choi An agent or automation can declare `computerUseModel` to override the inherited value for its runs. For an agent, omitting the key or setting it to `null` inherits `agentDefaults.computerUseModel`. For an automation, omitting the key or setting it to `null` inherits the selected agent's effective value, including an agent-level override. The setting applies only to Computer Use on the Warp Agent harness (`type: oz`); Warp keeps but ignores it for a third-party harness or when Computer Use is disabled. It can appear alongside either `model` or `harness` because it doesn't select the agent's main model. ## `agents//agent.md` -{/* factory-schema-coverage: agent.schema.json */} One file per agent. The YAML frontmatter configures how the agent runs, and the Markdown body is the agent's prompt: the durable instructions for its role. The agent's name comes from its directory. @@ -336,7 +329,6 @@ The frontmatter accepts: The agent's role: `CUSTOM` (the default), `FOREMAN` (alias `MAIN`), `TRIAGE`, `SPEC`, `IMPLEMENT`, `REVIEW`, or `VERIFY`. Every definition declares exactly one foreman — the factory's entry point and the default target for automations. See [factory agents](/factories/factory-agents/) for what each role does. ## `automations//automation.md` -{/* factory-schema-coverage: automation.schema.json */} One file per automation. The frontmatter declares when runs start and how they execute, and the Markdown body is the prompt each run starts with. The automation's name comes from its directory. @@ -391,7 +383,8 @@ The published trigger catalog currently uses these filter keys across its provid * GitHub and GitLab: `actions`, `assignees`, `assignee_ids`, `authors`, `base_branches`, `branches`, `conclusions`, `labels`, `paths`, `pr_numbers`, `repos`, `review_states`, `reviewer_teams`, `reviewers`, and `workflows`. * Linear and Jira: `creator_ids`, `issue_ids`, `project_ids`, `project_keys`, `stages`, `state_ids`, `status_ids`, and `team_ids`. * Slack: `channel_ids`, `emojis`, `item_user_ids`, `keywords`, `mentioned`, `mentioned_user_ids`, and `user_ids`. -* Schedule and webhook: `schedule_ids`, `webhook_ids`, and `payload`. Payload patterns also accept `exists`. +* Schedule: `schedule_ids` is server-managed and cannot be set in a factory definition. +* Webhook: `webhook_ids` and `payload`. Payload patterns also accept `exists`. `baseBranches` and `prNumbers` are authoring aliases for `base_branches` and `pr_numbers`. `teams`, `projects`, `states`, `issues`, `channels`, `users`, and `itemUsers` are name-based aliases for their `_ids` counterparts. An alias and its canonical key are mutually exclusive. @@ -423,7 +416,6 @@ triggers: An automation may also declare `model` or `harness`, `runner`, `environmentId`, `secrets`, `mcpServers`, `workerHost`, and `computerUseModel` (the same keys as [`agentDefaults`](#agentdefaults)) to override the target agent's settings for the runs it starts. ## `runners/.yaml` -{/* factory-schema-coverage: runner.schema.json */} Optional. Each file defines a runner: the compute a run executes on. The runner's name comes from the file name, and agents and automations select it by that name. See [cloud agent runners](/platform/runners/) for how runners behave. For three runners selected per agent, including a macOS runner, see [`02-sdlc-issue-to-pr`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/02-sdlc-issue-to-pr). @@ -445,10 +437,6 @@ platform: Optional. Shell commands run in order while the sandbox is prepared. -### `failureSessionRetentionMinutes` - -Optional. Keeps a failed run's session open for 1 to 60 minutes so you can inspect it. Omit the key to use the environment's setting. - ### `instanceShape` Optional. The compute size, as `vcpus` and `memoryGb`. Omit it to take the workspace default. @@ -460,7 +448,6 @@ The operating system and architecture. `os` is `linux` (the default) or `macos`, For a private Linux image, set `linux.registryCredentialSecretName` to a managed `docker_registry` secret whose registry host matches `linux.dockerImage`. ## `benchmarks//suite.yaml` -{/* factory-schema-coverage: benchmark_suite.schema.json */} Optional. This file defines a [benchmark suite](/factories/benchmarks/): one agent, optional reusable configurations, and an ordered set of reusable tasks. The suite slug is its stable file location, not its display name, so renaming `name` does not move the file or change the suite's identity. @@ -506,7 +493,6 @@ The optional `agents` list pins named factory agents to the models and harnesses Optional. An ordered list of unique task slugs. Each slug must match exactly one file under `benchmarks//tasks/`, and every task file must appear once in this list. A suite without tasks saves successfully but cannot run. ## `benchmarks//tasks/.yaml` -{/* factory-schema-coverage: benchmark_suite_task.schema.json */} Optional. Each file defines one task in its parent suite. The task slug is the file name without `.yaml` and stays stable when you change the task's title. @@ -538,12 +524,7 @@ Optional. The ID of the prior run the task came from. This records provenance on Optional. The GitHub or GitLab repositories and exact commits the task starts from. Each entry can use `github.com:OWNER/REPO@COMMIT_SHA` or `gitlab.com:OWNER/REPO@COMMIT_SHA`. It can instead use an object with `codeForge` (`GITHUB` or `GITLAB`), `owner`, `repo`, and `ref`. `COMMIT_SHA` and `ref` must be full 40-character commit SHAs, not branches or tags. Omit this key to use the agent's normal checkout defaults. -### `linearSeed` - -Optional. JSON-compatible starting state for the isolated Linear sandbox used by the benchmark trial. - ## `scorers//scorer.md` -{/* factory-schema-coverage: scorer.schema.json */} Optional. Each file defines a scorer: an LLM judge that classifies a sample of an agent's finished runs against a rubric. The directory segment is only a stable filesystem slug — the required `name` field is the scorer's identity. The YAML frontmatter declares the classification contract, and the Markdown body after the closing `---` fence is the rubric. See [Configuring Scorers](/factories/measure-and-improve/scorers/) for how scores are used. @@ -577,7 +558,7 @@ Optional. A short summary of what the scorer checks. ### `agents` -Required. The agents whose runs this scorer evaluates, as a list of one or more agent names. Each name matches an agent defined under [`agents/`](#agentsnameagentmd). Use an object with `name` and `includeDescendants: true` to include scoring evidence from the agent's descendant runs; `includeDescendants` defaults to `false`. +Required. The agents whose runs this scorer evaluates, as a list of one or more agent names. Each name matches an agent defined under [`agents/`](#agentsnameagentmd). ### `output` @@ -604,7 +585,6 @@ Required. The model that judges the runs. Optional. When `true`, failing scores can feed the factory's self-improvement flow, which proposes definition changes as pull requests. Defaults to `false`. ## `webhooks/.yaml` -{/* factory-schema-coverage: webhook.schema.json */} Optional. Each file defines a [custom webhook](/factories/webhooks/): an authenticated URL that external systems POST JSON to, which `webhook` triggers on automations subscribe to. The webhook's name comes from the file name. The file never holds the secret itself: `secretName` references a [managed secret](/platform/secrets/) that already exists on the team, and Warp never generates one for a file-declared webhook. From 9dededef4ea499d0dbfe6a371c958032e345b592 Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Thu, 17 Sep 2026 05:22:20 +0000 Subject: [PATCH 3/4] Correct Factory trigger filter catalog --- src/content/docs/factories/factory-as-code.mdx | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/src/content/docs/factories/factory-as-code.mdx b/src/content/docs/factories/factory-as-code.mdx index 9c428ca88..1a927a6c9 100644 --- a/src/content/docs/factories/factory-as-code.mdx +++ b/src/content/docs/factories/factory-as-code.mdx @@ -380,11 +380,16 @@ A `webhook` trigger with the `received` event requires `webhook_ids` in its filt The published trigger catalog currently uses these filter keys across its provider and event combinations: -* GitHub and GitLab: `actions`, `assignees`, `assignee_ids`, `authors`, `base_branches`, `branches`, `conclusions`, `labels`, `paths`, `pr_numbers`, `repos`, `review_states`, `reviewer_teams`, `reviewers`, and `workflows`. -* Linear and Jira: `creator_ids`, `issue_ids`, `project_ids`, `project_keys`, `stages`, `state_ids`, `status_ids`, and `team_ids`. -* Slack: `channel_ids`, `emojis`, `item_user_ids`, `keywords`, `mentioned`, `mentioned_user_ids`, and `user_ids`. +* Factory: `stages`. +* GitHub: `assignees`, `authors`, `baseBranches`, `base_branches`, `branches`, `conclusions`, `labels`, `mentioned`, `paths`, `prNumbers`, `pr_numbers`, `repos`, `review_states`, `reviewer_teams`, `reviewers`, and `workflows`. +* GitLab: `actions`, `base_branches`, `branches`, `mentioned`, and `repos`. +* Jira: `keywords`, `labels`, `project_keys`, and `status_ids`. +* Linear: `assignee_ids`, `creator_ids`, `issue_ids`, `issues`, `keywords`, `labels`, `mentioned_user_ids`, `project_ids`, `projects`, `state_ids`, `states`, `team_ids`, and `teams`. * Schedule: `schedule_ids` is server-managed and cannot be set in a factory definition. -* Webhook: `webhook_ids` and `payload`. Payload patterns also accept `exists`. +* Slack: `channel_ids`, `channels`, `emojis`, `itemUsers`, `item_user_ids`, `keywords`, `user_ids`, and `users`. +* Webhook: `payload` and `webhook_ids`. + +Payload patterns also accept `exists`. `baseBranches` and `prNumbers` are authoring aliases for `base_branches` and `pr_numbers`. `teams`, `projects`, `states`, `issues`, `channels`, `users`, and `itemUsers` are name-based aliases for their `_ids` counterparts. An alias and its canonical key are mutually exclusive. From 624dbc0ba66f9c10362ab7908762d5cca5434de4 Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Fri, 18 Sep 2026 04:46:12 +0000 Subject: [PATCH 4/4] docs: clarify MCP transport credentials Document the released MCP field shapes and direct credentials to managed secrets or managed MCP installations. Co-Authored-By: Oz --- src/content/docs/factories/factory-as-code.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/content/docs/factories/factory-as-code.mdx b/src/content/docs/factories/factory-as-code.mdx index 60a9f6ae6..b0eb0f94e 100644 --- a/src/content/docs/factories/factory-as-code.mdx +++ b/src/content/docs/factories/factory-as-code.mdx @@ -179,8 +179,10 @@ Optional. Names of [managed secrets](/platform/secrets/) granted to every agent Optional. [MCP servers](/platform/mcp/) granted to every agent, keyed by the name the agent sees. Each entry selects exactly one transport: * `warpId` - A Warp-managed MCP server ID. -* `command` - A stdio command. Optional `args` and `env` apply only to this transport. -* `url` - An absolute HTTP or HTTPS URL. Optional `headers` apply only to this transport. +* `command` - A stdio command. Optional `args` is a list of strings, and optional `env` maps names to string values. +* `url` - An absolute HTTP or HTTPS URL. Optional `headers` maps header names to string values. + +Don't put credentials directly in `env` or `headers`. Reference a [Warp-managed secret](/platform/secrets/) as `{{SECRET_NAME}}`, or use `warpId` for a [managed MCP installation](/platform/mcp/#oauth-authentication). ```yaml mcpServers: