docs(billing): define agent hours for platform credits and refresh stale language

[hongyi-chen]

Summary

Sales needs the platform credits docs to state that platform credits are calculated from agent hours, with a clear definition. The term appeared nowhere in the docs. This PR adds the definition to the platform credits page and echoes it on the three sibling billing pages, refreshes stale preview-period language now that platform-credit billing is live (prod has been in charge mode since July 1, 2026), and de-slops the prose per the AGENTS.md voice rules.

Behavior claims were verified against the warp-server billing code (logic/ai/ambient_agents/billing/platform.go, specs/REV-1551/TECH.md) and the sandbox driver in the warp client (app/src/ai/agent_sdk/driver.rs): platform credits accrue per minute of wall-time from when the agent starts in its environment (the driver reports IN_PROGRESS before environment setup and MCP startup, so setup is inside the billed window) until the run ends or pauses for input. Queue and sandbox-provisioning time before the agent starts, waiting-on-input time, and idle time aren't billed. Exact rates stay deferred to warp.dev/pricing (per-tier and still tuned server-side).

Changes

The plans-and-billing pages live in src/content/docs/support-and-community/plans-and-billing/.

platform-credits.mdx

• Added agent hours to the intro, frontmatter description, and the "How platform credits are measured" section, which now leads with the definition: the clock starts when the agent starts in its environment (including environment setup) and stops when the run finishes, fails, is cancelled, or pauses for input; queued time, waiting-on-input time, and idle time excluded; exact time billed, not rounded to whole hours.
• De-duped the intro against "The three credit buckets" (the bucket breakdown and the independence sentence appeared twice on one page); kept the #the-three-credit-buckets anchor, which three other pages link to.
• Cut AI-isms: em-dash chains, "regardless of" ×3, "Warp's platform infrastructure" ×6, triple-parallel constructions, and the "Learn when they apply" filler description.

credits.mdx

• Platform credits section now leads with the agent-hours definition; aligned the platform-layer wording with the platform credits page (dropped stray "scheduling").
• Compute credits section now covers Enterprise self-hosted workers: those cloud runs never consume compute credits (the server rejects compute charges for self-hosted runs) but do consume platform credits. Broadened the integrations list beyond Slack and Linear.
• Normalized the heading hierarchy (the page started at H3 with H4 subsections and bold inside headings; now H2/H3, plain). Anchor slugs are unchanged.
• Replaced the versioned model ranking (Opus 4.7, Sonnet 4.6, GPT-5.5...) with a non-drifting statement; it was already behind the pricing page.
• Fixed "Warp's Agent" terminology and lowercased generic "agent" in the edited sentences.
• Fixed style-lint findings on the page: added standard maxWidth to the usage-footer screenshot, replaced the filler-opener frontmatter description.

pricing-faqs.mdx

• "How do platform credits factor in?" now mentions agent-hours metering and drops the stale preview-period framing.
• Removed the "When do platform credits start being charged on self-serve plans?" question entirely — billing started July 1, 2026, so it no longer earns an entry. All links that pointed at its anchor were retargeted first, and the link checker confirms none remain.
• Updated the BYOK/custom-endpoint bullets and the admin checklist to current-state language; fixed pre-existing tone-buzzword lint findings ("unlocks powerful", "allow you to", "designed to").
• Changed "don't consume Warp credits" to "don't consume AI credits" in the four BYOK/custom-endpoint answers that go on to say platform credits apply. Platform credits are Warp credits, so the old wording contradicted itself within the same answer. (The BYOK and custom-endpoint feature pages already say "AI credits".)

add-on-credits.mdx

• Fixed an inverted claim: "Add-on credits draw from the same pool as platform credits and compute credits" conflated a credit source with usage types. Now: add-on credits can be spent on any credit type.
• Cut two restated cause-and-effect sentences, removed bold from a heading, and wrapped the screenshot in a standard-width figure with accurate alt text.

index.mdx and plans-pricing-refunds.mdx

