diff --git a/CLAUDE.md b/CLAUDE.md
index c3e9cc6..491d00c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -13,6 +13,16 @@ Core tech:
 - Bun.serve() for HTTP + WebSocket + SSE
 - plain text output (no xterm.js) for mobile-friendly display
 
+## Terminal Emulation
+
+Output processing uses @xterm/headless for proper VT100 emulation:
+- src/terminal.ts - headless terminal wrapper
+- One terminal instance per session (created on auth, disposed on close)
+- serializeAsHTML() produces HTML for SSE broadcast
+- ansi.ts and ansi-carryover.ts are deprecated (kept for rollback)
+
+See docs/terminal-emulation.md for design rationale.
+
 ## References
 
 Inspiration and patterns to steal from:
diff --git a/README.md b/README.md
index b10780a..6954d5b 100644
--- a/README.md
+++ b/README.md
@@ -110,6 +110,7 @@ Pure Bun stack:
 - bun-pty for PTY wrapper
 - bun:sqlite for persistence
 - Bun.serve() for HTTP + WebSocket + SSE
+- @xterm/headless for terminal emulation and state tracking
 - plain text output (mobile-friendly)
 
 Target: ~1000-1500 lines total.