For agents, on top of README.md, which they read first.

Notes for agents

Keep it stateless toward the Worker. One HTTP request per message (plus the dev tool-list poll) is what lets the Worker restart under a running session. A held connection or cached MCP session would bring back the restart-both problem this replaced (2026-09-24). The OAuth tokens are the one thing it holds, and only in memory.

No tokens on disk, ever. Not the access token, not the refresh token, not a cache of either. A new session signing in once is the cost, and it is the intended one.

One dependency, outside the workspace. The MCP SDK, pinned in package.json, for auth(). It is not a pnpm workspace package, so the SDK stays out of the site's pnpm closure and hash; nix fetches package-lock.json by each entry's integrity (importNpmLock in nix/strudel.nix), so there is no hash to update. After changing package.json, run npm install here and commit the lockfile. For running it from the tree, npm install here first.

Never poll prod. Every request there counts against the user's MCP rate (120 a minute); prod's tools change only with a deploy.

Opening the browser: rundll32.exe url.dll,FileProtocolHandler, not explorer.exe or cmd.exe /c start. Measured 2026-09-26: explorer.exe exited 1 and opened nothing; cmd splits the URL at &. windows-exec cannot show a window (session 0). The Windows browser's request to http://127.0.0.1:<port> reaches a listener on 127.0.0.1 in the guest.

Test-only environment: JEVSTRUDEL_PROD_MCP_URL points prod at a local production Worker, JEVSTRUDEL_MCP_OPEN_BROWSER=0 opens nothing (the test's headless browser reads the URL from stderr instead). .mcp.json sets neither.