add legacy warning to agent dom mode

[tkattkat]

why

we want to move towards hybrid mode being the default

what changed

added a legacy warning when using dom mode recommends hybrid mode and links out to hybrid mode docs

test plan

---

Summary by cubic

The agent now logs a legacy warning when mode isn’t specified (defaults to DOM), recommending hybrid mode for better performance with a link to the Agent docs. Docs navigation was updated to surface Agent basics and reference.

^{Written for commit 8898e28. Summary will update on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 8898e28

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[greptile-apps]

Greptile Summary

This PR adds a deprecation warning for DOM mode in the agent, recommending users migrate to hybrid mode. The warning is logged at level 0 (visible) when an agent is instantiated with mode: "dom" (or when mode is not specified, since DOM is the default). The warning message includes a link to the hybrid mode documentation. Additionally, the docs navigation has been reorganized to prioritize agent documentation, moving it to the top of both the "Basics" and "References" sections.

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The changes are straightforward and non-breaking. The warning is added in the constructor and only logs information without affecting functionality. The documentation reordering is a simple navigation change. No logic changes or potential runtime issues.
• No files require special attention

Important Files Changed

Filename	Overview
packages/core/lib/v3/handlers/v3AgentHandler.ts	Added warning log when DOM mode is used, recommending hybrid mode with link to documentation
.changeset/proud-ads-live.md	Added changeset documenting the deprecation warning for DOM mode
packages/docs/docs.json	Reordered documentation to prioritize agent docs over other methods in the navigation

Sequence Diagram

sequenceDiagram
    participant User
    participant V3AgentHandler
    participant Logger
    
    User->>V3AgentHandler: new V3AgentHandler(mode: "dom")
    V3AgentHandler->>V3AgentHandler: Check if mode === "dom"
    V3AgentHandler->>Logger: Log warning message
    Logger-->>User: Display: "Using DOM mode (legacy)..."
    V3AgentHandler-->>User: Return agent instance

Loading

[cubic-dev-ai]

No issues found across 3 files

[miguelg719]

we should say

Suggested change

	"Using DOM mode (legacy). Consider using mode: 'hybrid' for improved performance.\n → https://docs.stagehand.dev/v3/basics/agent\n",
	"Using default DOM mode in agent (legacy). Consider using mode: 'hybrid' for improved performance.\n → https://docs.stagehand.dev/v3/basics/agent\n",