[STG-1482] Update caching docs: split into Browserbase Cache and Local Cache sections

[derekmeegan]

Summary

Restructures the caching best practices docs page into two clear sections:

Changes

• Removed the disclaimer/note about server-side caching only working with env: "BROWSERBASE" — this is now naturally conveyed in the section description
• Renamed "Server-side Caching" → "Browserbase Cache" with a clear description of what it is (managed, server-side, automatic, zero-config)
• Renamed "Local Caching" → "Local Cache" with a clear description of what it is (file-based, works everywhere, portable)
• Added use-case bullets to the Local Cache section explaining when to reach for it (agent workflows, CI/CD, local dev, cross-machine sharing)
• Preserved all existing code snippets, configuration examples, and best practices

What stays the same

• All code examples (disabling on constructor, disabling per call, inspecting cache status, act/agent caching, cache directory organization)
• The limitations section for Browserbase Cache
• The best practices accordion (descriptive dirs, clearing cache, committing for CI/CD)
• The blog link for deeper technical details

Only modifies packages/docs/v3/best-practices/caching.mdx.

Linear: https://linear.app/browserbase/issue/STG-1482

[changeset-bot]

⚠️ No Changeset found

Latest commit: 6d9c307

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]

cubic analysis

No issues found across 1 file

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Linked issue analysis

Linked issue: STG-1482: Update caching docs: split into Browserbase Cache and Local Cache sections

Status	Acceptance criteria	Notes
✅	Remove the disclaimer about server caching	Removed block and integrated into Browserbase section text
✅	Create two clear sections: Browserbase Cache and Local Cache	Headings renamed to 'Browserbase Cache' and 'Local Cache'
✅	Add code snippets and descriptions for each caching strategy	Descriptions added and existing act()/agent()/cacheDir examples preserved

Architecture diagram

sequenceDiagram
    participant App as User Script
    participant SDK as Stagehand SDK
    participant FS as Local FileSystem
    participant BB as Browserbase API
    participant LLM as LLM Provider

    Note over App,LLM: Runtime Caching Strategy Flow

    App->>SDK: act() / extract() / agent()
    
    == Local Cache Check ==
    opt if cacheDir is provided
        SDK->>FS: NEW: Check for cached file (hash of inputs)
        alt Local HIT
            FS-->>SDK: Return cached result
            SDK-->>App: Return Result (Instant)
        end
    end

    == Execution / Remote Cache ==
    Note right of SDK: Local MISS or no cacheDir
    
    alt env: "BROWSERBASE"
        SDK->>BB: CHANGED: Request execution (act/extract/observe)
        BB->>BB: CHANGED: Check Browserbase Cache (Managed)
        
        alt Browserbase HIT
            BB-->>SDK: Return result + cacheStatus: "HIT"
        else Browserbase MISS
            BB->>LLM: Execute inference
            LLM-->>BB: Response
            BB->>BB: Store in Managed Cache
            BB-->>SDK: Return result + cacheStatus: "MISS"
        end
        
    else env: "LOCAL"
        SDK->>LLM: Execute inference
        LLM-->>SDK: Response
    end

    == Persistence ==
    opt if cacheDir is provided
        SDK->>FS: NEW: Write result to local file
    end

    SDK-->>App: Return Final Result

Loading

[greptile-apps]

Greptile Summary

Improved caching documentation clarity by renaming sections to "Browserbase Cache" and "Local Cache", removing redundant notes, and adding helpful use-case bullets for Local Cache. All code examples and functionality preserved.

• Renamed "Server-side Caching" → "Browserbase Cache" with clearer description of managed, server-side caching
• Renamed "Local Caching" → "Local Cache" with enhanced description and use-case bullets (agent workflows, CI/CD, local dev, cross-machine sharing)
• Removed redundant note about BROWSERBASE-only requirement (now naturally conveyed in section description)
• Formatting improvements from prettier/linting (quote style, line breaks)

Confidence Score: 5/5

• This PR is safe to merge with no risk
• Documentation-only change that improves clarity and organization without modifying any functionality. All code examples preserved, no broken links, formatting changes consistent with project standards.
• No files require special attention

Important Files Changed

Filename	Overview
packages/docs/v3/best-practices/caching.mdx	Documentation restructured with clearer section names and enhanced descriptions; formatting improvements from prettier

_{Last reviewed commit: 75bca72}

[greptile-apps]

_{1 file reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}