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

Notes for agents

Write tooling here in Node, not shell. The user asked for it (2026-09-24), and it is the better fit: spawn(…, { env }) states the Worker's whole environment in one line where bash needed a regex over export -p, and health checks are a fetch.

Ports are set once each. The site's in website/astro.config.mjs (server.port, 4322); the dev Worker's in worker/wrangler.json (dev.port, 4323), which the Astro proxy, the MCP proxy and dev.mjs all read; the preview's in preview.mjs (PREVIEW_PORT, 4324). A second pair beside the user's (an agent's worktree) runs on its own ports without touching theirs: wrangler dev … --port 4342 through worker.mjs, and JEV_WORKER_PORT=4342 pnpm exec astro dev --port 4341 in website/, which points the Astro proxy at that Worker.

worker.mjs passes wrangler an allowlisted environment. wrangler hands the Worker every variable it is given, and inside op-env-run that is every secret in the 1Password environment. Both launchers go through it; never spawn wrangler around it.

Keep the health check. The Worker has failed silently twice (2026-09-24): wrangler exiting with an empty error, and a restarted runtime that listened but never answered. Only a check that expects an HTTP answer catches the second. It lives once, in supervise.mjs.

The preview must stay what deploys. It serves nix build .#static, the derivation nix run .#deploy uploads, and the production config (--env ""). Never point it at a separately built site or give it the dev environment: the point is hearing exactly what the public will. Its local state is worker/.wrangler/preview, apart from the dev Worker's.