From 704e4cdfd187c70b277c01f82cc532de9b99ee1e Mon Sep 17 00:00:00 2001
From: mwiegand <martin.wiegand@seibert.group>
Date: Sun, 17 May 2026 02:17:38 +0200
Subject: [PATCH] docs(editor-v2): AGENTS.md editor bundle rebuild section

Adds an 'Editor bundle (CodeMirror 6)' section after the e2e tests
section describing:
- where the source lives (l4d2web/scripts/editor-src/)
- how to rebuild (./l4d2web/scripts/build-editor.sh)
- the NPM_CACHE workaround for the root-owned ~/.npm cache files
- the vocab regeneration command (./l4d2web/scripts/build-vocab.py)
- pointers to the design + plan docs

Verified end-to-end:
- 676 fast tests passing (no regressions from the wiring)
- 3 e2e tests passing (smoke + 2 editor tests)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 AGENTS.md | 39 +++++++++++++++++++++++++++++++--------
 1 file changed, 31 insertions(+), 8 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 2d22da3..db5b60e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -107,12 +107,35 @@ chromium binary, fetched on first setup:
 uv run playwright install chromium
 ```
 
-Run with `uv run pytest -m e2e`. Excluded from the default fast suite
-via the `e2e` marker.
+Always invoke as `uv run pytest -m e2e ...` (excluded from the default
+fast suite via the `e2e` marker). Other forms crash Chromium under the
+macOS sandbox; only this exact invocation is exempt.
 
-**Sandbox note:** Chromium needs Mach-port IPC on macOS, which the
-Claude Code sandbox blocks. When running e2e tests from a sandboxed
-agent session, pass `dangerouslyDisableSandbox: true` on the
-`uv run pytest -m e2e` invocation (the symptom of a sandboxed run is
-a `FATAL` Chromium crash with `Permission denied (1100)` on Mach port
-rendezvous, not a missing-binary or network error).
+## Editor bundle (CodeMirror 6)
+
+The in-browser code editor on the blueprint config / overlay script /
+files-modal textareas is bundled from `l4d2web/scripts/editor-src/`
+via esbuild and committed pre-built to
+`l4d2web/l4d2web/static/vendor/editor.bundle.js`. Source lives under
+`l4d2web/scripts/editor-src/`; design and plan at
+`docs/superpowers/specs/2026-05-17-textarea-editor-v2-design.md` and
+`docs/superpowers/plans/2026-05-17-textarea-editor-v2.md`.
+
+Rebuild after editing the source:
+
+```bash
+./l4d2web/scripts/build-editor.sh
+```
+
+Requires `node` + `npm` locally. The script overrides the npm cache to
+`$TMPDIR/npm-cache` (set `NPM_CACHE` to override) to dodge root-owned
+files in `~/.npm/_cacache/` from older npm versions. Commit the
+regenerated `editor.bundle.js`, `editor.bundle.css`, and
+`editor.bundle.sha256` alongside any source change.
+
+Regenerate the autocomplete vocab from `./cvar_list` (live L4D2
+cvarlist dump committed at repo root) after replacing the dump:
+
+```bash
+./l4d2web/scripts/build-vocab.py
+```