Document terminal E2E verification gate

tools/TERMINAL_E2E.md

@@ -2,6 +2,15 @@
 
 `zig build terminal-e2e` runs `tools/terminal_e2e.py` against the compiled `mim`
 binary and writes ignored artifacts under `.zig-cache/terminal-e2e/<scenario>/`.
+It is the canonical local gate for terminal rendering/input/panel/workflow slices
+(NS10). Run it after `zig build`, `zig build test`, and `zig build v1-smoke` when
+a change can affect terminal-visible behavior; pure protocol/headless or docs-only
+changes may use cheaper checks unless their claim is terminal-visible.
+
+The command is expected to finish in seconds on a normal development machine
+(current matrix target: under 30s). A timeout or nonzero exit should be treated as
+a product regression or harness bug, not a flaky benchmark: inspect the scenario
+artifact directory named in the failure output.
 
 Matrix input profiles:
 
@@ -36,6 +45,17 @@ Artifact roles:
   this is not a runtime config surface.
 - `raw.bin`: exact PTY bytes for low-level debugging.
 
+Failure triage:
+
+1. Start with the scenario directory reported by the command.
+2. Read `manifest.tsv` for hashes, CR/LF status, ANSI roles, key budget, and
+   artifact list.
+3. Read `visible-controls.normalized.txt` for visible `␍`, `␊`, `␛`, and path
+   normalized raw terminal evidence.
+4. Read `transcript.txt`, `widths.tsv`, `keystrokes.tsv`, and any
+   `saved-files.tsv` for semantic assertions before inspecting screenshots.
+5. Use `screenshot.svg`/`terminal.html` to explain what a user would see.
+
 Golden policy:
 
 - Investigate before updating any expected artifact or assertion.