From 0ac5eec30de9acbf7f9d3957c062cf9bd8956f9b Mon Sep 17 00:00:00 2001
From: Jared Miller <jared@smell.flowers>
Date: Sat, 31 Jan 2026 10:04:29 -0500
Subject: [PATCH] Update docs for terminal emulation

---
 CLAUDE.md | 10 ++++++++++
 README.md |  1 +
 2 files changed, 11 insertions(+)

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.