docs: clarify pricing transparency and usage billing

.agents/references/terminology.md

@@ -111,6 +111,16 @@ For the summary of the most critical terms (core features, Automation Platform t
 - **Full Terminal Use** — The capability that lets an agent attach to and drive interactive terminal programs (for example `psql`, `vim`, a dev server) by reading live PTY output.
   *Usage note:* Capitalize as a feature name, including in headings.
 
+## Inference configuration
+
+- **personal BYOK** — Provider API keys configured on a user's device for local Warp Agent runs. App and CLI keys are configured separately. Use "personal" when distinguishing these keys from team-managed BYOK.
+- **personal custom inference endpoint** — An OpenAI-compatible endpoint configured on a user's device for local Warp Agent runs. Distinguish it from an endpoint configured by a team admin.
+- **team-managed API keys and endpoints** — Shared provider configuration that Business and Enterprise admins manage centrally for local and cloud Warp Agent runs. Warp stores the credentials securely; personal-device storage guarantees do not apply.
+- **connected subscription** — A provider subscription connected through its own authentication flow, not a provider API key. Verify its model, surface, cloud, billing, and retention support separately from BYOK.
+- **third-party harness credentials** — Credentials used by a harness such as Claude Code or Codex. Don't infer their storage or cloud support from personal Warp Agent BYOK behavior.
+
+Use local versus cloud to describe where a run executes, and interactive versus unattended to describe how the user participates. A local CLI run can be unattended; "interactive requests only" is not a substitute for "local runs only."
+
 ## Coding terms (Warp features)
 
 - **Code** — Warp's coding experience for agent-assisted changes (editing, diffs, code review).
@@ -394,7 +404,7 @@ Docs match the screen; the fix belongs in the app.
 - **macOS** — not "Mac OS" or "Mac"
 - **Zero Data Retention (ZDR)** — Warp's agreements with contracted LLM providers not to train on or retain customer data. Capitalize as a proper term, including in headings ("Zero Data Retention (ZDR)"); keep the "(ZDR)" acronym on first mention in a section.
 - **SSO (Single Sign-On)** — Authentication through an organization's identity provider (Okta, Microsoft Entra ID, Google Workspace, or any SAML 2.0/OIDC provider). Always capitalize the acronym "SSO"; capitalize "Single Sign-On" when spelled out as the feature name.
-- **Bring Your Own LLM (BYOLLM)** — Warp Enterprise's routing of agent inference through a customer's own cloud infrastructure (AWS Bedrock or Google Cloud via Gemini Enterprise). Capitalize as a proper feature name, including in headings; keep the "(BYOLLM)" acronym on first mention in a section. Distinct from BYOK (Bring Your Own API Key), a self-serve, user-level feature.
+- **Bring Your Own LLM (BYOLLM)** — Warp Enterprise's routing of agent inference through a customer's own cloud infrastructure (AWS Bedrock or Google Cloud via Gemini Enterprise). Capitalize as a proper feature name, including in headings; keep the "(BYOLLM)" acronym on first mention in a section. Distinct from provider API-key BYOK, which can be personal or team-managed. Verify cloud support for each BYOLLM provider rather than treating them as interchangeable.
 
 ## Branded and informal terms
 
@@ -423,14 +433,24 @@ Docs match the screen; the fix belongs in the app.
 
 ## Billing and credits
 
-- **Add-on Credits** — capitalized as a product feature name
-- **Auto-reload** — the setting that automatically purchases another add-on credit pack when a user's balance drops below 100 credits. Hyphenated; capitalize the first letter only at the start of a sentence, bullet, or bolded list term.
-- **team-wide spend cap** — the admin-configured monthly ceiling on add-on credit spending across a whole team. Use instead of "budget" or "credit limit" when describing the cap. The per-account wording "monthly spend limit" refers to the same setting in single-user contexts.
-- **compute credits** — lowercase common noun; capitalize the first letter only at the start of a sentence or bullet. The compute bucket, consumed when an agent run uses Warp-hosted compute. Use alongside AI credits and platform credits when describing credit types.
-- **cloud agent credits** — lowercase common noun; capitalize the first letter only at the start of a sentence or bullet. Credits consumed by cloud agents, in contrast with local agent credits. Refers to the same compute bucket as compute credits; choose the term that fits the framing.
-- **platform credits** — lowercase common noun; capitalize the first letter only at the start of a sentence or bullet. The platform-infrastructure bucket, consumed for every cloud agent run plus local runs with customer-supplied inference.
-- **credits** — the unit of usage for AI features in Warp (lowercase, not "AI credits")
-- **Warp credits** — credits included with a subscription plan. Use in user-facing copy rather than "plan 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.
+- **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.
+- **purchase premium** — an additional payment cost when buying usage. Distinguish it from inference rates; don't describe it as an extra multiplier on each model call.
+- **Add-on Credits** — preserve this exact capitalization when quoting a shipped UI label or referring to a purchase shown in credits. Use "purchasing additional usage" for general guidance.
+- **auto-reload** — purchases the selected usage amount when the available balance runs low, subject to purchase controls. Do not make a credit threshold universal across billing units.
+- **monthly spend limit** — the team's control on additional usage purchases and auto-reloads. Match **Monthly spend limit** in UI instructions and preserve legacy anchors that use "monthly purchase limit." It is not an Enterprise consumption cap, a limit on spending an existing balance, or a guaranteed ceiling on payments or the whole invoice.
+- **Enterprise spending limits** — contract-specific controls on cloud, local, total, and per-user usage. Don't describe self-serve purchase controls as these separate consumption limits.
+- **compute usage** / **platform usage** — charge components, not necessarily separate balances. Platform usage measures billable agent time.
+- **credits**, **compute credits**, **cloud agent credits**, **platform credits**, **Warp credits** — use when an account bills in credits, for credit display units, and for exact UI labels. Keep common nouns lowercase; do not use the "AI credits" prefix.
+- **public identifiers** — retain credit-named API fields, error codes, CLI labels, and published URLs. A billing-unit change is not an identifier rename.
+
+### Billing usage notes
+
+- Keep current prices and purchase amounts on [Warp pricing](https://www.warp.dev/pricing). Link from the canonical billing pages; summaries and FAQs link to those pages rather than copying tables or contract rules.
+- Use "conversation usage" for the concept, and quote **Credit usage** when identifying the `/statusline` item. A credits/dollars display preference changes presentation, not charges, and isn't available on every account or surface.
+- Keep inference rates, purchase prices, included allowances, and recorded usage charges separate. "Public API rates" describes Warp-provided inference on eligible plans, not every cost on the invoice.
 
 ## External product names
 

AGENTS.md

@@ -27,6 +27,8 @@ Describe what the reader sees and does. Internal components get at most one sent
 - ✅ "Warp tracks every run. Check its status from the CLI, the API, or the dashboard."
 - ❌ "The orchestration layer runs on Warp's servers (cloud control plane), creates tasks when triggers fire, and tracks lifecycle state (created → running → completed/failed)."
 
+Apply a reader-value test to technical detail: does it help someone choose, configure, verify, diagnose, or understand a charge or security boundary? Credential storage and request transit can inform a security decision; backend assembly steps, billing constants, internal feature flags, and implementation provenance usually don't. Keep verification evidence in the PR rather than narrating it in public prose.
+
 #### Order from intent to technical detail
 
 When readers need exact fields, IDs, or runtime labels, order the explanation from intent to implementation:
@@ -73,7 +75,7 @@ AI-drafted pages share a rhythm. Break it.
 - **Rhetorical question openers** - Don't open a section with a question you immediately answer. Use a descriptive header and a declarative first sentence.
 - **Hedging stacks** - Chains of "typically", "often", "generally", "where supported", and "as applicable" read as evasive. State what happens, then note the exception if there is one.
 - **Bold-everything** - Bolding several phrases per paragraph kills emphasis. Reserve bold for UI elements and lead terms of list items (see Emphasis).
-- **Bullets as a substitute for prose** - Bullets are for short, parallel, scannable items. If every bullet is a full paragraph, or the bullets tell a story in order, write prose.
+- **Bullets as a substitute for prose** - Bullets are for short, parallel, scannable items. If every bullet is a full paragraph, or the bullets tell a story in order, write prose. Connect a cause to its remedies, then explain the exception separately. A balance-exhaustion answer needs recovery options, not an unrelated token-limit caveat.
 - **Slashed shorthand** - Write "mentions and assignments", not "mention/assignment", and "4 vCPU / 8 GB", not "4/8". Slashed pairs and bare number pairs read as notes, not prose.
 - **Callout spam** - Callouts follow the same restraint: never consecutive, at most one per section (see Callouts and hints).
 
@@ -522,6 +524,7 @@ These rules apply regardless of content type:
 - **Don't over-specify counts or internals that will drift**: Describe a capability rather than naming an exact count of tools, steps, or subcomponents behind it (e.g., "a small set of tools" instead of "ten tools"). Precise counts go stale the moment the implementation changes, and a stale number is worse than no number.
 - **Feature real differentiators structurally**: If a capability is a genuine advantage over the default path (an agent- or API-driven alternative to a UI flow, for example), give it real visual weight — a clear callout near the top of the relevant section, not a footnote after the primary steps are already done. Where something sits on the page communicates how important it is.
 - **Verify claims against the live product, not just prior drafts**: Terminology, UI labels, and calculated values drift between rounds of review. Confirm names, labels, and metric definitions against the actual app, API, or codebase before publishing — especially for pages describing metrics or anything computed.
+  - Record the source revision separately from deployment, stable-release, and live-checkout evidence. Merged code or checked-in production configuration does not prove that a customer can use a feature. Keep uncertain availability or policy claims conditional, omitted, or explicitly recorded for review.
 - **Preserve page purpose**: Removing a page or changing its purpose requires human approval. An unsupported claim calls for a narrow correction, not permission to turn a transition guide into a chooser. Record the reader task, ownership across sibling pages, repetition removed, and useful understanding preserved in the editorial verdict.
 - **Use one positioning source**: Follow `.agents/rules/oz-style-guidelines.md` for product framing and `.agents/references/terminology.md` for names. Positioning is demonstrated through relevant workflows, not mandatory slogans.
 
@@ -923,13 +926,19 @@ See `.agents/references/terminology.md` → "Warp Factories terminology" for the
 - **macOS** (not "Mac OS" or "Mac")
 
 ### Billing and credits
-- **credits** (lowercase, not "AI credits") - the unit of usage for AI features in Warp
-- **Add-on Credits** (capitalized as a product feature name)
-- **compute credits** (lowercase common noun; capitalize the first letter only at the start of a sentence or bullet) - the compute bucket; consumed when an agent run uses Warp-hosted compute. Used alongside AI credits and platform credits when describing credit types.
-- **cloud agent credits** (lowercase common noun; capitalize the first letter only at the start of a sentence or bullet) - credits consumed by cloud agents (in contrast with local agent credits). Refers to the same compute bucket as compute credits; pick the term that fits the framing.
-- **platform credits** (lowercase common noun; capitalize the first letter only at the start of a sentence or bullet) - the platform-infrastructure bucket
-- **Warp credits** - credits included with a subscription plan. Use in user-facing copy rather than "plan credits."
-- Use "credit" or "credits" without the "AI" prefix throughout documentation
+- **usage** - the general term for metered inference, Warp-hosted compute, and platform activity. Explain the billing unit where it affects the reader's task, not in every paragraph. Name plans naturally: "Free," "Build," "Max," "Business," and "Enterprise," not "dollar-billed Free" or "self-serve dollar Max."
+- **included usage** / **purchased usage** - distinguish the monthly allowance from additional usage purchases and contract-specific pools.
+- **dollar usage** - a usage balance, not the subscription price or necessarily the amount paid for a purchase.
+- **credits** (lowercase, not "AI credits") - use when an account bills in credits, for credit display units, and for exact product labels.
+- **Add-on Credits** - preserve the exact capitalization when quoting a shipped UI label or a purchase shown in credits.
+- **compute usage** / **platform usage** - charge components, not necessarily separate allowances. Use credit-named terms when an account bills in credits.
+- Keep credit-named public identifiers, error codes, CLI labels, and URLs unchanged. See `.agents/references/terminology.md` for purchase-limit and display-unit guidance.
+
+Current prices belong on [Warp pricing](https://www.warp.dev/pricing), not in duplicate purchase tables. The billing pages own charge components, purchase controls, and contract exceptions; FAQs summarize and link to those owners. Distinguish the inference rate, a purchase premium, the usage balance, and the amount paid. A purchase premium is not a second inference-rate multiplier.
+
+Match a control's shipped label without letting that label define all surrounding prose. For example, explain "conversation usage," then identify **Credit usage** as the item in `/statusline`. A documentation edit does not rename a product control or public identifier.
+
+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).
 
 ### UI elements
 - **Settings** (capitalized when referring to the Settings panel)
@@ -1035,6 +1044,7 @@ Before publishing any documentation, verify:
 3. **Consistency**: Check terminology and formatting against this guide
 4. **User focus**: Ensure content answers "what can I accomplish?" before "how does it work?"
 5. **Completeness**: Include necessary context, examples, and next steps
+6. **Review patterns**: Treat each comment as a possible pattern, not only a line edit. Check the canonical page, related tables, FAQs, procedures, and local-to-cloud guidance for the same problem; update warranted matches without a blanket terminology replacement. Record reusable lessons in this guide or the glossary, rather than in public product prose.
 
 # Agent-specific guidance
 

src/content/docs/agents/capabilities/full-terminal-use.mdx

@@ -188,29 +188,17 @@ These settings apply to every session that uses Full Terminal Use. You can still
 **Note**: All [Secret Redaction](/support-and-community/privacy-and-security/secret-redaction/) features still apply during Full Terminal Use, so sensitive values in your environment or output remain protected.
 :::
 
-### Credits usage
+<span id="credits-usage" />
 
-All AI interactions from Full Terminal Use consume [credits](/support-and-community/plans-and-billing/credits/), including understanding your natural language requests.
+### Usage
 
-Credits are consumed in a similar way as other Warp actions that use the same model and a similar context size.
+Agent interactions during Full Terminal Use follow [standard usage billing](/support-and-community/plans-and-billing/credits/).
 
-**Interactive sessions can consume more credits if:**
+Interactive sessions can consume more usage if the agent runs many commands on your behalf or has a lot of terminal output to read and summarize.
 
-* The agent runs many commands in an interactive shell on your behalf.
-* There is a significant amount of terminal output to read and summarize.
+For example, asking the agent to explain an entire database can involve more work than asking it to describe the orders table. If you're running a large batch or reading long logs yourself, you can take manual control and hand control back when you want the agent's help again.
 
-**To manage credit usage:**
-
-* Use tighter scopes:
-  * “Describe just the orders table.” instead of “Explain the entire database.”
-* Pause autonomy for high-volume tasks with copious terminal output:
-  * Take over manual control when running large batches or long logs.
-* Use stricter permissions:
-  * Set global permissions to "Ask on first write" or "Always ask", then approve only what you need.
-
-:::note
-To learn more about what goes into a credit and how to get more value from AI usage in Warp, see: [_Getting the most out of credits in Warp_](https://www.warp.dev/blog/warp-ai-requests).
-:::
+You can also use **Ask on first write** or **Always ask** to choose when the agent needs your approval.
 
 ## Example workflows