diff --git a/.storkit/work/1_backlog/365_story_surface_api_rate_limit_warnings_in_chat.md b/.storkit/work/1_backlog/365_story_surface_api_rate_limit_warnings_in_chat.md
index cf10764..876322c 100644
--- a/.storkit/work/1_backlog/365_story_surface_api_rate_limit_warnings_in_chat.md
+++ b/.storkit/work/1_backlog/365_story_surface_api_rate_limit_warnings_in_chat.md
@@ -15,6 +15,33 @@ As a project owner watching the chat, I want to see rate limit warnings surfaced
 - [ ] The notification includes which agent/story triggered the rate limit
 - [ ] Rate limit notifications are debounced to avoid spamming the chat with repeated warnings
 
+## Technical Context
+
+Claude Code emits `rate_limit_event` JSON in its streaming output:
+
+```json
+{
+  "type": "rate_limit_event",
+  "rate_limit_info": {
+    "status": "allowed_warning",
+    "resetsAt": 1774443600,
+    "rateLimitType": "seven_day",
+    "utilization": 0.82,
+    "isUsingOverage": false,
+    "surpassedThreshold": 0.75
+  }
+}
+```
+
+Key fields:
+- `status`: `"allowed_warning"` when approaching limit, likely `"blocked"` or similar when hard-limited
+- `rateLimitType`: e.g. `"seven_day"` rolling window
+- `utilization`: 0.0–1.0 fraction of limit consumed
+- `resetsAt`: Unix timestamp when the window resets
+- `surpassedThreshold`: the threshold that triggered the warning (e.g. 0.75 = 75%)
+
+These events are already logged as `[pty-debug] raw line:` in the server logs. The PTY reader in `server/src/llm/providers/claude_code.rs` (line ~234) sees them but doesn't currently parse or act on them.
+
 ## Out of Scope
 
 - TBD