[akeimach]

why

Update docs to describe new caching workflow

what changed

test plan

---

Summary by cubic

Updates the docs to reflect that server-side caching for Browserbase projects is now opt-in instead of on by default.

• V3 and V4 guides and API references now explain that caching is off until a project requests it via Browserbase support.
• The cache/serverCache options still work, but only after project-level enabling; cacheStatus is undefined when disabled.

^{Written for commit 2ddacfe. Summary will update on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2ddacfe

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[cubic-dev-ai]

All reported issues were addressed across 15 files

Architecture diagram

sequenceDiagram
    participant Dev as Developer
    participant Docs as Stagehand Docs
    participant Support as Browserbase Support
    participant App as Stagehand App
    participant Browserbase as Browserbase Platform

    Note over Dev,Browserbase: NEW: Server-side caching is now opt-in per project

    Dev->>Docs: Read caching docs
    Docs-->>Dev: Caching requires project enablement

    Dev->>Support: Email request with project ID
    Support->>Browserbase: Enable caching for project
    Support-->>Dev: Caching enabled confirmation

    Dev->>App: Stagehand.create({ env: "BROWSERBASE" })
    App->>Browserbase: init browser session
    Browserbase-->>App: Session ready

    alt Caching enabled for project
        App->>App: act/extract/observe with cache option
        App->>Browserbase: Send request with cache key
        alt Cache hit
            Browserbase-->>App: cached result
            App-->>Dev: cacheStatus: "HIT"
        else Cache miss
            Browserbase->>Browserbase: Run LLM inference
            Browserbase-->>App: fresh result (cached server-side)
            App-->>Dev: cacheStatus: "MISS"
        end
    else Caching not enabled for project
        App->>Browserbase: Send request (no cache)
        Browserbase-->>App: result
        App-->>Dev: cacheStatus: undefined
    end

    Note over App,Browserbase: Locator-scoped calls bypass cache (status: DISABLED)

Loading

<sub>Tip: Get a Slack DM when cubic finishes reviewing your PRs. Connect Slack

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>