1 files changed, 28 insertions, 0 deletions

diff --git a/CONTEXT.md b/CONTEXT.md
index 861fbf8..1c43b1f 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -99,6 +99,10 @@ Starts fully collapsed on first open. `Insert` toggles; `Up`/`Down` navigate;
 Bind rows enter bind-select mode: press a key/button to assign, `Escape` sets
 None (always-on), `Enter` cancels.
 
+> The text menu below is being replaced by the GUI described in the next
+> section. The old tree is kept only until the GUI reaches parity. The current
+> preview shell opens with F2; Insert still opens the text tree.
+
 ```
 HL2hake
   Bunnyhop
@@ -136,6 +140,30 @@ HL2hake
 
 Binds use SDL scancodes; mouse buttons are pseudo-scancodes 600..604.
 
+## GUI vocabulary / decisions
+
+- **GUI**: custom immediate-mode settings surface drawn through the existing
+  `ISurface` paint path. No Dear ImGui, no OpenGL hook, no new runtime
+  dependency.
+- **Category**: sidebar group. Movement, Combat, Visuals, Weapons, System.
+- **Card**: per-feature panel. Header always shows Active + Bind; body is a
+  collapsible set of settings.
+- **Freeze**: while the GUI is open, the usercmd movement/buttons/impulses/view
+  are held and combat features are skipped; the game keeps simulating and
+  ESP/FOV circle/speed graph keep drawing. No invulnerability.
+- **Native cursor**: on open, leave SDL relative-mouse mode and show the OS
+  cursor; restore on close. Absolute mouse coordinates are used.
+- **Bind capture**: click Bind, press a key/button; Esc or clicking elsewhere
+  cancels; Clear sets None; Insert is reserved for the GUI.
+- **UI scale**: `clamp(min(screen_w/1920, screen_h/1080), 0.75, 1.5)`; base
+  window 960x620, body/title fonts 15/20 px at scale 1.
+- Every feature gets Active + Bind; bind None means always-on.
+- System page: config path/build info, Reload config, and a two-click Reset
+  that restores feature settings/binds but keeps GUI layout.
+- Window: fixed-size, draggable by title bar, clamped to screen, position,
+  category and expanded cards persisted under `[gui]`.
+
+
 ## Bones / ESP
 
 - `SetupBones(BONE_USED_BY_ANYTHING)` with engine `Time()`; studio header via