• Platform credits entries now say "billed by the agent hour" and name both charged scopes. Replaced the "Learn about..." filler description on the plans page.

enterprise/support-and-resources/billing.mdx

• "Cloud agent billing" now notes platform credits are billed by the agent hour, that self-hosted-worker runs skip compute credits but not platform credits, and links to the platform credits page; replaced the meta-opener and filler-opener description flagged by style lint.

Content design plan

Audience and JTBD: A prospect or customer in a sales conversation (and the account team supporting it) who needs to understand what platform credits are and how they're calculated.

Problem: The docs described the metering behavior but never named or defined "agent hours", the term sales uses; the pricing FAQs still described the pre-July-2026 preview period in present tense.

Content type: Update to existing feature/FAQ pages — no new page.

Unverified claims

None — metering behavior (including the agent-hour start boundary), charge eligibility, the self-hosted compute exemption, and billing-start dates were verified against warp-server source (logic/ai/ambient_agents/billing/platform.go, logic/ai/ambient_agents/finalization.go, model/types/billing.go, config/prod.yaml, specs/REV-1551/TECH.md) and the warp client (app/src/ai/agent_sdk/driver.rs, app/src/settings_view/billing_and_usage/billing_cycle_usage_common.rs).

Follow-ups not in this PR

• reload-credits.png (add-on credits page) shows an internal test account email and a "5 credits / 99% off" test pack. Worth re-capturing from a clean account.
• credits.mdx still has 7 callouts (mostly per-factor "Tip" notes); folding them into body prose is a bigger restructure than this PR.
• "Slack and Linear integrations require team membership" on credits.mdx predates the GitHub, GitLab, Bitbucket, Azure DevOps, and Jira integrations; not verified here.

Validation

• style_lint --changed: no findings on changed content (remaining findings are pre-existing: page-wide callout density, proper-noun header-case false positives, glossary suggestions for bolded link text).
• check_for_broken_links --internal-only: 3,966 internal links, 0 broken. Heading-level changes on credits.mdx don't alter slugs.
• npm run build: passes.

Plans:

• Platform credits docs: agent hours definition + refresh

Co-Authored-By: Warp agent@warp.dev

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Sep 2, 2026 1:07am UTC

[hongyi-chen]

This PR was generated with Warp.

Comment @warp-agent on this PR to send it follow-up work.

 

[warp-local-for-testing-only]

Your GitHub account is not connected to Warp. Connect it here.

[warp-for-oss]

@hongyi-chen

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[warp-for-oss]

Overview

This PR updates billing documentation to define agent hours for platform credits, refresh platform-credit billing language after the preview period, and tighten related prose across the billing pages. I reviewed the changed docs against the attached diff, docs style guidance, security checklist, and the provided spec context; no approved implementation spec was available for drift checks.

Concerns

• No blocking concerns found.
• Comment audit: the diff does not add code comments or documentation comments that violate repository conventions.
• Test audit: the diff does not add or change tests.

Verdict

Found: 0 critical, 0 important, 0 suggestions

Approve

Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[warp-factories]

Overview

Refreshes the platform-credits docs to define "agent hours," updates stale preview-period language now that billing is live, and trims AI-ism prose across four billing/credits pages. No correctness issues found; recommend merging as-is.

Concerns

• Four pre-existing instances of "Warp's platform infrastructure" remain in the very pages this PR is refreshing to "platform layer" terminology (pricing-faqs.mdx:326,336 and enterprise/support-and-resources/billing.mdx:46,91, all outside the diff). Not introduced by this change, but worth a follow-up pass for full terminology consistency on these pages.

Verdict

Checks: build pass, internal links 3968/3968 pass (0 broken), style_lint --changed clean (all 10 reported findings are pre-existing/false-positive, none on changed lines), visual proof n/a (docs-only prose change)

Found: 0 critical, 0 important, 1 suggestion, 0 nits

Responding as revops-factory: Open session · View factory task

[hongyi-chen]

this will update with pricing transparency, but this is still accurate today