feat(stagehand): revamp Stagehand + Valkey cookbook

[atao2004]

Summary

Migrates the archived Stagehand + Valkey cookbook (TypeScript + Python tracks) from archive/main-pre-reorg (closed PR #32, closed during the repo reorganization, not for content reasons) to the current CONTRIBUTING.md structure.

Stagehand is Browserbase's open-source browser automation framework. Valkey caching support is implemented in two upstream PRs that are open but not yet merged:

• browserbase/stagehand#2264 (core server, TypeScript)
• browserbase/stagehand-python#346 (Python SDK)

Changes from the archived version

• Added the **Who is this for:** audience line to all 6 cookbook files (missing from the archive)
• Moved the security callout in both 01 files to after the Docker startup command (was before it)
• Pinned valkey/valkey-bundle:latest → 8.1.7 everywhere (4 locations)
• Added a Configuration Reference table to both 03 files, with defaults verified directly against the fork source (not just the PR description)
• Added the required sample/ test file for each track (the archived PR had none): cache-contract.test.ts (vitest + iovalkey) and test_valkey_cache_config.py (pytest + valkey), both exercising the documented key scheme/TTL/command contract against a real Valkey container — no paid services needed
• Added .github/workflows/cookbook-ts.yml and cookbook-python.yml (temporary per-cookbook copies, following the pattern used by other in-flight cookbook PRs until the shared workflow lands)
• Dropped meta.json (not part of the current convention)
• Switched KEYS → SCAN in the cache-inspection step
• Added try/finally around client cleanup in a few inline snippets that were missing it

Real inaccuracies caught by verifying against the actual fork source

The archived cookbook's claims were checked against the PR description; this revamp reads the actual diffs/files at the pinned commits instead, which surfaced:

• VALKEY_CACHE_TTL vs CACHE_TTL: the core server's env-var fallback reads VALKEY_CACHE_TTL, but the Python SDK's local-mode process-env builder forwards valkey_cache_ttl as CACHE_TTL — the two forks disagree on this one name. Documented as a caveat; the request-body/session-dict path (recommended) is unaffected.
• Local-mode caveat cited the wrong mechanism: a comment in the Python fork's own source blames a @valkey/valkey-glide native addon. The actual TS core implementation (CacheStorage.ts) dynamically imports iovalkey (plain JS, no native addon at all) — verified directly. Corrected to the real mechanism (the SEA binary doesn't bundle the dynamically-imported optional dependency).
• valkeyTls default: documented as unconditionally false; it's actually true when a password is set (verified in CacheStorage.ts and the Python SDK's own field docstring).
• TS build command: npm installing the fork directly fails (triggers the monorepo's full prepare script). The documented recipe clones + builds packages/core specifically via npx turbo run build --filter=@browserbasehq/stagehand (a plain pnpm --filter ... run build silently succeeds only if stale generated files already happen to exist on disk — verified this the hard way against a genuinely fresh clone).

Validation

• markdownlint-cli2 (pinned to the exact version this repo's CI action bundles, 0.17.2): 0 errors
• TypeScript track: fresh fork clone → npx turbo run build --filter=@browserbasehq/stagehand → npm ci → npx tsc --noEmit (passes, validates demo.ts's API usage against the real built package) → npm test (4/4 vitest tests pass against a live Valkey container)
• Python track: pip install -r requirements.txt (installs cleanly from the fork via git+https) → pytest test_valkey_cache_config.py -v (5/5 pass against a live Valkey container)
• Independently confirmed the Stagehand server itself boots from the fork via pnpm install --ignore-scripts + npx tsx src/server.ts (no build step needed for the Python track's recipe) — real HTTP 200 on /healthz
• Two independent review passes: a general code/security review, and a line-by-line verification of every documented API claim against the actual fork source. Findings from both were fixed (a test had act/agent key variables swapped in naming, a couple of cross-doc links pointed at notes that didn't exist in the target file) and are reflected in the diff.

Cookbook structure

cookbooks/framework-integrations/
├── stagehand/                    (TypeScript track)
│   ├── README.md, 01-getting-started.md, 02-cache-categories-and-ttl.md, 03-production-configuration.md
│   └── sample/  demo.ts, __tests__/cache-contract.test.ts, package.json, package-lock.json,
│                tsconfig.json, vitest.config.ts, docker-compose.yml, .gitignore, README.md
└── stagehand-python/             (Python track)
    ├── README.md, 01-getting-started.md, 02-cache-categories-and-ttl.md, 03-production-configuration.md
    └── sample/  demo.py, test_valkey_cache_config.py, requirements.txt, docker-compose.yml, .gitignore, README.md

.github/workflows/cookbook-ts.yml       (new, temporary — matrix: [stagehand])
.github/workflows/cookbook-python.yml   (new, temporary — matrix: [stagehand-python])

Relationship to other PRs

Draft — will stay open until browserbase/stagehand#2264 and browserbase/stagehand-python#346 show real merge progress. Once either merges and releases, the corresponding track's install instructions switch from the fork to the published package (each doc/README already notes exactly what changes).

Pre-Submit Checklist

• Builds and runs from a clean clone (verified against a genuinely fresh fork clone, not a partially-built one)
• Runs against current stable Valkey (valkey/valkey-bundle:8.1.7, pinned)
• No private links, internal references, or local paths
• No marketing language or uncited claims
• Vendor-neutral by default; Browserbase affiliation disclosed
• README explains the Valkey concept demonstrated, prerequisites, and how to run
• Dependencies pinned to specific versions (including the fork commits, with a note on switching to the release once available)
• CI validates the sample

[jbrinkman]

Closing this draft PR as part of a cookbook program cleanup.