Audit pass 2: factual corrections, terminology unification, style cleanup#99
Merged
Merged
Conversation
…anup Comprehensive pass over the orchestration-launch branch to catch content issues that wiring-focused audit #97 left behind. Factual corrections: - agents.mdx: drop 'getAgent' from the operationId list and remove the 'Retrieve - GET /agent/identities/{uid}' bullet. The OpenAPI spec (developers/agent-api-openapi.yaml) only ships createAgent / listAgents / updateAgent / deleteAgent under the /agent/identities path; there is no single-resource GET. - agents.mdx: replace 'pass the identity\'s UID to the generateApiKey mutation' with 'choose the identity when creating the team API key'. No generateApiKey mutation exists in the OpenAPI, and api-keys.mdx describes a UI-driven creation flow. - agents.mdx: drop the ('Quick run' in the web app) parenthetical from the default-identity fallback note. oz-web-app.mdx defines Quick run as user-attributed ('runs as your own user'), so equating it with the default agent identity contradicts the rest of the docs. Terminology unification (post three-bucket / agents-launch model): - harnesses/index.mdx, claude-code.mdx, codex.mdx: replace the vague 'Warp credits cover the orchestration platform' wording with the explicit three-bucket framing 'Warp meters compute credits for the run\'s sandbox and platform credits for the orchestration layer'. - team-access-billing-and-identity.mdx: rename every 'Reload Credits' / 'Reload Credit pool' / 'Reload Credit balance' reference to the canonical 'Add-on Credits' (5 spots, including the parenthetical '[Reload Credits (Add-on Credits)](...)'). - oz-web-app.mdx: rename the page title and 6 image alt texts from 'Oz Web App' (Title Case) to 'Oz web app' to match the canonical glossary entry and the sidebar label. Style guide cleanup: - secrets.mdx: drop a trailing ' ' GitBook artifact, replace 'just references it by name' with 'only references it by name', and backtick the bare 'oz secret' in 'oz secret command family'. - harnesses/authentication.mdx: replace 'just like any other Warp- managed secret' with 'like any other Warp-managed secret'. - deployment-patterns.mdx: drop 'just' from 'and you just need a reliable, cloud-connected agent runner'. - cloud-agents/overview.mdx: lowercase two H4 headings ('For Cloud Agents via CLI/API' -> 'For cloud agents via CLI/API'; 'For Integrations (Slack/Linear)' -> 'For integrations (Slack/Linear)') per the sentence-case style guide. Validation: - check_links --internal-only: 0 broken across 2,501 internal links (up 6 from the 2,495 baseline, matching the new compute-credits / platform-credits anchors added in the harnesses billing sections). - style_lint --changed: only pre-existing proper-name false positives in pricing-faqs.mdx (Build / Business / Pro / Turbo / Lightspeed / Add-on Credits headings). - npm run build: 326 pages built; sidebar compiles; new anchor and slug references resolve. Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
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 Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Overview
This PR makes focused documentation corrections across the cloud agent docs: removing stale agent identity API references, aligning billing terminology with Add-on Credits/platform credits wording, and cleaning up Oz web app and style-guide terminology.
Concerns
- No blocking concerns found in the attached diff.
- No approved spec context was available for implementation/spec validation.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
hongyi-chen
added a commit
that referenced
this pull request
May 19, 2026
…ent identities (#98) * docs(agent-platform): add agent identities page and expand secrets + web-UI coverage (#88) * docs(agent-platform): add named agents page and cross-link from related pages Adds a new dedicated page for named agents (agent identities) under cloud agents, and reconciles a handful of existing pages so that automation guidance and service-account references point to the new page. - New: src/content/docs/agent-platform/cloud-agents/agents.mdx — what a named agent is, plan limits, attaching descriptions/secrets/skills, REST endpoints, API keys bound to a named agent, running as a specific identity, and where named agents surface in the product. - Edit: agent-platform/cloud-agents/secrets.mdx — forward-links from the team-secrets recommendation and adds a brief note that secrets can be attached directly to a named agent. - Edit: agent-platform/cloud-agents/deployment-patterns.mdx — Pattern 1 checklist now references a named agent (recommended for automation) instead of an unscoped "service account". - Edit: agent-platform/cloud-agents/oz-web-app.mdx — reconciles the two meanings of the Agents page (skills browser + named-agent management) with a clear section split and a forward link. - Edit: reference/cli/index.mdx — keeps the literal `oz whoami` output intact and adds a one-line note pointing readers to the new agents page for what a service-account principal represents. - Edit: reference/cli/federate.mdx — keeps the literal `service_account:my-sa-id` example and adds a cross-reference to the new agents page. Hard rules: no edits to sidebar.ts, vercel.json, landing pages, or any pages owned by the five orchestration-launch PRs. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(agent-platform): rename to agent identities; expand secrets and web-UI coverage Revises the previous "named agents" page and related cross-links to use "agent identity" consistently, and folds in three product surfaces that land alongside agent identities at launch. - agents.mdx: retitled to "Agent identities" and reframed throughout to use the canonical term. Plan-limit table replaced with a single sentence pointing readers to warp.dev/pricing while preserving the default-identity / over-limit visibility behavior. Adds two new subsections: a service-account-to-agent-identity mapping (covers service_account:<uid> in oz whoami and oz federate) and a rationale paragraph for supporting multiple identities (CI, on-call, scheduled jobs). - secrets.mdx: new "Creating secrets in the Oz web app" walkthrough alongside the existing oz secret CLI section. New "Scoping secrets to environments and runs" section covering environment-level scoping and run-level scoping (default-inherit / explicit list / empty-list opt-out), with cross-links to environments and the Oz API reference. Terminology references updated. - oz-web-app.mdx: adds Secrets to the quick-reference table, reframes the Agents-page disambiguation to use "agent identity," and adds a step-by-step walkthrough of the New agent side pane (name, description, prompt, skills, harness, model, harness auth secret, secrets, memory stores). Cross-links to agents.mdx for the conceptual reference. - deployment-patterns.mdx: Pattern 1 checklist now references "an agent identity." - reference/cli/index.mdx and reference/cli/federate.mdx: leave literal CLI output intact; one-line notes tying service_account principals to agent identities, with cross-links to agents.mdx. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(secrets): fix two 'an cloud' → 'a cloud' grammar typos Pre-existing grammar slips picked up during the agent-identities PR audit. 'Cloud' starts with a consonant sound, so the article 'a' is correct. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(agent-identities): address audit findings - secrets.mdx: rephrase environment-level scoping as a default contribution to the run's allowlist (not a cap); drop the CLI environment-secret attachment claim; make the env-secret section self-contained with a web-UI walkthrough and attachment semantics - oz-web-app.mdx: fix the "Oz harness" noun-phrase slip in the base-harness bullet; drop the availability hedge on the memory-stores bullet while keeping the bullet Co-Authored-By: Oz <oz-agent@warp.dev> --------- Co-authored-by: Oz <oz-agent@warp.dev> * docs(cloud-agents): add multi-harness pages (Warp Agent, Claude Code, Codex) (#87) * docs(cloud-agents): add multi-harness pages for Oz orchestration launch Add a new harnesses section under agent-platform/cloud-agents documenting the harnesses available inside Oz (Warp Agent, Claude Code, Codex), plus a procedural authentication page for connecting Anthropic and OpenAI credentials. Add 'two contexts' callouts to the existing CLI-agent pages distinguishing the local terminal toolbelt from the cloud orchestration surface, and cross-link to the new harness pages. New pages: - agent-platform/cloud-agents/harnesses/index.mdx (overview) - agent-platform/cloud-agents/harnesses/warp-agent.mdx - agent-platform/cloud-agents/harnesses/claude-code.mdx - agent-platform/cloud-agents/harnesses/codex.mdx - agent-platform/cloud-agents/harnesses/authentication.mdx Edited pages: - agent-platform/cli-agents/overview.mdx (two-contexts callout) - agent-platform/cli-agents/claude-code.mdx (cross-link) - agent-platform/cli-agents/codex.mdx (cross-link) - agent-platform/cli-agents/opencode.mdx (fast-follow note) Sidebar wiring is intentionally deferred to the cross-cutting sidebar PR per the orchestration launch tracker. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(harnesses): address PR #87 feedback, reframe "Oz harness" terminology - Retitle harness pages to "Warp Agent with Oz", "Claude Code with Oz", "Codex with Oz"; index becomes "Harnesses in Oz". Update body copy and cross-references in cli-agents/* to match. - Reconcile billing claim: customer-supplied Anthropic and OpenAI API keys mean the provider bills your account directly for inference; Warp credits cover the platform layer only. Apply across overview, Claude Code, Codex, and authentication pages. - Remove ChatGPT-auth ambiguity from Codex model list; "default" now reads as "Codex picks its own recommended model" with no provider- account claim that does not match cloud auth options. - Qualify launch surfaces accurately: Warp terminal harness dropdown lists Warp Agent, Claude Code, Gemini today (no Codex); Oz CLI accepts --harness oz|claude|gemini today (Codex is fast-follow); Oz web app and API/SDK expose all four harnesses. Mark Codex CLI selection as fast-follow in the Codex page and authentication page. - Add conservative framing for Gemini and OpenCode harnesses on the overview. - Strip internal field-name jargon from user-facing examples. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(harnesses): drop OpenCode mentions, simplify CLI cross-link, audit implementation detail Address Slack-thread feedback on PR #87: - Drop OpenCode from the harnesses overview roadmap note and remove the OpenCode-in-Oz callout from cli-agents/opencode.mdx. OpenCode is no longer mentioned anywhere in the harness docs. - Replace the six-sentence 'two contexts' callout on cli-agents/overview with a two-sentence note: Claude Code and Codex are also supported as harnesses in Oz. The matching callouts on cli-agents/claude-code and cli-agents/codex shrink to the same shape. - Audit pass for over-explanation: harness 'How it works' sections drop Docker / cli-invocation walk-throughs in favor of user-facing copy; Claude and Codex model lists trim in-product aliases (opus[1m], sonnet[1m], opusplan, gpt-5.3-codex-spark, etc.) and defer to the picker for the full list; 'What stays the same' bullets lead with the user benefit; the authentication intro and BYOK callouts drop 'cloud container' / 'injected at runtime' phrasing. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(harnesses): address audit findings - Replace "the default Oz harness" with "Oz's default harness" in Related-pages bullets to avoid the "Oz harness" noun-phrase. - Sweep "on Oz" → "with Oz" across harness page descriptions and body copy. - Drop preview/fast-follow hedges around Codex CLI launch and the Warp app's harness dropdown — treat as launching at GA. - Rewrite "GPT-5.5 family" as "the GPT-5 lineup" and drop gpt-5.5 from the cloud Codex Common picks (gpt-5.5 is ChatGPT-auth only; cloud Codex authenticates with an OpenAI API key). gpt-5.4 is now framed as the recommended cloud Codex default. - Add the \`best\` alias to the Claude Code Common picks list with a note that it resolves to the current top-of-line Claude model. Co-Authored-By: Oz <oz-agent@warp.dev> * Tweaking copy * docs(harnesses): copy polish on Lili's tweaks - Fix broken `[H]` link in cloud Claude Code Related pages. - Fix "OpenA credential type" typo in authentication.mdx. - Clean up Anthropic Console URL (drop ?returnTo=/? query string). - Capitalize "OpenAI Platform" to match "Anthropic Console". - Restore --team in CLI examples so the follow-up sentence parses. - Drop word-repeat in harnesses index ("harness from the harness dropdown"). - Switch backtick `Cloud Agent` to bold (UI/tab name per style guide). - Reword dangling preposition in Codex available-models bullet. - Trim trailing whitespace and a double-blank line. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(harnesses): second polish pass on multi-harness pages - Fix link-text/URL mismatch in harnesses overview: link reads 'triggers' but pointed to /integrations/; repoint to /triggers/. - Add Oxford comma to 'environment compute, triggers, and observability' in three places (style guide requires the serial comma). - Match the actual UI label: 'the harness dropdown' -> 'the **Agent harness** dropdown' on the Claude Code, Codex, and Warp Agent cloud pages (confirmed via harness_selector.rs). - Unify product descriptors so the auth page matches the harness pages: Claude Code is now 'Anthropic's agentic coding tool' and Codex is 'OpenAI's coding agent'. - 'Key icon above the input box' -> 'key icon above the input' (the spec uses lowercase 'key icon' and the rest of the docs say 'above the input'). - Drop redundant article: 'the same toolbelt the Warp Agent uses locally' -> '...the same toolbelt Warp Agent uses locally'. - Drop redundant qualifier: 'Warp Agent with Oz is the same agent runtime' -> 'Warp Agent is the same agent runtime' (page context already establishes Oz). - Disambiguate 'Claude Code and Codex call Anthropic or OpenAI directly' -> '...each call their provider directly' so it's clear each harness calls its own provider. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(harnesses): restore Lili's original Anthropic Console link Revert the Anthropic Console URL to platform.claude.com/login?returnTo=/? per PR review feedback that the original link was correct. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(harnesses): final polish pass on multi-harness pages - Match in-page link text to target page titles ('with Oz' instead of 'in Oz' / 'as a Cloud Agent'). - Point the harnesses index intro at the harness-specific pages instead of authentication anchors so readers land on the page that introduces each harness. - Surface every harness page from the index Related pages list. - Rename warp-agent's 'Starting a run' header to 'Starting a Warp Agent run' for parity with the Claude Code and Codex pages. - Split the team-admin disable sentence for clearer phrasing. Co-Authored-By: Oz <oz-agent@warp.dev> --------- Co-authored-by: Oz <oz-agent@warp.dev> Co-authored-by: liliwilson <lilimmwilson@gmail.com> * docs: add Platform Credits page and three-bucket model (#83) * docs: add Platform Credits page and three-bucket model Adds a new conceptual page introducing Platform Credits as the third credit bucket in Warp, alongside AI credits and Cloud Agent Credits. Explains when Platform Credits apply (cloud agents on any plan, and local agents on Business/Enterprise with BYOK or BYOLLM inference), when they don't, and where they appear in usage views. Also updates the existing Credits and Plans pages to introduce the three-bucket model and cross-link to the new page. Pricing specifics are deferred to warp.dev/pricing. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(platform-credits): align charge matrix and tighten copy - Fix contradiction flagged in PR #83 review: cloud agents always charge Platform Credits regardless of inference source. Reframe intro, three- bucket section, and the multi-bucket example to match the matrix in 'When Platform Credits apply'. - Point Generate link at /agent-platform/local-agents/generate/. - Remove time-unit details from the rate section; defer to warp.dev/pricing. - Drop internal tooltip-label callouts from the admin section. - Tighten plans-pricing-refunds Platform Credits one-liner to match. Co-Authored-By: Oz <oz-agent@warp.dev> * docs: reframe Platform Credits around inference / compute / platform infrastructure Per review feedback, lead with the three-infrastructure framing (inference, compute, platform) rather than the orchestration-layer framing. Each credit bucket now names the kind of infrastructure it covers. Also drop the enterprise custom-rate sentence; warp.dev/pricing remains the source of truth for rates. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(platform-credits): address audit findings - Reframe Platform Credits intro to lead with the rule (every cloud agent run, plus Business/Enterprise local agent runs with customer-supplied inference) instead of the negative 'when Warp isn't paying' framing. - Align cross-file framing in credits.mdx and plans-pricing-refunds.mdx so all three pages describe Platform Credits in the same terms. - Replace 'Workflow autofill' with linked 'AI Autofill'. - Replace 'Local Oz runs' with 'local agent runs' (Oz run is cloud-only). - Deduplicate the second BYOK parenthetical and normalize BYOLLM wording. - Clarify that self-hosted cloud workers count as cloud agents for Platform Credits purposes. Co-Authored-By: Oz <oz-agent@warp.dev> * Update src/content/docs/support-and-community/plans-and-billing/platform-credits.mdx Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> * Update src/content/docs/support-and-community/plans-and-billing/platform-credits.mdx Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> * docs(platform-credits): apply Rachael's wording suggestions Address remaining suggested edits from Rachael's review on PR #83: - plans-pricing-refunds.mdx: rewrite Platform Credits bullet to action-oriented form, matching sibling bullets. - platform-credits.mdx: de-dupe "charge for" repetition in intro; convert three-bucket bullets to active-voice complete sentences; rewrite "When Platform Credits apply" with "Uses Platform Credits" / "Doesn't use Platform Credits" headers and complete-sentence bullets; replace internal "harness" jargon with "which agent runs the task"; rename "Third-party harnesses run directly" to "Third-party agent CLIs run directly". - credits.mdx: same active-voice and "agent CLI" updates in the three-bucket summary and Platform Credits subsection. Validation: style_lint --changed clean (9 files, 0 issues), check_links --internal-only clean (2435 links, 0 broken). Co-Authored-By: Oz <oz-agent@warp.dev> * docs(platform-credits): reframe Cloud Agent Credits as compute bucket + add BYOK TOS rule Two pieces of feedback addressed on PR #83. 1. Cloud Agent Credits reframing. The bucket is described as compute infrastructure consumed by any agent run, local or cloud. Local agents rarely draw from it in practice because they don't run on Warp's compute, but the credit type is no longer tied to 'cloud-only by construction.' Updated: - platform-credits.mdx three-bucket bullet for Cloud Agent Credits (was 'cover compute infrastructure when cloud agents run on Warp-hosted compute,' now 'are the compute bucket... cover Warp-hosted compute consumed by any agent run, local or cloud'). - credits.mdx three-bucket bullet for Cloud Agent Credits with the same framing. - credits.mdx ### Cloud Agent Credits section intro reframed as 'the compute credits bucket - consumed when an agent run uses Warp-hosted compute. Both local and cloud agent runs can in principle draw from this pool...' - credits.mdx 'Not eligible' list intro tightened to make the reason explicit ('because they don't run on Warp-hosted compute') instead of implying the credit type is fundamentally cloud-only. 2. BYOK / customer-supplied inference TOS rule. Surfaces Warp's TOS rule wherever BYOK or customer-supplied inference is invoked as a workaround for Warp-paid inference. Added: - :::caution callout in platform-credits.mdx after the customer-supplied-inference paragraph, stating the individuals-and-organizations <=10 users rule and the Business or Enterprise requirement for orgs >10 users. Links to the canonical https://www.warp.dev/terms-of-service. - One-line forward reference at the end of the 'Local agents on Business or Enterprise with customer-supplied inference' bullet in platform-credits.mdx, pointing readers back to the callout for plan-size eligibility. - :::caution callout in bring-your-own-api-key.mdx directly after the existing :::note about BYOK paid-plan availability. - One-sentence summary of the TOS rule in the 'BYOK on Enterprise and Business plans' section, so admins reading that section see the eligibility constraint. Out of scope: renaming the 'Cloud Agent Credits' product term, changing pricing-faqs.mdx, or reworking BYOLLM enterprise gating (BYOLLM is already Enterprise-only, so the TOS rule is implicit). Validation: - style_lint --changed: 0 issues across 9 files scanned. - check_links --internal-only: 0 broken links across 319 files and 2,435 internal links. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(platform-credits): holistic polish pass after the compute/TOS reframe Tightens stale framing and copy that fell out of alignment after the last commit reframed Cloud Agent Credits as the compute bucket. credits.mdx: - Drop the orphaned 'small hosting fee, charged only when running agents in the cloud' sentence in the opener (L13). It predates the three-bucket model and now contradicts the new framing immediately below it; the bullet at the new L16 covers the same ground correctly. - Reframe the 'Cloud Agent Credits' bullet in Credit limits and billing (was L47, now L45). The old wording ('their normal Warp credits, Cloud Agent Credits, or a Build plan with available credits') treated Cloud Agent Credits as a separate currency. Rewritten as 'Cloud agents and integrations: Individual users can run cloud agents via the CLI and API, drawing from their plan credits. Slack and Linear integrations require team membership.' - Tighten 'in principle draw from this pool' to 'are eligible to draw from this pool' in the Cloud Agent Credits section intro (L122). platform-credits.mdx: - Frontmatter description shortened from 219 to 144 chars (back in the 50-160 SEO range). - Drop the redundant second sentence on L13 ('Platform Credits don't apply to local runs on Free, Build, or Max plans...'). The Doesn't use section below already covers it. The first sentence (defining customer-supplied inference) stays since the TOS callout depends on it. - Align the Admin usage breakdown bullet (L55): 'distinct from the AI and Compute segments' -> 'distinct from the AI credits and Cloud Agent Credits segments'. Uses the bucket names consistently with the rest of the page. Validation: - style_lint --changed: 2 pre-existing warnings on bring-your-own-api-key.mdx (Zero Data Retention is a proper term; Enterprise/Business are proper plan names). Acceptable. - check_links --internal-only: 0 broken links across 319 files and 2,433 internal links. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(platform-credits): rename Cloud Agent Credits -> compute credits + reframe as orthogonal credit-type/host model Per user correction: the credit type is 'compute credits' (lowercase), not 'Cloud Agent Credits.' The old name conflated the credit type (compute) with the host (cloud). The corrected conceptual model treats the three credit types (AI/inference, compute, platform) and the two host types (local, cloud) as orthogonal dimensions: any credit type can in principle apply to any host, with compute credits being the one that in practice only cloud agents consume (because local agents run on the user's machine). Files touched: Content (6): - credits.mdx: three-bucket bullets reframed to lead with the orthogonal dimension; section heading '### Cloud Agent Credits' -> '### Compute credits'; section intro rewritten; eligible/not- eligible subheadings renamed; all inline mentions and the '#cloud-agent-credits' anchor flipped to '#compute-credits'. - platform-credits.mdx: page intro three-bucket sentence updated to use 'compute credits'; three-bucket bullets reframed with the orthogonal-dimension intro; multi-bucket example updated; per-user and admin breakdown bullets updated to use bucket names consistently. - team-access-billing-and-identity.mdx: 3 references reworded to drop the 'normal Warp credits, Cloud Agent Credits, or a Build plan' stale enumeration and use plan credits / compute credits. - agent-platform/cloud-agents/overview.mdx: 2 references updated to the new terminology + anchor. - enterprise/support-and-resources/billing.mdx: 'small hosting fee' framing replaced with the explicit three-bucket model; 'no separate cloud agent credits or local credits' sentence replaced with a framing that aligns with the bucket model (credit type depends on infrastructure, not on local vs cloud). - terminal-and-agent-modes.mdx: Credits indicator description generalized from 'remaining cloud agent credits' to 'remaining credits.' Support / glossary (3): - AGENTS.md: 'Cloud Agent Credits' entry replaced with 'compute credits' (lowercase) entry; new 'Platform Credits' entry added (was previously implicit). - .agents/references/terminology.md: same swap in the billing glossary. - .agents/skills/style_lint/style_lint.py: 'Cloud Agent Credits' removed from PROPER_FEATURE_NAMES (no longer a Title-Case exception since it's now lowercase); 'Platform Credits' added to PROPER_FEATURE_NAMES; PRODUCT_CASING gains 'Cloud Agent Credits' -> 'compute credits' and 'Cloud Agent Credit' (singular) as one-way nudges so future contributors don't reintroduce the old name. Validation: - 0 remaining 'Cloud Agent Credit' or '#cloud-agent-credit' references in src/content/docs. - style_lint --changed: only the 2 pre-existing BYOK warnings (Zero Data Retention, BYOK on Enterprise and Business plans). Both are acceptable false positives flagged in prior commits. - check_links --internal-only: 0 broken across 319 files and 2,434 internal links. The Astro Starlight heading-to-anchor derivation (### Compute credits -> #compute-credits) resolves correctly. Out of scope: - Lowercasing 'Platform Credits' (user did not request). - Changes to pricing-faqs.mdx (no mentions). - vercel.json redirects (anchors aren't redirected; all inbound refs in our own docs were updated directly). Co-Authored-By: Oz <oz-agent@warp.dev> * docs: normalize credits list separators Co-Authored-By: Oz <oz-agent@warp.dev> * docs(platform-credits): restore descriptive 'cloud agent credits' on the Credits indicator UI label In the prior rename pass I over-corrected one spot: the 'Credits indicator' UI label in terminal-and-agent-modes.mdx, which described the cloud agent conversation's credit-balance indicator. The original text 'Shows your remaining cloud agent credits' was using 'cloud agent credits' descriptively (as in 'the credits cloud agents consume'), not as a formal product-name reference. Restoring the original wording. The PRODUCT_CASING lint nudge is case-sensitive on Title Case 'Cloud Agent Credits' / 'Cloud Agent Credit', so descriptive lowercase mentions like this one don't trigger it. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(platform-credits): revert compute credits rename back to Cloud Agent Credits Per user feedback: the product name is 'Cloud Agent Credits' (Title Case). The word 'compute' is the type description (what the bucket covers - the sandbox an agent runs in), not the product name. My prior rename pass conflated the two. Revert it. Kept from the prior pass: - The orthogonal credit-type/host conceptual reframe: 'Credit types and where an agent runs (local or cloud) are independent. Each agent run consumes from whichever credit types apply to it.' This framing was an improvement and stays. - The Enterprise billing page rewrite: the old 'small hosting fee' framing and the contradicting 'no separate cloud agent credits or local credits' sentence stay replaced by the explicit three-bucket explanation. Just substituted 'Cloud Agent Credits' back for the product-name reference. - The BYOK / customer-supplied inference TOS callouts in platform-credits.mdx and bring-your-own-api-key.mdx. - The Platform Credits glossary entry I added to AGENTS.md and terminology.md (was a real gap, not added by mistake). - The descriptive lowercase 'cloud agent credits' in terminal-and-agent-modes.mdx:126 (UI label restoration in 8833ded). Reverted: - credits.mdx: three-bucket bullets, section heading '### Compute credits' -> '### Cloud Agent Credits', section intro, eligible / not-eligible subheadings and intros. - platform-credits.mdx: page intro three-bucket sentence, three-bucket bullets, multi-bucket example, per-user and admin breakdown bullets. - team-access-billing-and-identity.mdx: 3 references and anchor link. - cloud-agents/overview.mdx: 2 references and anchors. - enterprise/support-and-resources/billing.mdx: product-name swap. - AGENTS.md: glossary entry back to 'Cloud Agent Credits'. - terminology.md: same. - style_lint.py: 'Cloud Agent Credits' back in PROPER_FEATURE_NAMES; removed the two PRODUCT_CASING nudges for Cloud Agent Credits -> compute credits. Validation: - 0 'compute credits' product-name references remain in src/content/docs. - style_lint --changed: only the 2 pre-existing BYOK header false positives. - check_links --internal-only: 0 broken across 319 files and 2,434 internal links. The '#cloud-agent-credits' anchor resolves via the restored '### Cloud Agent Credits' heading. Co-Authored-By: Oz <oz-agent@warp.dev> * docs: add Platform Credits AEO summary Co-Authored-By: Oz <oz-agent@warp.dev> * Split Cloud Agent Credits into Compute credits + Cloud agent credits; rename plan credits to normal Warp credits Address review feedback: 1. Split into two complementary concepts: - **Compute credits** (sentence case): the compute bucket itself, used alongside AI credits and Platform Credits when describing credit types. - **Cloud agent credits** (sentence case, 'Cloud' capitalized): credits consumed by cloud agents, in contrast with local agent credits. Both refer to the same underlying bucket; pick the term that fits the framing. 2. Rename 'plan credits' to 'normal Warp credits' in user-facing copy so it's no longer confused with 'Build plan credits' (the proper plan product noun, which is preserved). Files updated: - credits.mdx: Three-bucket bullets use 'Compute credits'. Section heading '### Cloud Agent Credits' becomes '### Compute credits' with anchor '#compute-credits', plus eligible/not-eligible subheadings switch to 'compute credits'. A short note explains the 'Cloud agent credits' alias for the host-context framing. - platform-credits.mdx: Bucket-context bullets and per-user/admin breakdown switch to 'Compute credits' (bucket framing) plus the three-bucket intro sentence. - team-access-billing-and-identity.mdx, cloud-agents/overview.mdx: Cloud-vs-local-host bullets use 'Cloud agent credits' (sentence case) pointing to '#compute-credits'. - enterprise/support-and-resources/billing.mdx: Three-bucket framing uses 'compute credits' alongside AI and Platform Credits. - add-on-credits.mdx, pricing-faqs.mdx: 'plan credits' (legacy term) swapped for 'normal Warp credits'; 'Build plan credits' (proper noun) is preserved. - AGENTS.md, .agents/references/terminology.md: Glossary updated with both 'Compute credits' and 'Cloud agent credits' entries, and the 'normal Warp credits' guidance. - .agents/skills/style_lint/style_lint.py: Removes 'Cloud Agent Credits' from PROPER_FEATURE_NAMES and adds a nudge to use sentence case ('Cloud agent credits') or 'compute credits' depending on framing. Validation: - 0 'Cloud Agent Credits' Title Case occurrences in src/content/docs - All 3 remaining 'plan credits' matches are 'Build plan credits' - style_lint --changed: only pre-existing BYOK false positives - check_links --internal-only: 0 broken across 2,434 internal links - '#compute-credits' anchor resolves via renamed section heading Co-Authored-By: Oz <oz-agent@warp.dev> * Lowercase 'cloud agent credits' mid-sentence/mid-bullet Per review feedback: the term 'cloud agent credits' is a common noun and should be lowercased anywhere it appears mid-sentence or mid-bullet. Only capitalize the first letter at the start of a sentence or bullet. Files updated: - credits.mdx L124: the alias clarification ('referred to as **cloud agent credits**') is now lowercase. - team-access-billing-and-identity.mdx L21, L41, L84: all three are mid-bullet/mid-sentence references and are lowercased. - cloud-agents/overview.mdx L120, L135: mid-bullet references lowercased. - AGENTS.md, .agents/references/terminology.md: glossary entry header is now '**cloud agent credits**' (lowercase) to match the canonical form for common-noun terms (consistent with **credits**, **normal Warp credits**, etc.). The description was updated to explain when to capitalize. - .agents/skills/style_lint/style_lint.py: PRODUCT_CASING nudge now recommends lowercase 'cloud agent credits' with a note about capitalizing the first letter at sentence/bullet boundaries. Glossary entries that lead a bullet (e.g. '**cloud agent credits**') stay lowercase to follow the existing common-noun convention in terminology.md, not because they're mid-sentence. Co-Authored-By: Oz <oz-agent@warp.dev> * Lowercase 'platform credits' mid-sentence/mid-bullet/mid-heading Per review feedback, apply the same common-noun convention to 'platform credits' that we applied to 'cloud agent credits' and 'compute credits'. Capitalize the first letter only at the start of a sentence, bullet, or heading; lowercase everywhere else. Files updated: - platform-credits.mdx: title -> 'Platform credits'. Every body, bullet, and heading occurrence reframed: - Three-bucket bullets and mid-sentence text -> 'platform credits' / '**Platform credits**' (bullet leads stay sentence-cased). - All H2/H3 headings ('## How platform credits are measured', '## When platform credits apply', '### Uses platform credits', '### Doesn't use platform credits', '## Where platform credits appear') lowercase the second word. - credits.mdx: three-bucket bullet, section heading '### Platform credits', subsection headings, and all in-text occurrences updated. Mid-sentence link text 'See [platform credits](...)' is also lowercased. - enterprise/support-and-resources/billing.mdx: the example sentence the reviewer flagged ('...AI credits..., compute credits..., and platform credits for the orchestration layer') and the three-types parenthetical (AI credits, compute credits, and platform credits) are lowercased. - plans-pricing-refunds.mdx: the related-links bullet now reads '[Platform credits](...) - learn how platform credits cover...'. - AGENTS.md, .agents/references/terminology.md: glossary entry header is now '**platform credits**' (matching the existing common-noun convention used for **credits**, **normal Warp credits**, **compute credits**, **cloud agent credits**) with a usage note explaining the casing rule. Adjacent **compute credits** entry is normalized the same way. - .agents/skills/style_lint/style_lint.py: 'Platform Credits' removed from PROPER_FEATURE_NAMES and a new PRODUCT_CASING nudge maps the title-cased form to lowercase 'platform credits' with a note about capitalizing at sentence/bullet/heading boundaries. Validation: - check_links --internal-only: 0 broken across 2,434 internal links. - The only remaining 'Platform Credits' Title Case match is the linter's own wrong->right mapping (expected). Co-Authored-By: Oz <oz-agent@warp.dev> * docs: rename 'normal Warp credits' to 'Warp credits' Drops the 'normal' qualifier across user-facing copy, the terminology glossary, and AGENTS.md. 'Warp credits' is the cleaner brand-aligned term for credits included with a subscription plan. Co-Authored-By: Oz <oz-agent@warp.dev> * docs: polish credit copy after rename - Drop now-redundant 'or Build plan credits' / 'or a Build plan with available credits' (Build plan credits are Warp credits). - Tighten 'individual Warp credits' to 'individual credits' to match the prior bullet's wording. - Remove duplicate 'Warp' in 'your included monthly Warp credits'. - Replace 'Build plan credits' with [Add-on Credits] in the cloud-agents requirements bullet so it mirrors the team-requirements bullet below it. - Restructure the Add-on Credits/limits sentence in platform-credits.mdx to make the consumption order explicit. - Update 'same plan credit pool' to 'same Warp credit pool' in credits.mdx. Co-Authored-By: Oz <oz-agent@warp.dev> * docs: drop redundant credit-type enumerations The '(any type works)' parenthetical and the 'Warp credits, cloud agent credits, and Add-on Credits all work' bullet aren't actually telling the user anything actionable — they're all credits and they all draw from the same balance. Just say '20 credits' and let the linked billing pages handle the credit-type breakdown. Touched: - agent-platform/cloud-agents/overview.mdx (2 occurrences; removed the redundant credit-type bullet under Credit requirements as well as the vague 'Usage is billed based on credit type and team configuration' filler bullet). - agent-platform/cloud-agents/team-access-billing-and-identity.mdx (2). - agent-platform/cloud-agents/quickstart.mdx (1). - agent-platform/cloud-agents/integrations/slack.mdx (1). - agent-platform/cloud-agents/integrations/linear.mdx (1). Co-Authored-By: Oz <oz-agent@warp.dev> --------- Co-authored-by: Oz <oz-agent@warp.dev> Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> * Audit pass: wire new orchestration-launch pages into sidebar; tidy stale terminology (#97) Audit pass over the three PRs merged into hyc/orchestration-launch (#83 Platform Credits, #87 Harnesses, #88 Agent identities) to catch wiring and cross-reference issues before rollout. Sidebar wiring (src/sidebar.ts): - Under 'Oz Cloud Agents & Orchestration', add 'Agent identities' (slug agent-platform/cloud-agents/agents) after Managing cloud agents, and a new collapsed 'Harnesses' subsection (Overview, Warp Agent, Claude Code, Codex, Authentication) after Secrets and before MCP servers. - Under 'Plans and billing', add 'Platform credits' after Add-on Credits. Terminology / cross-reference (one-line tweaks): - external-authentication-required.mdx:104: replace the inline '(service account)' parenthetical with 'bound to an [agent identity](...)'. Matches the alias formalized in agents.mdx and the existing phrasing in federate.mdx and cli/index.mdx. - cloud-agents/overview.mdx Learn more: add two bullets so the new Harnesses overview and Agent identities pages are discoverable from the parent overview. Validation: - check_links --internal-only: 0 broken across 2,495 internal links (up 3 from the 2,492 baseline, matching the 3 new links added). - style_lint --changed: 14 warnings, identical to baseline (all pre-existing proper-name false positives in pricing-faqs.mdx, bring-your-own-api-key.mdx, etc.). - npm run build: succeeds; 326 HTML files generated. Co-authored-by: Oz <oz-agent@warp.dev> * Audit pass 2: factual corrections, terminology unification, style cleanup (#99) Comprehensive pass over the orchestration-launch branch to catch content issues that wiring-focused audit #97 left behind. Factual corrections: - agents.mdx: drop 'getAgent' from the operationId list and remove the 'Retrieve - GET /agent/identities/{uid}' bullet. The OpenAPI spec (developers/agent-api-openapi.yaml) only ships createAgent / listAgents / updateAgent / deleteAgent under the /agent/identities path; there is no single-resource GET. - agents.mdx: replace 'pass the identity\'s UID to the generateApiKey mutation' with 'choose the identity when creating the team API key'. No generateApiKey mutation exists in the OpenAPI, and api-keys.mdx describes a UI-driven creation flow. - agents.mdx: drop the ('Quick run' in the web app) parenthetical from the default-identity fallback note. oz-web-app.mdx defines Quick run as user-attributed ('runs as your own user'), so equating it with the default agent identity contradicts the rest of the docs. Terminology unification (post three-bucket / agents-launch model): - harnesses/index.mdx, claude-code.mdx, codex.mdx: replace the vague 'Warp credits cover the orchestration platform' wording with the explicit three-bucket framing 'Warp meters compute credits for the run\'s sandbox and platform credits for the orchestration layer'. - team-access-billing-and-identity.mdx: rename every 'Reload Credits' / 'Reload Credit pool' / 'Reload Credit balance' reference to the canonical 'Add-on Credits' (5 spots, including the parenthetical '[Reload Credits (Add-on Credits)](...)'). - oz-web-app.mdx: rename the page title and 6 image alt texts from 'Oz Web App' (Title Case) to 'Oz web app' to match the canonical glossary entry and the sidebar label. Style guide cleanup: - secrets.mdx: drop a trailing ' ' GitBook artifact, replace 'just references it by name' with 'only references it by name', and backtick the bare 'oz secret' in 'oz secret command family'. - harnesses/authentication.mdx: replace 'just like any other Warp- managed secret' with 'like any other Warp-managed secret'. - deployment-patterns.mdx: drop 'just' from 'and you just need a reliable, cloud-connected agent runner'. - cloud-agents/overview.mdx: lowercase two H4 headings ('For Cloud Agents via CLI/API' -> 'For cloud agents via CLI/API'; 'For Integrations (Slack/Linear)' -> 'For integrations (Slack/Linear)') per the sentence-case style guide. Validation: - check_links --internal-only: 0 broken across 2,501 internal links (up 6 from the 2,495 baseline, matching the new compute-credits / platform-credits anchors added in the harnesses billing sections). - style_lint --changed: only pre-existing proper-name false positives in pricing-faqs.mdx (Build / Business / Pro / Turbo / Lightspeed / Add-on Credits headings). - npm run build: 326 pages built; sidebar compiles; new anchor and slug references resolve. Co-authored-by: Oz <oz-agent@warp.dev> * docs(agent-platform): add Agent Memory research-preview pages (#86) * docs(agent-platform): add Agent Memory research-preview pages Add overview, memory-stores, self-hosted-memory, and api pages under agent-platform/capabilities/agent-memory/. List the feature on the capabilities index and add a Suggested Skills from Agent Memory note to the skills page. The new pages are scoped to the agent-platform topic but are not yet wired into src/sidebar.ts; the cross-cutting sidebar PR will add the entries so the build resolves the topic association. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(agent-memory): scrub internals, downsize API page, tighten tone Address reviewer feedback and Slack-thread guidance on the Agent Memory research-preview pages. - Overview: narrow the API capability bullet to user-owned store creation (team-owned creation is in the Warp app only), drop the 'harness-support endpoint' internal reference, drop the service-account-granted-stores phrasing, trim the data flywheel section, and tighten the frontmatter description to fit the 50-160 char SEO range. - Memory stores: tighter description, generalize API references away from raw HTTP method/path callouts, drop schema field name leaks ('memory_stores' as wire field) in favor of conceptual prose, polish tone. - Self-hosted memory: present as forward-looking direction for the research preview, drop the specific Postgres/Turbopuffer/ Voyage AI vendor stack from the reference adapter section in favor of abstract relational + vector + embedding language. - API: downsize to a research-preview stub. Drop endpoint paths, request/response schemas, and HTTP method signatures. Keep authentication, capability surface at category level, attachment behavior rules, validation error patterns, and the design-partner contact path. - Skills: tighten Suggested Skills from Agent Memory section to honest, forward-looking direction-of-travel wording. - Capabilities overview: tighten the Agent Memory entry copy. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(agent-memory): drop remaining internal-implementation details Second pass of trimming on the Agent Memory research-preview pages, following the same direction as 1564a8d. - index.mdx: collapse the two-stage extraction/planning description of consolidation into a single user-facing paragraph; drop the internal facts/learnings/outcomes taxonomy; drop the reranker mention from the retrieval bullet; tighten the matching key-features and research-preview bullets for consistency. - memory-stores.mdx: remove the wire-format Update semantics section (omit / empty / non-empty) and link out to the API page instead; replace the dependency-order permanent-deletion sentence with a single user-facing line; drop the 409 Conflict HTTP status code while keeping the rule and remediation. - self-hosted-memory.mdx: replace the named interface-method list with a one-paragraph capability summary; drop the embedding-pipeline phrasing on both the in-scope and reference-adapter sections; drop the extraction/planning two-stage framing. - api.mdx: rename 'Validation errors' to 'Common rejection reasons' and drop the 400 invalid_request / 409 Conflict codes while keeping the rejection reasons; soften the wire-format mention for the identity-attachment endpoint. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(agent-memory): use canonical "agent identity" terminology Replace "named agent identity/identities" (and shorthand "named identity" forms) with "agent identity/identities" throughout the Agent Memory pages to align with the docs-wide canonical term. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(agent-memory): consolidate research-preview docs into a single page Replace the four-page Agent Memory subsection with a single research-preview overview page. The deleted pages (memory-stores, self-hosted-memory, api) were never published and overcommitted on behavior that's still in design. - Rewrite agent-memory/index.mdx as a tight overview: research-preview callout with waitlist CTA, what's available today, what's not yet available, how to get involved, related pages. - Tighten the "Suggested Skills from Agent Memory" subsection on skills.mdx to a single forward-looking paragraph without procedural claims. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(agent-memory): audit polish pass on the consolidated research-preview page Editorial copy pass on top of 2ea77ff. No structural or scope changes; no new claims, no new links. agent-memory/index.mdx: - Drop slight anthropomorphism in opener ("no recollection" -> "without context"). - Replace "verbose transcript dump" with neutral "the full conversation transcript." - Reorder the personal-memory bullet so the actor (Oz) leads and the harness clause doesn't bury the punchline. - Fix awkward SVO order on self-hosted bullet. - Replace vague "focused on the personal store" with precise "only reads from the personal store." - Tighten the two related-pages descriptions. skills.mdx: - Tighten the Suggested Skills from Agent Memory paragraph: drop the doubled "Agent Memory" reference, replace "is being explored" with "is in design," and remove the awkward "no concrete behavior" hedge. Validation: - style_lint --changed: one known false positive on the Suggested Skills header (Skills and Agent Memory are proper feature names per AGENTS.md). - check_links --internal-only: 0 broken links across 318 files and 2391 links. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(agent-memory): rewrite as unified SEO/waitlist page Drops the "What's available today" / "What's not yet available" split in favor of a single capability narrative. The page is now a marketing-pitched, SEO-oriented overview that walks a prospective user through the value of Agent Memory and pushes toward the waitlist three times (top caution, hero closer, dedicated Get early access section). Structural changes: - Tightened frontmatter description (132 chars, in SEO range) leading with the primary keyword "agent memory" and the value proposition. - Hero is now two short paragraphs that motivate the problem (cold runs) and introduce the product, ending with a request-early-access link. - Five keyword-rich H2 sections describe the capability surface in one unified narrative: Persistent memory across runs, Cross-harness retrieval, Automatic consolidation, Personal and team memory stores, Self-hosted memory backends. No shipped-vs-roadmap hedging in the body; the research-preview caution at the top covers "behavior may change." - New "What Agent Memory unlocks" section with three use-case vignettes (debugging that resumes; repeated maintenance agents that learn the codebase; team-shared knowledge) that give prospects concrete reasons to want it and add SEO surface area. - New "Get early access" section replaces the old "How to get involved." - Switched the Agent identities related-pages link from the absolute docs.warp.dev URL to a relative path, now that PR #88 has merged into the gating branch and been forward-merged into this branch. Validation: - style_lint --changed: 0 new issues on the rewritten page (the existing known false positive on skills.mdx:414 Suggested Skills header is untouched). - check_links --internal-only: 0 broken links across 319 files and 2,421 internal links. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(agent-memory): polish hero opener for clarity Drop the self-referential "by default" qualifier (the non-default mode it implied is Agent Memory itself, making the phrase quietly circular). Make the cold-start problem more concrete by spelling out that prior runs' learnings are lost \u2014 strengthens the value framing the page is trying to build for the waitlist CTA. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(agent-memory): consolidate PR #95 content, move to top-level Memory section Major restructure of the Agent Memory docs to address user feedback: 1. Promote Agent Memory to its own top-level section in the sidebar. New 'Memory (Research Preview)' group sits inside the Agents topic between Getting started and Warp Agents for top-of-list visibility. 2. Move the page from agent-platform/capabilities/agent-memory/ to agent-platform/agent-memory/ to match the new section's IA. The '/agent-platform/capabilities/agent-memory' URL now redirects to '/agent-platform/agent-memory/' via vercel.json. 3. Add '(Research Preview)' marker to the sidebar label, matching the page title and the existing Settings Sync (Beta) precedent. 4. Replace 'workspace' with 'team' in user-facing copy. The implementation-layer WORKSPACE enum is internal and unaffected. 5. Consolidate PR #95 (hyc/memory-waitlist) content into the page. PR #95 had been opened separately as a marketing/waitlist rewrite from another conversation. Taking its richer body (8 capability bullets, dedicated sections for Personal/team stores, Automatic memory from conversations with Sparse/Reasoned/Reversible sub-bullets, How agents retrieve memories with the Vector+BM25+Reranking pipeline, Attaching memory to agents covering identity-level and run-level attachments, and Built for teams), stronger CTAs (bold-link waitlist CTA after hero + 'Ready to give your agents memory?' closer), and richer 5-link related pages. Restores the research-preview caution callout that PR #95 had dropped, keeps the (Research Preview) title, and uses 'team' throughout. PR #95 will be closed in a follow-up. 6. Use generic 'agents' / 'your agents' / 'Warp agents' framing throughout. Memory is gated to cloud agents today but will work for local agents going forward, so the docs don't specify cloud vs local. The research-preview caution carries any 'behavior may change before GA' hedge. 7. Capability claims (deletion safety, per-store instructions, versioned history, hybrid semantic+keyword search) all match the QUALITY-585 and QUALITY-536 specs. Files touched: - src/content/docs/agent-platform/agent-memory/index.mdx (new) - src/content/docs/agent-platform/capabilities/agent-memory/index.mdx (deleted) - src/content/docs/agent-platform/capabilities/index.mdx (Agent Memory bullet removed) - src/content/docs/agent-platform/capabilities/skills.mdx (link URL updated) - src/sidebar.ts (new Memory group) - vercel.json (old URL redirect) Validation: - style_lint --changed: only the known pre-existing false positive on skills.mdx:414 Suggested Skills from Agent Memory header (both 'Skills' and 'Agent Memory' are proper feature names per AGENTS.md). - check_links --internal-only: 0 broken across 319 files and 2,422 internal links. New URL resolves cleanly. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(agent-memory): address Suraj's review feedback - Drop vector/keyword search and versioned history bullets; remove the 'recorded reason for every change' / 'Reasoned' bullet so the page stays high level for waitlist-phase customers (Slack feedback + pending inline comment). - Replace 'Warp agents' wording and explicitly call out cross-harness support (Warp Agent, Claude Code, Codex, Gemini) in the description and intro paragraph (pending inline comments on multi-harness and 'Warp agents'). - Reframe automatic-memory and bullets section around 'learning over time' instead of one-shot extraction (pending inline comment). - Rename 'Personal and team memory stores' to 'Memory stores', explain per-agent scoping with cross-agent sharing, and add the code-review + Sentry triage repo-store example (pending inline comment). - Replace 'runs a memory synthesis pass that extracts' with 'extracts' (pending inline comment). - Slim 'How agents retrieve memories' to 'How agents use memory' and note that agents can retrieve memories on demand throughout a conversation when they decide it's the right thing to do (pending inline comment + Slack 'how' removal). - Collapse 'Attaching memory to your agents' to one paragraph and remove the redundant 'Built for teams' section to keep the page scannable and 'what/why'-focused. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(agent-memory): lead with async + Oz-as-the-layer framing Follow-up to Suraj's feedback on PR #86. Verbiage inspiration from the Claude Managed Agents memory post. - Frontmatter description and hero paragraph now lead with the value prop ('Your agents should learn across every conversation, every harness, every run') instead of a descriptive opener, and explicitly position Warp as the platform the customer already uses to run their agents. - Hero paragraph + a new 'Async by design' bullet + a new sentence in each of 'Automatic memory from conversations' and 'How agents use memory' make it clear that memory creation and retrieval happen in the background. Agents never burn tokens or attention on memory work during a run. - 'Cross-harness persistence' is promoted to the first 'What you get' bullet and reframed as 'One memory layer for every agent in Warp'. Dropped the now-redundant 'Durable knowledge across conversations' bullet (the intro already says it). - New 'Built on the layer your agents already live on' subsection drives the Oz-as-the-layer pitch home: Warp Agent locally, Oz cloud agents in the background, and Claude Code/Codex/Gemini all go through the same platform, so memory is a free byproduct rather than new infrastructure. - Final CTA sharpened to 'Your agents already live on Warp. Give them a memory that lives there too.' Co-Authored-By: Oz <oz-agent@warp.dev> * docs(agent-memory): polish pass - Trimmed frontmatter description so it fits the ~50-160 char target and reads as a standalone summary. - Split the long hero paragraph into shorter sentences so each beat (value prop, harness list, no infra, async, each run) lands on its own. Fixed the 'memory ... memory' repetition by referring to creation and retrieval with 'they'. - Reworded the 'Built on the layer your agents already live on' paragraph: opens with 'Warp is already the platform where your agents run', drops the dangling 'through the same platform' clause, and avoids the 'layer ... layer too' echo by saying 'Agent Memory turns that same platform into a memory layer'. - Used 'Memory creation' (instead of 'Synthesis') in the 'Automatic memory from conversations' paragraph so the async terminology matches the 'Async by design' bullet. - Switched the 'Sparse by design' / 'Learns over time' mini-headlines to the bold-term + em-dash + explanation pattern used by the rest of the page. - Tightened the 'Per-agent access control and instructions' bullet. - Replaced the awkward 'watch what they learn today make them sharper tomorrow' construction in the final CTA with 'so what they learn today makes them sharper tomorrow'. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(agent-memory): de-marketing pass, dev-doc tone Strip marketing-style phrasing and rewrite the page in the descriptive, factual tone used by the rest of the agent-platform capability pages (skills.mdx, codebase-context.mdx, cloud-agents/overview.mdx). - Description and intro now lead with what Agent Memory is, not a rule-of-three pitch. Dropped 'Your agents should learn across every conversation, every harness, every run' and 'Agent Memory makes that real.' Replaced with: 'Agent Memory is a persistent memory layer that lives on Warp and is shared across every supported agent harness...' - Renamed 'What you get with Agent Memory' to 'Key features' (matches skills.mdx). - Renamed 'Built on the layer your agents already live on' to 'Where Agent Memory runs' and rewrote it as factual coverage info: storage + creation + retrieval are all hosted on Warp infrastructure, with an explicit bulleted list of the agent types covered (local Warp Agent, Oz cloud agents, third-party harnesses). - Tightened bullets to bold-term + em-dash + plain explanation pattern. Dropped 'draws from the same well of knowledge', 'any harness you reach for next', 'leaves your team a little smarter than the last', and 'Instructions matter: they're the difference between an agent that has memory and an agent that knows what to remember and when.' - Tightened the 'How agents use memory' paragraph and changed 'whenever they decide it's the right thing to do' to 'when they determine it's relevant' (preserves the intent of Suraj's earlier feedback without the colloquial phrasing). - Replaced the 'Ready to give your agents memory?' CTA with a plain 'Join the waitlist' section, and switched the in-body waitlist link from bold + arrow to a plain markdown link. All seven of Suraj's earlier pending comments are still addressed (multi-harness, harness-agnostic wording, learning over time, no 'reason' mentions, Memory stores rename + use case, 'Warp extracts', and on-demand mid-conversation retrieval). Co-Authored-By: Oz <oz-agent@warp.dev> * docs(agent-memory): address all of Suraj's review comments Addresses every inline comment from szgupta on PR #86: - Comment 3263750377 (lines 5-6, description, 'cross-harness covers it'): dropped the trailing 'that learns over time' clause from the description. - Comment 3263750945 (line 14, 's/Warp/Oz'): the platform that hosts Agent Memory is Oz. Replaced Warp -> Oz in the intro and anywhere else the page used Warp as the platform noun ('Where Agent Memory runs', the Oz API bullet, 'Oz extracts...', 'Oz searches...'). Kept Warp where it means the product (Warp Agent harness name, Warp client, warp.dev URLs). - Comment 3263752096 (line 14 reply, 'Gemini isn't officially supported in Oz yet'): removed every Gemini mention from the page (description, intro, Cross-harness bullet, 'Where Agent Memory runs' bullet). - Comment 3263755700 (line 25, 'focus more on sharing'): replaced the 'Personal and team stores' Key features bullet with 'Agent-scoped, shareable stores' that leads with default agent-scoping and cross-agent sharing. The Memory stores section now also notes that stores can be shared 'across teammates when knowledge should travel with the team'. - Comment 3263756525 (line 27, 'seems irrelevant?'): dropped the Deletion safety Key features bullet entirely. - Comment 3263761292 (line 20, suggested 5 new bullets): added Both local and cloud agents, Fully accessible via API, Traceability, Auditability, and Self-hostable to Key features. - Comment 3263763038 (line 31, 'we should mention self-hosted'): the 'Where Agent Memory runs' section now says memory runs on the same Oz instance that hosts your agents - Warp-hosted Oz by default, or a customer-hosted Oz instance for teams that need to keep memory inside their own perimeter. Paired with the new Self-hostable bullet in Key features. - Comment 3263765714 (line 35, '3P harnesses are Oz-cloud-only for now'): scoped the third-party harnesses bullet to 'Third-party harnesses running as Oz cloud agents' and added an explicit '(Running third-party harnesses locally isn't supported during the research preview.)' qualifier. Same scope is mirrored in the Cross-harness Key features bullet. - Comment 3263767235 (lines 52-53, replace Sparse/Learns with 'evolves+resolves contradictions'): replaced the two bullets with a single 'Memories evolve over time' bullet that says agents update and supersede their own memories as new information arrives, including to resolve contradictions with prior memories. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(agent-memory): polish pass after review-comment rewrite - Intro: separated the 'regardless of which harness' clause with an em-dash so the second sentence parses more cleanly. - 'Both local and cloud agents' bullet: 'Works for' -> 'Supports' for a slightly more formal verb. - Memory stores intro: replaced the em-dash construction with a comma so the two sharing scopes (across agents, across teammates) read as a single list, and tightened 'named container of memories' to 'named collection of memories'. - Attaching memory paragraph: 'free-form instruction string' -> 'per-store instructions', matching the terminology already used in the Key features bullet. No factual changes. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(agent-memory): make self-hosted explicit + small polish - 'Where Agent Memory runs' now calls out self-hosting by name: 'either Warp-hosted Oz (the default) or a self-hosted Oz instance that your team operates inside its own perimeter', replacing the previous 'customer-hosted Oz instance' phrasing. - 'Automatic memory from conversations': 'from what happened' -> 'from the transcript'; 'during the run that produced it' -> 'during that run'. - 'Attaching memory to your agents': 'Each attachment carries per-store instructions' -> 'Each attachment includes per-store instructions'; cleaned up the 'Without instructions' sentence to 'the agent can access the store but won't know when to read from or write to it'. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(agent-memory): cross-link self-hosting + Oz API, tighten store bullet The page mentions self-hosting and the Oz API prominently in Key features and 'Where Agent Memory runs', but those concepts weren't linked to the dedicated reference pages. Add the links so readers can follow up: - Inline-link 'Oz API' in the 'Fully accessible via API' bullet to /reference/api-and-sdk/. - Inline-link 'self-hosted Oz' in both the 'Self-hostable' bullet and the 'Where Agent Memory runs' paragraph to /agent-platform/cloud-agents/self-hosting/. - Inline-link 'Rules' and 'Codebase Context' in 'How agents use memory' (and capitalize 'rules' to match the feature name). - Add 'Self-hosting overview' and 'Oz API and SDK' to Related pages. Also tightened the 'Agent-scoped, shareable stores' bullet so its sharing phrasing varies slightly from the near-identical sentence in the Memory stores section ('shared across multiple agents, or across an entire team, when the same knowledge should travel with the work'). Co-Authored-By: Oz <oz-agent@warp.dev> * docs(agent-memory): final scan nits - 'Attaching memory': 'Each attachment includes per-store instructions' -> 'Each attachment can include per-store instructions'. Removes a small logical contradiction with the very next sentence, which treats instructions as optional ('Without instructions, the agent can access the store but won't know when to read from or write to it.'). - 'Team stores' bullet: replaced the coined adjective 'any team-authorized agent' with 'any agent the team authorizes', matching the active-voice phrasing used elsewhere on the page. Co-Authored-By: Oz <oz-agent@warp.dev> --------- Co-authored-by: Oz <oz-agent@warp.dev> * docs(handoff): add local↔cloud handoff documentation (#85) * docs(handoff): add local↔cloud handoff documentation Add a new handoff section under cloud-agents that documents the three directions of handoff supported by the orchestration launch: - Overview (conceptual) explaining what handoff is, the three directions, and what carries over. - Local→cloud (procedural) for promoting a local Warp Agent conversation to a cloud agent run. - Cloud→local (procedural) for picking up a cloud run inside the Warp terminal via /continue-locally and equivalent UI entrypoints. - Cloud→cloud (procedural) for follow-ups that span multiple executions of the same run. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(handoff): scrub internals, drop cloud-to-local, tighten copy Address PR review feedback and Slack-thread direction. - Drop cloud-to-local.mdx; existing fork-to-local docs in viewing-cloud-agent-runs.mdx already cover the capability. Overview now references that page for cloud-to-local. - Scope the snapshot rehydration mechanism in the overview to local-to-cloud and cloud-to-cloud only; cloud-to-local does not apply workspace patches. - Replace the inaccurate `git diff --binary HEAD` capture description in local-to-cloud with a high-level summary that covers tracked and untracked changes without committing to a specific git command. - Soften the local-to-cloud entry point: do not document a specific keyboard shortcut, add a note that the affordance may evolve during the Oz launch rollout. - Strip internal-only details from user-facing copy: GCS paths, manifest filenames, `git apply` mechanics, internal routing names (appended/injected/requeued), API endpoint paths, and rehydration checklist references. - Senior-writer pass: tighten descriptions to 50-160 chars, reduce marketing fluff, normalize cross-references. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(handoff): second editor pass to drop residual internal jargon - Replace 'execution' with 'session' across cloud-to-cloud.mdx so the user-facing unit of work stays 'the run', not the internal model. - Drop 'rehydrate'/'rehydration' in favor of 'restore'/'carry over'; fold the standalone 'Rehydration behavior' section into 'What carries over' in the overview. - Drop the 'server-side' qualifier on 'fork' throughout; users don't care where the fork happens. - Collapse the cloud-to-cloud 'How follow-ups route' state-machine into a single user-facing description; remove the two routing-paths items from troubleshooting since they describe normal behavior, not problems. - Collapse local-to-cloud's 'Verifying the handoff' debugging walkthrough into one sentence pointing readers to the management view. - Cut meta self-descriptions: 'The handoff entry point is integrated into the cloud agent launch flow...' and 'Cloud-to-cloud handoff is automatic...'. - Dr…
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Comprehensive content audit of the
hyc/orchestration-launchbranch to catch issues that the wiring-focused audit in #97 left behind. 10 files changed, +25 / \u221226.Factual corrections
agents.mdx:getAgentfrom the operationId list and remove the Retrieve \u2014GET /agent/identities/{uid}bullet. The OpenAPI spec only shipscreateAgent/listAgents/updateAgent/deleteAgentunder/agent/identities; there is no single-resource GET.generateApiKeymutation" with "choose the identity when creating the team API key". NogenerateApiKeymutation exists in the spec;api-keys.mdxdocuments a UI-driven creation flow.oz-web-app.mdxdefines Quick run as user-attributed ("runs as your own user"), so equating it with the default agent identity contradicts the rest of the docs.Terminology unification (post three-bucket / agents-launch model)
harnesses/index.mdx,claude-code.mdx,codex.mdx\u2014 replace the vague "Warp credits cover the orchestration platform" wording with the explicit three-bucket framing: "Warp meters compute credits for the run's sandbox and platform credits for the orchestration layer."team-access-billing-and-identity.mdx\u2014 rename everyReload Credits/Reload Credit pool/Reload Credit balancereference to the canonicalAdd-on Credits(5 spots, including the legacy parenthetical[Reload Credits (Add-on Credits)](...)).oz-web-app.mdx\u2014 rename the page title and 6 image alt texts from "Oz Web App" (Title Case) to "Oz web app" to match the canonical glossary entry and the sidebar label.Style guide cleanup
secrets.mdx\u2014 drop a trailing GitBook artifact, replace "just references it by name" with "only references it by name", and backtick the bareoz secretin "oz secret command family".harnesses/authentication.mdx\u2014 replace "just like any other Warp-managed secret" with "like any other Warp-managed secret".deployment-patterns.mdx\u2014 drop "just" from "and you just need a reliable, cloud-connected agent runner".cloud-agents/overview.mdx\u2014 lowercase two H4 headings (For Cloud Agents via CLI/API\u2192For cloud agents via CLI/API;For Integrations (Slack/Linear)\u2192For integrations (Slack/Linear)) per the sentence-case style guide.Validation
check_links --internal-only: 0 broken across 2,501 internal links (up 6 from the 2,495 baseline; the additions are the new#compute-creditsand/platform-credits/anchors in the three harnesses billing sections).style_lint --changed: only pre-existing proper-name false positives inpricing-faqs.mdx(Build / Business / Pro / Turbo / Lightspeed / Add-on Credits headings).npm run build: 326 pages built; sidebar compiles; new anchor and slug references resolve.Out of scope
hyc/orchestration-launchand the new pages it adds. Pre-existing artifacts inenvironments.mdxand "Oz Web App" alt text inskills-as-agents.mdx/environments.mdxare unrelated; leaving for a separate cleanup.hyc/orchestration-launch(docs(orchestration): add multi-agent orchestration pages #84 multi-agent, docs(handoff): add local↔cloud handoff documentation #85 handoff, docs(agent-platform): add Agent Memory research-preview pages #86 Memory) are untouched.Co-Authored-By: Oz oz-agent@warp.dev