Document terminal E2E verification gate

AGENTS.md

@@ -38,6 +38,19 @@ zig build v1-smoke
 zig build run -- --help
 ```
 
+Canonical terminal/browser E2E check for terminal rendering, raw input, panels,
+KEYMAP workflows, LSP/tool workflow reachability, viewport/chrome/color behavior,
+or NS10 work:
+
+```sh
+zig build terminal-e2e
+```
+
+Run `terminal-e2e` after the regular build/test checks for behavior slices that
+touch terminal UI, input, panel focus, workflow routing, or screenshot-visible
+rendering. It writes ignored artifacts under `.zig-cache/terminal-e2e/`; a clean
+source tree must remain clean after the command.
+
 Canonical server install verification for a selected profile:
 
 ```sh

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.