docs: editorial review of product overviews, factories, and quickstarts

.agents/references/terminology.md

@@ -366,7 +366,7 @@ Docs match the screen; the fix belongs in the app.
   *Usage note:* Not a second concept. Use "task" only where the MCP surface forces it, and say once on the page that a task is the factory's work item. Never introduce "task" as a distinct unit of work.
 
 - **stages** — The phases a work item moves through, named as the factory dashboard's **Activity** view names them: **Triage**, **Planning**, **Building**, and **Reviewing**, plus the terminal stages **Complete** and **Cancelled**.
-  *Usage note:* Stage names are not agent names. The spec agent works the Planning stage, the implement agent works the Building stage, and the review agent works the Reviewing stage. Write stages with the dashboard's names so docs and screen agree; write agents with their own names (triage, spec, implement, review).
+  *Usage note:* Stage names are not agent names. The spec agent works the planning stage, the implement agent works the building stage, and the review agent works the reviewing stage. Use lowercase for stages in explanatory prose. Preserve the displayed spelling and capitalization when referencing exact UI labels, filters, or status values; sentence-initial and diagram labels may also begin with capitals. Write agents with their own names (triage, spec, implement, review).
 
 - **foreman agent** — The foreman is the agent that coordinates a factory's work and communicates with you. It delegates work to other agents, asks for your decisions when needed, and returns results.
   *Usage note:* Lowercase "foreman" in prose. The foreman is an agent inside a factory, not the factory itself — never use the two interchangeably, and never call the foreman "the factory" even though setup gives them the same name by default.
@@ -434,6 +434,8 @@ Docs match the screen; the fix belongs in the app.
 ## Billing and credits
 
 - **usage** — the general term for metered inference, Warp-hosted compute, and platform activity. Explain dollars versus credits when that distinction affects the task; use ordinary plan names elsewhere.
+- **usage balance** — usage available to the user or team billed for the work, subject to the applicable billing rules.
+  *Usage note:* Use "add usage" for the action of funding the balance, with "if needed" when an existing allowance may cover the work. Do not imply that every workflow uses a shared team balance or requires a new purchase.
 - **included usage** — the allowance included with a plan; distinguish it from purchased usage and contract-specific pools.
 - **purchased usage** — additional usage bought on an eligible plan. Distinguish the usage added to the balance from the payment amount.
 - **dollar usage** — a usage balance expressed in US dollars, not the subscription price or necessarily the amount paid for a purchase.

AGENTS.md

@@ -346,6 +346,7 @@ Captions orient the reader — they identify what the image shows so the reader
 - ❌ `<figcaption>The input toolbelt, from left to right: model selector, voice input, image attachments, and conversation controls.</figcaption>` (exhaustive list)
 
 ### Links, embeds, and cross-references
+- When link text uses a destination's full page title, match that title's wording and capitalization, even within a sentence. Descriptive link phrases follow normal sentence capitalization and don't need to reproduce the title.
 - Use descriptive link text that explains what users will find. The anchor text should describe the destination or task, not the action of clicking.
   - ✅ "Learn more about [Codebase Context](...)" / "See [configuring environments](...)"
   - ❌ "Click [here](...)" / "See [this page](...)" / "Read [more](...)"
@@ -567,6 +568,7 @@ These rules apply regardless of content type:
 5. Troubleshooting for common issues (optional but recommended)
 
 **Rules**:
+- **Keep prerequisites concise.** State requirements in unbolded bullets rather than bold labels followed by explanations. Link setup details, and put conditional instructions beside the step that needs them. Keep required access, credential types, and technical constraints explicit. This also applies to quickstarts.
 - **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.
