docs: terminology sweep - CLI/API reference sunset callouts (GROW-6090) - #593
docs: terminology sweep - CLI/API reference sunset callouts (GROW-6090)#593warp-agent-staging[bot] wants to merge 2 commits into
Conversation
Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
This PR was generated with Warp. Comment    |
- fix stale Aug-18 comment in vars.ts to match the 9/15 holdout - scope the 'no warp equivalents' claim to what the Warp Agent CLI reference documents, instead of asserting nothing exists anywhere (the 2025 changelog already lists warp environment/integration list) - drop the unsupported 'for these workflows' claim from the shared subpage callout; keep the reference-scoped claim only on the CLI landing page and the API & SDK note - replace 'haven't' with 'have not' phrasing per AGENTS.md Co-Authored-By: Oz <oz-agent@warp.dev>
![warp-agent-staging[bot]](https://avatars.githubusercontent.com/in/2196476?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
Terminology sweep for GROW-6090: sidebar audit (no changes needed), a date-consistency fix in the glossary, and new sunset callouts on the CLI and API & SDK reference pages. One open question needs a human decision before this is safe to merge.
Concerns
- Three different September dates are now in play and they do not reconcile. The glossary says the Oz CLI is retired and wrapped into the Warp Agent CLI on 2026-09-15, these callouts say
ozcommands remain supported through the end of September 2026, and GROW-6090 refers to a September 19 cutover. Nothing here states which executable acceptsozcommands in the gap after 9/15, so a reader who follows the callout has no migration path for the last two weeks of the support window. Confirm whether 9/15 is only the naming/binary migration with end-of-September as legacy-syntax compatibility — and if so, what accepts the legacy syntax — or pick one authoritative date and the callouts will be rewritten to it. - Related and still open from the ticket itself: the successor name for the Oz API is unconfirmed, so this PR deliberately ships no backwards-compatibility callout for the Oz API to Warp API/SDK migration and leaves
API_SDK_NAMEuntouched. That omission is intentional, not a gap. Once the name is confirmed, the callout and the variable flip are a small follow-up.
Verdict
Checks: build pass, tests pass, CI green, visual proof present
Found: 0 critical, 1 important, 0 suggestions, 0 nits
Five further findings were raised in review and are already addressed on this branch in commit 433a697: a stale 2026-08-18 date in src/data/vars.ts, an over-broad "no warp equivalents exist" claim contradicted by the 2025 changelog, subpage callout wording with no referent, a contraction in a formal warning, and the missing visual proof.
Summary
Terminology sweep for GROW-6090: verification-and-gap-filling pass over sidebar labels, the style guide/glossary, and new CLI/API reference callouts for the
oz->warpCLI sunset window.Ref: GROW-6090
Changes
1. Sidebar label audit (
src/sidebar.ts)No changes. Audited every remaining "Oz" occurrence:
platform/oz-web-apprenders throughVARS.WEB_APP(deliberate holdout, matches "What still says Oz").reference/clilegacy label renders through${VARS.WARP_AGENT_CLI} (legacy)(deliberate holdout).reference/api-and-sdklabel renders throughVARS.API_SDK_NAME(deliberate holdout).No stale hardcoded "Oz" labels found.
2. Style guide / glossary pass (
AGENTS.md,.agents/references/terminology.md)terminology.md: the "Warp Agent CLI" usage note said the Oz CLI is retired "at the next launch (approximately August 18, 2026)", which contradicted the canonical "What still says Oz" holdout date of 2026-09-15 (andvars.ts) elsewhere in the same file. Updated the note to point at 2026-09-15 and added the newoz-commands-supported-through-September fact from this ticket.AGENTS.md's Terminology standards section againstterminology.md(Core terms, Oz CLI commands list, Terms to avoid, Automation Platform article rule, Warp Factories rules) — all consistent, no other gaps found.3. CLI/API reference callouts (substantive new work)
src/content/docs/reference/cli/index.mdx(landing page): the deprecation:::cautionstates thatozcommands remain supported through the end of September 2026, and that the Warp Agent CLI reference does not yet documentwarpequivalents for every workflow on the page.agent-profiles,api-keys,artifacts,federate,integration-setup,mcp-servers,quickstart,skills,troubleshooting,warp-drive): kept each page's existing deprecation:::caution, adding only the September 2026 support-window fact (no page-specific "workflows" claim, since that wording didn't fit pages likeartifactsorfederate).src/content/docs/reference/api-and-sdk/index.mdx: added a:::notescoping the same September 2026 window to theozcommand examples referenced from this reference (e.g.oz environment list), and noting the Warp Agent CLI reference doesn't document awarpequivalent yet.Revisions from review
src/data/vars.ts: fixed a stale comment that still said the Oz CLI migration happens "at the next launch, approximately 2026-08-18" — now matches the 2026-09-15 holdout date used everywhere else (variable value unchanged).warpCLI command exists anywhere, which the 2025 changelog contradicts (warp environment list,warp integration listare already documented there from an earlier CLI surface). Reworded every callout to scope the claim to what the Warp Agent CLI reference documents today, rather than asserting non-existence.artifacts,federate,mcp-servers,skills, andagent-profiles. Those pages now carry only the September 2026 support-window fact; the reference-scoped claim lives on the CLI landing page and the API & SDK note.Out of scope (needs a human decision)
API_SDK_NAMEinvars.ts. A safe, successor-name-free version of that callout is possible (e.g. "the Oz API & SDK name changes soon; endpoints and existing SDK versions keep working") but I left it undone rather than guess.Overlap with PR #583
Reviewed
factory/rev-38-docs-audit-findings(#583). It touchesterminology.md(Launch Configuration, Computer Use, Full Terminal Use, ZDR, SSO entries — unrelated to the Automation Platform/Oz sections) andagents/cli/quickstart.mdx,agents/cli/reference.mdx,reference/cli/mcp-servers.mdx(the Warp Agent CLI docs, not the legacyreference/cli/Oz CLI reference this PR touches, exceptmcp-servers.mdxwhere PR #583 renamed a heading unrelated to the callout lines this PR edits). No line-level collisions expected between the two PRs.Verification
npm run build— succeeds, no errors.python3 .agents/skills/style_lint/style_lint.py --changed— no new issues on edited lines (pre-existing, unrelated warnings in touched files were left alone to keep the diff scoped).python3 .agents/skills/style_lint/test_platform_determiner.pyandtest_factory_proper_noun.py— all pass.python3 .agents/skills/check_for_broken_links/check_links.py --internal-only— 0 broken links across 3859 internal links.Computer-use screenshots (3)
Page 1 (/reference/cli/) - "Oz CLI reference" title with top "Caution" callout box fully visible after hard reload
Page 2 (/reference/api-and-sdk/) - "Oz API & SDK reference" title with top "Note" callout box fully visible after hard reload
Page 3 (/reference/cli/quickstart/) - "CLI quickstart" title with top "Caution" callout box fully visible after hard reload