docs(handoff): add local↔cloud handoff documentation#85
Merged
Conversation
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>
|
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 adds four new handoff documentation pages covering local-to-cloud, cloud-to-local, cloud-to-cloud, and an overview. The structure is useful, but a few statements overpromise current behavior or document an unconfirmed/incorrect user flow, which could mislead users at launch.
Concerns
- The overview describes all handoff directions as sharing workspace-snapshot rehydration, but the cloud-to-local page says local continuation only forks the conversation and artifacts.
- The local-to-cloud procedure publishes a specific
/cloud-agent/shortcut handoff flow even though the client surface needs confirmation. - The local-to-cloud page says
git diff --binary HEADcaptures untracked changes, which that command does not do by itself.
Verdict
Found: 0 critical, 3 important, 0 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
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>
Collaborator
Author
Revision passPushed What changed
Review comments addressed
Internal-only scrubStripped from all user-facing copy: GCS paths ( Validation
Open questions for PM
|
- 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...'. - Drop the rollout caveat note on local-to-cloud. - Reduce 'sandbox' references where they leak infrastructure. Co-Authored-By: Oz <oz-agent@warp.dev>
Collaborator
Author
Second editor passPushed Terminology
Structural changes
Validation
|
Co-Authored-By: Oz <oz-agent@warp.dev>
- cloud-to-cloud.mdx: soften per-session timeline claim to API-only (UI render not present) - cloud-to-cloud.mdx: gloss 'ambient agent task' inline for clarity - local-to-cloud.mdx: switch primary credits link to credits page; fix link text casing for access page Co-Authored-By: Oz <oz-agent@warp.dev>
Collaborator
Author
|
Applied audit fixes for handoff pages. Summary of changes:
Co-authored-by: Oz oz-agent@warp.dev |
|
Some other thoughts that are not aligned with existing content:
|
- index.mdx: drop launch-anchored framing; reframe Directions list as evergreen capability statement; add third-party-harness coverage subsection (cloud<->cloud works on 3P with Continue+input prompt; local->cloud is Warp Agent only). - local-to-cloud.mdx: replace /cloud-agent entry-point claim with the '&' shortcut and the '/handoff' slash command; add note that the model can't be changed during handoff. - cloud-to-cloud.mdx: consolidate duplicate scheduled/integration bullets; add 'same Git branch' detail to workspace-state carryover; add :::caution that handoff requires a prior-execution snapshot; note that local->cloud-originated runs can only be continued by the creating user; scope send-follow-up to the Warp app and drop the Oz-web-app/integration follow-up sections; add third-party harness Continue-button flow; soften per-execution timeline claim (transcript is the source of truth, not the API). Co-Authored-By: Oz <oz-agent@warp.dev>
Collaborator
Author
Both points addressed in this pass:
|
rachaelrenk
reviewed
May 19, 2026
Contributor
rachaelrenk
left a comment
rachaelrenk
left a comment
There was a problem hiding this comment.
Reviewed for the same patterns we covered in PRs #83 and #84: user-facing terminology, direct Oz web app links, sentence-case consistency, and launch-surface/eligibility clarity. One PR-level note: the PR description still says there are four new handoff pages including a dedicated cloud-to-local page, but the current file list has three new pages and routes cloud-to-local to the existing viewing-cloud-agent-runs page. It may be worth updating the PR description or confirming whether a dedicated cloud-to-local page is still expected before merge.
rachaelrenk
approved these changes
May 19, 2026
Contributor
rachaelrenk
left a comment
rachaelrenk
left a comment
There was a problem hiding this comment.
Approving but left comments + suggested edits
…cloud.mdx Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>
Apply all 9 of @rachaelrenk's suggested edits on PR #85 and run a final senior-copywriter pass for consistency across the three handoff pages. index.mdx - Intro: "your local Warp terminal" -> "a local Warp session" so the intro talks about a session rather than the terminal application. - "Third-party harness coverage" -> "Third-party agent runtime coverage"; same swap in the two bullets underneath. "Harness" is internal vocabulary; "agent runtime" is the user-facing term. - "spiraled into work" -> "grown into work" (less idiomatic). - "Managing Cloud Agents" -> "Managing cloud agents" in Related pages to match the sentence-case nav style used elsewhere. - Consistency polish: "Fork a cloud conversation into your local terminal" -> "into a local Warp session" so the cloud-to-local bullet uses the same terminology as the rewritten intro. local-to-cloud.mdx - Intro: "Hand off a conversation from the Warp terminal" -> "Hand off a local Warp conversation" (same reason as above). - "This direction is the right move when:" -> "Use this handoff direction when:" (less conversational, matches docs voice). - Post-handoff pointer: linked the management view doc -> deep-linked the [Runs page](https://oz.warp.dev/runs) in the Oz web app, which matches the pattern added in PR #84. - "Cloud Agents quickstart" -> "Cloud agents quickstart" (sentence case). cloud-to-cloud.mdx (consistency polish, same patterns Rachael called out in the other two pages) - "This direction is the right move when:" -> "Use this handoff direction when:". - Step 1 of "Sending a follow-up": linked the management view doc -> deep-linked the Runs page in the Oz web app. - Removed a stray duplicate `### Third-party harnesses` heading that was sitting directly above the correct `### Third-party agent runtimes` heading, and inserted a missing blank line before the next `## Inspecting a run that's been handed off` section. - "Managing Cloud Agents" -> "Managing cloud agents" in Related pages. Validation - python3 .agents/skills/style_lint/style_lint.py --changed -> 0 issues. - python3 .agents/skills/check_for_broken_links/check_links.py --internal-only -> 0 broken links (2,439 internal links across 321 files). Co-Authored-By: Oz <oz-agent@warp.dev>
A senior-copywriter follow-up on commit b45a4e8. Focuses on terminology consistency, list parallelism, active voice, and a few style-guide nits caught on the second read. index.mdx - Frontmatter description: "Move an agent conversation between your terminal and the cloud" -> "Move agent work between a local Warp session and the cloud" so the description matches the body intro (which Rachael's review moved to "local Warp session" terminology). - "Directions of handoff" Local-to-cloud bullet: "more compute, longer-running work, or to fan out variants in parallel" -> "more compute, longer-running work, or parallel variants of the same task". Now all three list items are parallel noun phrases. - "Workspace state" bullet: "The cloud-to-local direction does not currently apply" -> "doesn't currently apply" (contractions are encouraged in the style guide for an approachable tone). local-to-cloud.mdx - "Use this handoff direction when:" list: first bullet started with "The task is going to run for a long time..." while the other three start with "You want...". Rewrote it to "You have a long-running task and don't want to keep your laptop awake." so all four bullets open the same way. - Step 1: "trigger handoff with the `&` shortcut or the `/handoff` slash command" -> "press `&` or run the `/handoff` slash command". Direct verbs match the style guide pattern for keyboard / slash commands. - Step 2: "Pick the environment whose..." -> "Pick the one whose..." (avoids repeating "environment" right after the bold header). "create one first and add" -> "create one and add" ("first" was doing no work). - Post-steps prose: "After submission, the cloud agent applies your workspace snapshot" -> "After you submit, the cloud agent...". Active voice; readers don't talk about "submission." - Troubleshooting (uncommitted changes): "Without it, the conversation can't be forked" -> "Otherwise, the conversation can't be forked". "Without it" had a fuzzy antecedent; "Otherwise" reads cleanly off the preceding sentence. cloud-to-cloud.mdx - "Use this handoff direction when:" list: first bullet "A cloud agent finished and you want to send a follow-up after the session has ended." -> "You want to send a follow-up to a cloud agent after its session has ended." Now parallel with the second bullet ("You want to continue an ambient agent run..."). - Cleaned up three lingering uses of "execution" that the earlier internals scrub missed. All three were re-introduced when applying Safia's audit-fix feedback in e4bdd4b. Replaced with "session": - "the new execution runs on the same Git branch as the prior session" -> "the new session continues on the same Git branch" (avoids both the internal term and the "new ... prior" cycle). - ":::caution Cloud-to-cloud handoff relies on a snapshot from the prior execution" -> "...the prior session". - "Click into the run to see the full transcript: each execution appears in order, and you can scan the transcript to see where one execution ended and the next began. Per-execution timestamps aren't currently exposed in the API..." -> all three "execution"s -> "session" / "Per-session". - "What carries over" trailing sentence: "...proceeds with what it could before continuing to your follow-up." -> "...rather than starting over silently." Now parallel with the same sentence on the other two handoff pages. - "Sending a follow-up" lead-in: dropped the orphan third sentence ("Send-follow-up support is available in the Warp app.") and folded it into the first: "you send a follow-up from the Warp app, and the run continues." - Step 2: "Type the next message into the conversation's input" -> "Enter the next message in the conversation's input" ("Enter" is the style guide's verb for text fields). - Troubleshooting (old runs): "Start a new cloud agent run with the prompt you want and reference the prior run in the prompt if needed." -> "Start a new cloud agent run with the prompt you want, referencing the prior run if needed." (drops the "prompt" repetition). Final grep over the handoff folder for "execution", "harness", "spiraled", "right move", "Cloud Agents", "Warp terminal" -> zero hits. Validation - python3 .agents/skills/style_lint/style_lint.py --changed -> 0 issues. - python3 .agents/skills/check_for_broken_links/check_links.py --internal-only -> 0 broken links (2,439 internal links across 321 files). Co-Authored-By: Oz <oz-agent@warp.dev>
I missed two of @rachaelrenk's review comments on the cloud-to-cloud page in earlier passes because they weren't returned by the first `gh pr view` query. Applying them now. cloud-to-cloud.mdx - "ambient agent run" -> "background cloud agent run". Rachael flagged "ambient agent run" as abstract/internal-feeling; "background cloud agent run" keeps the example concrete and matches the user-facing framing on the surrounding pages. Per her suggested edit verbatim. - Removed `blocked` from the example list of terminal states. The API treats BLOCKED as terminal for cancellation purposes, but the spec describes it as "awaiting user input or approval" — so it isn't a natural place to send a follow-up via cloud-to-cloud handoff (responding to the prompt on the original run is the right path). Added a sentence to the prereq calling that out explicitly so readers don't try to hand off a blocked run. Validation - python3 .agents/skills/style_lint/style_lint.py --changed -> 0 issues. - python3 .agents/skills/check_for_broken_links/check_links.py --internal-only -> 0 broken (2,439 internal links, 321 files). Co-Authored-By: Oz <oz-agent@warp.dev>
Two small consistency fixes caught on a third audit round:
- L29 "An ended cloud agent run" prereq: "Blocked runs ... aren't
continued through cloud-to-cloud handoff" -> "...can't be continued
via cloud-to-cloud handoff". Makes the carve-out parallel with the
very next sentence ("Very old runs ... can't be continued via
handoff"), and reads more directly than "aren't continued through".
- L30 "A snapshot from the prior session" prereq: "the run still
continues -- it just starts without restored workspace state" ->
"the run still continues, just without restored workspace state".
The em dash + "it just starts" was colloquial and a bit redundant
("continues" and "starts" describe the same event); the comma-led
adjective phrase is cleaner.
Validation
- python3 .agents/skills/style_lint/style_lint.py --changed -> 0 issues.
- python3 .agents/skills/check_for_broken_links/check_links.py
--internal-only -> 0 broken (2,439 internal links, 321 files).
Co-Authored-By: Oz <oz-agent@warp.dev>
The "cross-cutting sidebar PR" that the original PR description referred to doesn't exist — none of the orchestration-launch content is currently registered in `src/sidebar.ts`. PR #84 (multi-agent) doesn't touch the sidebar either; only PR #86 (memory) adds its own entries. Following that pattern: register the three handoff pages here so they actually appear in the docs sidebar when this branch merges. src/sidebar.ts - Added a new "Handoff" collapsible group inside the "Oz Cloud Agents & Orchestration" topic, slotted right after "Viewing cloud agent runs" since that's the closest thematic neighbor (it covers `Continue locally` / `/continue-locally`, the cloud-to-local path). The group contains: - Overview -> agent-platform/cloud-agents/handoff - Local to cloud -> agent-platform/cloud-agents/handoff/local-to-cloud - Cloud to cloud -> agent-platform/cloud-agents/handoff/cloud-to-cloud Mirrors the existing collapsible-group shape used by Triggers, Integrations, and Self-hosting in the same section. src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx - "(from the conversation details panel or the end-of-run tombstone)" -> "(from the conversation details panel or the artifacts shown after the run)". "Tombstone" is the internal code-level term for the post-run view (`shared_session/conversation_ended_tombstone_view.rs`). Even though it shows up in telemetry-event descriptions in `privacy.mdx`, it's not natural user-facing copy. Switched to a plainer reference to the artifacts surfaced after the run. Validation - python3 .agents/skills/style_lint/style_lint.py --changed -> 0 issues on the files this PR touches. (The pre-existing pricing-faqs.mdx warnings are out of scope.) - python3 .agents/skills/check_for_broken_links/check_links.py --internal-only -> 0 broken (2,440 links, 322 files). - `npm run build` fails on an UNRELATED orphan page (`agent-platform/cloud-agents/agents.mdx` is not registered in the sidebar). That page was added earlier on this branch by a different PR and is pre-existing breakage on `hyc/orch/handoff` — my edits don't touch it. Co-Authored-By: Oz <oz-agent@warp.dev>
This was referenced May 19, 2026
hongyi-chen
added a commit
that referenced
this pull request
May 19, 2026
…ries (#101) * Audit pass 3: Memory + Handoff polish, cross-references, glossary entries Final audit pass over hyc/orchestration-launch ahead of the rollout PR. Covers the deltas from #86 (Agent Memory research preview) and #85 (local\u2194cloud handoff) that landed after audit pass 2. Sentence case / Title Case: - capabilities/skills.mdx:414: '## Suggested Skills from Agent Memory' -> '## Suggested skills from Agent Memory'. The section body uses lowercase 'skill drafts', so the heading should match. Also clears the one new style_lint warning introduced by #86. Stale config: - agent-platform/agent-memory/index.mdx: drop '(Research Preview)' from the frontmatter sidebar.label. sidebar.ts already overrides the label to 'Agent Memory' under a group named 'Memory (Research Preview)'; the duplicate annotation was dead config. Cross-link gaps from neighboring pages: - cloud-agents/viewing-cloud-agent-runs.mdx (the '5. Fork the session to your local Warp' section): add a one-line reference to the new Handoff overview, so the cloud-to-local direction is discoverable from the broader handoff doc. - cloud-agents/managing-cloud-agents.mdx: add a Related pages section that links to the Handoff overview and the other neighbors that weren't surfaced before. - local-agents/cloud-conversations.mdx (Related features): add a link to the Handoff overview, since handoff relies on cloud-synced conversations. Style: - cloud-agents/handoff/index.mdx:30: drop 'just' from 'not just read about it' -> 'not only read about it'. Same ableist-language pattern audit pass 2 cleaned up elsewhere. Glossary additions: - .agents/references/terminology.md (Agent concepts) + AGENTS.md (Core features): add canonical entries for 'Agent Memory', 'memory store', and 'Handoff' so the launch terms ship with documented capitalization rules ('Agent Memory' Title Case as a feature; 'memory store' lowercase common noun; 'Handoff' Title Case as the feature, lowercase 'hand off' / 'handed off' as the verb). Validation: - check_links --internal-only: 0 broken across 2,543 internal links (up 6 from the 2,537 baseline, matching the 6 new cross-refs). - style_lint --changed: 14 warnings (one fewer than baseline; the skills.mdx Title Case heading is no longer flagged). The remaining warnings are all pre-existing proper-name false positives. - npm run build: 330 pages built; sidebar still resolves all slugs; new anchor reference (#5-fork-the-session-to-your-local-warp) resolves. Co-Authored-By: Oz <oz-agent@warp.dev> * Restore (Research Preview) suffix in agent-memory sidebar.label Revert the sidebar.label change from the audit pass. Keeping the research-preview annotation in the frontmatter as a defensive fallback in case the sidebar.ts override is ever removed. Co-Authored-By: Oz <oz-agent@warp.dev> --------- Co-authored-by: Oz <oz-agent@warp.dev>
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
3 participants
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.
Adds documentation for the Handoff feature shipping with the Oz Orchestration Launch (Maestro). Three new pages under a new
agent-platform/cloud-agents/handoff/directory cover the local↔cloud and cloud↔cloud handoff directions, plus an overview of what's preserved across a handoff. Cloud-to-local routes to the existing Viewing cloud agent runs page — the Continue locally affordance and/continue-locallyslash command are already documented there, and there isn't a dedicated cloud-to-local procedural in this PR.New pages
src/content/docs/agent-platform/cloud-agents/handoff/index.mdx— Conceptual overview: what handoff is, the three directions it supports, third-party agent runtime coverage, what carries over (conversation history, workspace state, conversation attachments), and when to use each direction.src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx— Procedural: promoting a local Warp Agent conversation to a cloud agent run via the&shortcut or/handoffslash command, including prerequisites, the workspace snapshot mechanics, and troubleshooting.src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx— Procedural: sending a follow-up to an ended cloud run so the run continues with the prior session's workspace state restored. Covers the Warp Agent flow, the third-party agent runtime Continue-button flow, and the per-session run identity model.Resolved review threads
e1da8dd,91cd3da, ande6bfba8. Scoped the snapshot mechanism to local↔cloud and cloud↔cloud (not cloud→local). Dropped the inaccurategit diff --binary HEADclaim. Softened the local-to-cloud entry point to&//handoffonly (with an explicit note that/cloud-agentis not a handoff entry point).e4bdd4b. Highlights: collapsed the duplicate "ambient agent run" bullet on the overview, called out the local→cloud handoff permission constraint, removed surfaces (Oz web app, API) that don't currently send follow-ups, and pinned per-session timestamps to the transcript rather than the API.b45a4e8. User-facing terminology ("Warp session" instead of "Warp terminal", "third-party agent runtimes" instead of "harnesses"), direct Oz web app deep links to the Runs page, sentence-case nav text consistency, and minor copy polish.Final senior-copywriter pass (commit
b45a4e8)On top of Rachael's suggestions, applied the same patterns to
cloud-to-cloud.mdxfor consistency:### Third-party harnessesheading that was sitting above the correct### Third-party agent runtimesheading, and fixed a missing blank line before the next##section.Validation
python3 .agents/skills/style_lint/style_lint.py --changed— clean (0 issues).python3 .agents/skills/check_for_broken_links/check_links.py --internal-only— clean (2,439 internal links across 321 files).File scope
Strictly within the listed handoff pages. No edits to
src/sidebar.ts,vercel.json, or any top-level/cross-cutting landing pages — those are reserved for the follow-up sidebar PR.For the engineering reviewer
local_to_cloud_handoffandcloud_to_cloud_handoffare not set inprod.yamltoday (only staging/local);OzHandoffis inDOGFOOD_FLAGS. The pages assume these are on at launch — confirm before merging.Co-Authored-By: Oz oz-agent@warp.dev