@@ -955,6 +957,24 @@ Match a control's shipped label without letting that label define all surroundin
 
 Scope credential claims by configuration: personal device keys, team-managed keys and endpoints, connected subscriptions, and third-party harness credentials are different paths. Don't apply "not stored by Warp" or "not available to cloud agents" to all customer credentials. See the glossary's [inference configuration terms](.agents/references/terminology.md#inference-configuration).
 
+#### Usage prerequisites and setup instructions
+
+State the funding requirement, give a short action if needed, and link to the canonical billing page. Prefer "usage balance" and "add usage" to vague conditions such as "sufficient eligible usage." Do not imply that every reader must make a purchase when included usage or a contract allowance may already cover the work.
+
+* **Separate access from funding** - Team membership, plan access, and available usage are different requirements. Keep required access visible; link to its reference rather than copying plan tables.
+* **Match the balance to the workflow** - Use team-balance wording for factory setup. Standalone cloud runs can be individual or team runs; don't add a team requirement to individual workflows. For schedules and API-triggered runs, preserve or link to which user or team is billed.
+* **Keep exceptions with their owner** - Billing pages own balance eligibility, spending controls, charge components, and Enterprise terms. Preserve a condition needed for the current task, but don't duplicate those rules in every prerequisite list. Don't apply standalone integration restrictions to factory integrations without verification.
+* **Preserve technical precision** - "Eligible" can be necessary when distinguishing usable balances in billing references. Keep credit-named UI labels, identifiers, error codes, URLs, and credit-billed contexts; this is not a blanket terminology replacement.
+
+Examples to adapt, not mandatory boilerplate:
+
+* **Factory setup** - "Available usage in your team's balance for factory runs. Add usage if needed. See access and billing requirements."
+* **Individual or team cloud runs** - "Available usage for cloud runs. Add usage if needed. See access and billing requirements."
+* **Scheduled runs** - "Available usage for the user or team billed for the schedule. Add usage if needed. See run identity before choosing which agent runs it."
+
+In published copy, link the billing-reference phrase to the owning page or section. If the funding source or access rule is unverified, ask the product or billing owner; do not invent a uniform policy for consistent wording.
+
+
 ### UI elements
 - **Settings** (capitalized when referring to the Settings panel)
 - **Command Palette** (capitalized)

scripts/test_check_redirects.py

@@ -65,6 +65,23 @@ def test_live_session_sharing_page_has_no_redirect(self):
 
         self.assertEqual(matching_sources, [])
 
+    def test_factory_agent_pages_have_no_redirect(self):
+        routes = (
+            "/factories/factory-agents",
+            "/factories/factory-agents/configuration",
+            "/factories/factory-agents/creating-custom-agents",
+        )
+        redirects = load_redirects()
+        for route in routes:
+            with self.subTest(route=route):
+                self.assertIsNotNone(url_to_content_path(route))
+                for source in (route, route + "/"):
+                    self.assertEqual(
+                        [r["source"] for r in redirects
+                         if redirect_source_matches_path(r["source"], source)],
+                        [],
+                    )
+
     def test_restored_transition_page_has_no_redirect(self):
         route = "/platform/transitioning-from-oz"
         self.assertIsNotNone(url_to_content_path(route))

src/content/docs/agents/capabilities/computer-use/index.mdx

@@ -136,5 +136,5 @@ Computer Use can also help with general web tasks: browsing websites, filling ou
 * [Images as Context](/agents/local-agents/agent-context/images-as-context/) - Pass design mockups and screenshots as context
 * [Full Terminal Use](/agents/capabilities/full-terminal-use/) - Let agents drive interactive terminal apps, see live output, and run commands
 * [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) - Open the cloud run transcript and artifacts after a Computer Use session finishes
-* [Factory agents](/factories/factory-agents/) - Roles and responsibilities for factory agents
+* [About factory agents](/factories/factory-agents/) - Roles and responsibilities for factory agents
 * [Self-hosted agent data storage](/platform/data-storage/) - Storage options for agent run data

src/content/docs/agents/cli/oz-cli/quickstart.mdx

@@ -17,6 +17,11 @@ This guide walks you through the essentials to get up and running with the {VARS
 Watch this short demo of the {VARS.WARP_AGENT_CLI} workflow:
 <VideoEmbed url="https://youtu.be/WpcChBNDCXQ" title={`${VARS.WARP_AGENT_CLI} quickstart video`} />
 
+## Prerequisites
+
+* A [Warp account](https://app.warp.dev/signup).
+* A computer running macOS, Linux, or Windows.
+
 ## 1. Install the CLI
 
 If you already have the [Warp desktop app installed](/getting-started/quickstart/installation-and-setup/), the **CLI is included** and available in Warp.
@@ -67,7 +72,7 @@ What happens:
 
 Cloud agents run in a remote environment with your repositories cloned and dependencies installed, making them useful for tasks that need full codebase access.
 
-If you haven't already created an environment, run `/create-environment` in Warp or follow the [Cloud Agents Quickstart](/platform/quickstart/). Then run the following command:
+If you haven't already created an environment, run `/create-environment` in Warp or follow the [Cloud agents quickstart](/platform/quickstart/). Then run the following command:
 
 ```sh
 oz agent run-cloud --environment <ENV_ID> --prompt "Scan this repo for outdated dependencies"

src/content/docs/agents/cli/quickstart.mdx

@@ -11,8 +11,8 @@ This guide takes you from installing the {VARS.WARP_CLI} to your first agent con
 
 ## Prerequisites
 
-* **A Warp account** - The login step opens your browser, where you can sign in or [create an account](https://app.warp.dev/signup). The CLI uses the same account as the Warp app, but doesn't require the app to be installed.
-* **A supported platform** - macOS (Apple Silicon or Intel), Linux (x64 or Arm64), or Windows (x64 or Arm64).
+* A [Warp account](https://app.warp.dev/signup).
+* A computer running macOS (Apple Silicon or Intel), Linux (x64 or Arm64), or Windows (x64 or Arm64).
 
 ## 1. Install the Warp Agent CLI
 
@@ -63,13 +63,13 @@ To turn off update checks, set `general.autoupdate_enabled` to `false` in the [s
 
 ## 2. Log in
 
-Log in once so the CLI can access your Warp account, models, and saved context. Start the CLI:
+The CLI uses the same account as the Warp app, but doesn't require the app to be installed. Log in once so the CLI can access your account, models, and saved context. Start the CLI:
 
 ```bash
 warp
 ```
 
-The CLI shows a verification link and a device code, and opens the link in your browser. Approve the login there and the CLI unlocks automatically, so you don't need to restart it. If the browser doesn't open, visit the link shown in the CLI and enter the code.
+The CLI shows a verification link and a device code, and opens the link in your browser. Sign in or [create an account](https://app.warp.dev/signup), then approve the login. The CLI unlocks automatically, so you don't need to restart it. If the browser doesn't open, visit the link shown in the CLI and enter the code.
 
 When login completes, the CLI shows its start screen with the version, a short "What's new" list, and the rules, skills, and MCP servers it discovered for your current directory. You stay signed in across sessions. To sign out later, run `/logout`, which returns the CLI to its login screen and signs out your browser session too.
 

src/content/docs/enterprise/support-and-resources/billing.mdx

@@ -37,7 +37,7 @@ Local and cloud usage draw from the shared Enterprise pool. Applicable charges d
 
 Agent API key runs use shared team usage. User-created schedules run as their creator by default, or as a cloud agent when configured to do so. Enterprise funding follows your contract.
 
-For more details, see [Access, Billing, and Identity](/platform/team-access-billing-and-identity/).
+For more details, see [Access, billing, and identity permissions](/platform/team-access-billing-and-identity/).
 
 ## BYOLLM billing
 

src/content/docs/factories/api-and-sdk/index.mdx

@@ -89,6 +89,8 @@ See the [**Python SDK**](https://github.com/warpdotdev/oz-sdk-python) or [**Type
 
 The Conversation API returns skill loads as `read_skill` actions. When `input.bundled_skill_id` is present, it identifies a Warp-provided bundled reference. `input.skill_path` is the path used to resolve a skill, but doesn't prove ownership: file-based skills and path-referenced bundled skills, including skills from a remote host, can both use this field.
 
+To measure team-owned skill usage, exclude actions with `input.bundled_skill_id`. Count a path-only load only after confirming the path belongs to a skill root your team manages, such as the [factory-wide or agent-specific skill directories](/factories/factory-skills/#add-or-edit-a-skill).
+
 The following stable, user-facing IDs are bundled directly with Warp:
 
 | Bundled skill ID | Purpose |

src/content/docs/factories/api-and-sdk/quickstart.mdx

@@ -19,11 +19,13 @@ Watch this short demo of how the REST API can power agent-backed apps like [Powe
 
 ## Prerequisites
 
-* **A Warp API key** - Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> and copy the raw value. Use a personal key if you want runs attributed to you, or an agent key to attribute runs to a [cloud agent](/platform/agents/). See [API Keys](/agents/cli/oz-cli/api-keys/) for the full flow.
-* **A cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don't have an environment yet, follow the [Cloud agents quickstart](/platform/quickstart/) first.
+* A Warp API key from the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP} settings</a>. See [API keys](/agents/cli/oz-cli/api-keys/).
+* A configured [cloud environment](/platform/environments/) with the required repositories and dependencies. See the [Cloud agents quickstart](/platform/quickstart/).
 
 ## 1. Set your API key
 
+Use a personal key to attribute runs to you, or an agent key to attribute them to a [cloud agent](/platform/agents/).
+
 Export your API key so the API can authenticate your requests automatically — all commands in this guide reference the `WARP_API_KEY` environment variable.
 
 ```bash
@@ -94,4 +96,4 @@ You created a cloud agent run over HTTP and tracked it from `QUEUED` to `SUCCEED
 * **Read the endpoint guide** - [Agent & run endpoints](/factories/api-and-sdk/) documents the configuration and run lifecycle, while the [{VARS.WARP_PLATFORM_API} reference](/api) lists all parameters, query filters, and response schemas.
 * **Explore the SDKs** - [`warp-platform-sdk` for Python](https://pypi.org/project/warp-platform-sdk/) and [`@warp-dot-dev/warp-platform-sdk` for TypeScript](https://www.npmjs.com/package/@warp-dot-dev/warp-platform-sdk) include typed request/response models, retries, and error handling.
 * **See a real-world example** - [Demo: Sentry monitoring with SDK](/factories/api-and-sdk/demo-sentry-monitoring-with-sdk/) shows how to build a webhook handler that triggers agents from production errors.
-* **Schedule and automate** - See the [Scheduled agents quickstart](/platform/triggers/scheduled-agents-quickstart/) to run agents on a cron, or the [Integrations quickstart](/platform/integrations/quickstart/) to trigger agents from Slack or Linear.
+* **Schedule and automate** - See the [Scheduled Agents quickstart](/platform/triggers/scheduled-agents-quickstart/) to run agents on a cron, or the [Integrations quickstart](/platform/integrations/quickstart/) to trigger agents from Slack or Linear.

src/content/docs/factories/api-and-sdk/troubleshooting/errors/agent-process-failed.mdx

@@ -58,6 +58,6 @@ This error is returned when:
 
 ## Related
 
-* [Cloud Agents Overview](/platform/) — How cloud agent tasks work
+* [Cloud agents overview](/platform/) — How cloud agent tasks work
 * [environment_setup_failed](/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/) — Errors during environment setup
 * [internal_error](/factories/api-and-sdk/troubleshooting/errors/internal-error/) — Catch-all for unexpected server-side errors

src/content/docs/factories/api-and-sdk/troubleshooting/errors/budget-exceeded.mdx

@@ -55,4 +55,4 @@ If you are not a team admin, contact your team admin to adjust the budget.
 
 ## Related
 
-* [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) — Budget configuration and billing details
+* [Access, billing, and identity permissions](/platform/team-access-billing-and-identity/) — Budget configuration and billing details

src/content/docs/factories/api-and-sdk/troubleshooting/errors/conflict.mdx

@@ -57,5 +57,5 @@ For task cancellation specifically, wait until the task moves from **pending** t
 
 ## Related
 
-* [Managing Cloud Agents](/platform/managing-cloud-agents/) — Viewing and managing agent tasks
+* [Managing cloud agents](/platform/managing-cloud-agents/) — Viewing and managing agent tasks
 * [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) — API reference for managing agent tasks

src/content/docs/factories/api-and-sdk/troubleshooting/errors/content-policy-violation.mdx

@@ -57,5 +57,5 @@ For security reasons, the error message is intentionally generic and does not de
 
 ## Related
 
-* [Cloud Agents Overview](/platform/) — How cloud agent tasks work
+* [Cloud agents overview](/platform/) — How cloud agent tasks work
 * [Environments](/platform/environments/) — Configuring setup commands

src/content/docs/factories/api-and-sdk/troubleshooting/errors/feature-not-available.mdx

@@ -50,11 +50,11 @@ The `title` field in the response will describe the specific feature that is una
 2. Upgrade to a plan that includes the required feature.
 3. Retry the operation.
 
-For plan comparisons and feature availability, see [Access, Billing, and Identity](/platform/team-access-billing-and-identity/).
+For plan comparisons and feature availability, see [Access, billing, and identity permissions](/platform/team-access-billing-and-identity/).
 
 ---
 
 ## Related
 
-* [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) — Plan requirements and feature availability
+* [Access, billing, and identity permissions](/platform/team-access-billing-and-identity/) — Plan requirements and feature availability
 * [Integrations](/platform/integrations/) — Integration requirements by plan

src/content/docs/factories/api-and-sdk/troubleshooting/errors/index.mdx

@@ -81,5 +81,5 @@ When an error response includes a `trace_id`, you can include it when [contactin
 ## Related pages
 
 * [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) — API reference for creating and managing agent tasks
-* [Cloud Agents Overview](/platform/) — How cloud agents work
-* [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) — Plan requirements and billing details
+* [Cloud agents overview](/platform/) — How cloud agents work
+* [Access, billing, and identity permissions](/platform/team-access-billing-and-identity/) — Plan requirements and billing details

src/content/docs/factories/api-and-sdk/troubleshooting/errors/infrastructure-timeout.mdx

@@ -58,6 +58,6 @@ This error is returned when:
 
 ## Related
 
-* [Cloud Agents Overview](/platform/) — How cloud agent tasks work
+* [Cloud agents overview](/platform/) — How cloud agent tasks work
 * [internal_error](/factories/api-and-sdk/troubleshooting/errors/internal-error/) — Other platform-level errors
 * [Cloud Agents FAQs](/platform/faqs/) — Common questions about cloud agents