1@README.md
2
3## Notes for agents
4
5**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`.
6
7**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.
8
9**`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.
10
11**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`.
12
13**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.