docs: promote Warp Factories navigation (Phase 2)

[rachaelrenk]

Summary

Promotes Warp Factories to the first product tab, makes the root product overview the Factory-tab destination, and gives Warp Terminal its own overview page. This PR now contains only Phase 2 navigation work on main, independent of the later migration and naming phases.

Changes

• Moves Factories to the first sidebar tab and Automation Platform immediately after it.
• Makes / the Factory-tab destination and adds Warp products as the first entry in Factories Overview. The existing root product overview is unchanged.
• Adds /terminal/ as the Terminal overview and restructures Terminal navigation into Overview followed by Get started.
• Preserves the Automation Platform's standalone overview and Cloud agents group.
• Narrows sidebar labels to strings before looking up topic order, fixing the two TypeScript errors caused by the plugin's translated-label union type.

Related issues

• GROW-6142: Phase 2 navigation
• GROW-6127: Factory launch docs
• Phase 1 landed in PR #748 on October 6.

Content design plan

Audience and JTBD: A developer choosing where to start in the docs who needs the product tabs to match Warp's launch product hierarchy.

Problem: The Terminal tab currently owns the root product overview, while Warp Factories remains visually secondary.

Goals: Put Factories first, keep Warp products discoverable at /, and give Terminal a clear product overview plus a separate onboarding path.

Content type: Conceptual navigation and overview update.

High-impact scenarios: Covers a new visitor entering the Factory tab, a Terminal user finding terminal documentation, and a cloud-agent user retaining the Automation Platform path.

Staging and handoff

• Base - main. Rebasing onto current origin/main completed without conflicts on October 8.
• Scope - Replayed only the launch-specific commits above the Phase 1 branch. The resulting diff touches two files: src/sidebar.ts and src/content/docs/terminal/index.mdx.
• Branch - rrenk/factories-launch-phases-2-4; the name is retained to preserve the existing PR, but this PR is now Phase 2 only.
• Workspace - /Users/rachaelrenk/Documents/Warp/docs-factories-launch-phases-2-4.
• Recovery - Original local history is preserved on backup/factories-launch-pre-rebase-20261008.

Validation

Local validation on October 8:

• npm ci - completed with lockfile-pinned dependencies.
• npm run typecheck - passed with 0 errors and 7 hints.
• npm run build - passed.
• npm run test:homepage-json-ld - passed.
• python3 .agents/skills/check_for_broken_links/check_links.py --internal-only - passed with 0 broken links across 4,366 internal links.
• python3 scripts/test_check_redirects.py - passed all 3 tests.
• python3 .agents/skills/style_lint/style_lint.py --changed - passed with two non-blocking product-casing warnings. "Warp Terminal" is retained in the page title and product-comparison link description to distinguish the terminal product.
• python3 .agents/skills/validate_ui_refs/validate_ui_refs.py --changed --require-provenance - passed with 0 issues.
• git diff --check - passed.

Trunk is not installed locally. Node v25 is outside the project's supported runtime range; GitHub CI uses Node 22. Dependency installation also reported existing audit findings and a starlight-llms-txt patch-version warning; this PR does not change dependencies.

Follow-ups

These are outside this PR and do not hold Phase 2 for implementation:

• GROW-6143: Oz web-app documentation migration, after destination workflows, names, and dates are confirmed.
• GROW-6144: Remaining GA naming cleanup, after the relevant product changes ship. Existing availability badges and transition wording are unchanged here.

Unverified claims

None. The new Terminal overview summarizes existing documented capabilities; this PR adds no new product behavior or availability claims.

Documentation risk

Risk: engineering-review-required
Rationale: Changes published navigation order and the root and Terminal documentation entry points.
Source files consulted: GROW-6142, src/sidebar.ts, src/content/docs/index.mdx, src/content/docs/factories/index.mdx, and existing Terminal documentation pages.
Requested engineering reviewers: none
Engineering review status: pending
Docs override: none

Agent context

Conversation

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

[vercel]

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

Project	Deployment	Actions	Updated
docs	Ready	Preview	Oct 9, 2026 1:43pm UTC

[warp-for-oss]

@rachaelrenk

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

You can view the conversation on Warp.

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

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

Powered by Oz

[warp-for-oss]

Overview

This PR stages the Phase 2 documentation navigation update by adding a Terminal overview page, moving the Terminal tab to /terminal/, making the Factories tab point at the root product overview, and sorting the top-level sidebar topics into the launch order.

Concerns

• No blocking general, security, or spec-alignment concerns found in the attached diff. spec_context.md reports that no approved or repository spec context was found, so there was no implementation spec to compare against.

Verdict

Found: 0 critical, 0 important, 0 suggestions

Approve

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

Powered by Oz

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/sidebar.ts:391 — [IMPORTANT] Making / the Factories topic leaves src/components/CustomSidebar.astro (breadcrumbFromUrl: if (segments.length === 0) return TOPIC_LABELS.terminal;) labeling the root page's search result "Terminal", although the root now sits under the Factories tab. Requested change: update that fallback so the root breadcrumb matches the new navigation (for example TOPIC_LABELS.factories or a neutral products label) and update any adjacent comment.
• src/sidebar.ts:933 — [SUGGESTION] Reordering topics with a post-hoc sidebarTopics.sort(...) and a phaseTwoTopicOrder map makes the array literal disagree with the rendered order, silently sorts unlisted topics last, and bakes a launch-phase name into the source. Requested change: move the Factories and Automation Platform entries to the top of the sidebarTopics literal and delete the Map and sort block, or rename it to topicOrder and add a comment explaining why the literal isn't reordered.
• src/content/docs/terminal/index.mdx:10 — [SUGGESTION] The opening paragraph ("combines a terminal, editor, and agent workspace in one application... without leaving your local development environment") reads as a product pitch, against AGENTS.md Voice & tone. Requested change: replace it with one or two plain declarative sentences stating what Warp Terminal does, and cut the "without leaving..." tail.
• src/content/docs/terminal/index.mdx:14 — [SUGGESTION] Each bullet on lines 14-18 bolds a feature name and then repeats it in a trailing "See same name" link, and line 14 says "Terminal Blocks" while the other links use lowercase names. Requested change: link the bold term itself (for example **[Blocks](/terminal/blocks/)**), drop the "See ..." tails, and make link text consistent.
• src/content/docs/terminal/index.mdx:20 — [SUGGESTION] The "Get started" H2 holds one sentence linking to the quickstart, and the [Agents](/agents/) Related pages link on line 28 has generic text. Requested change: fold the quickstart link into the intro or the first Related pages bullet and remove the separate H2, and rename the Agents link to say what the reader finds, such as "Agents in Warp".

Verdict

Request changes