docs: Document why activationEvents are necessary

Added comprehensive documentation to CLAUDE.md explaining why the
activationEvents array in package.json must be kept.

Key clarification:
- VS Code 1.74+ made onCommand activation implicit (for commands)
- onLanguage activation is DIFFERENT and still required
- Our extension activates on file open, not command invocation
- Without onLanguage events, extension won't be ready when TS/JS files open

This addresses a common misconception and prevents future audit questions
about why we don't remove activationEvents.

References:
- VS Code 1.74 Release Notes (implicit command activation)
- StackOverflow discussion (specifically about onCommand, not onLanguage)

Closes final audit point - all implementation complete.

Author: JohannesHoppe

.claude/settings.local.json

@@ -10,7 +10,9 @@
       "Bash(npm run check-types)",
       "Bash(npm run lint)",
       "Bash(npm run)",
-      "Bash(npm run build)"
+      "Bash(npm run build)",
+      "Bash(curl -s \"https://code.visualstudio.com/updates/\")",
+      "WebFetch(domain:code.visualstudio.com)"
     ],
     "deny": [],
     "ask": []

CLAUDE.md

@@ -218,6 +218,36 @@ All tests use REAL VSCode APIs with explicit expected outputs.
 
 ---
 
+## 📦 Extension Activation
+
+### Why We Keep `activationEvents` in package.json
+
+The `activationEvents` array is **required and correct**:
+
+```json
+"activationEvents": [
+  "onLanguage:typescript",
+  "onLanguage:typescriptreact",
+  "onLanguage:javascript",
+  "onLanguage:javascriptreact"
+],
+```
+
+**Common misconception:** VS Code 1.74+ made activation events "implicit"
+
+**Reality:** Only **command** activation (`onCommand`) became implicit. Language-based activation (`onLanguage`) is different - it activates the extension when specific file types are opened.
+
+**Why we need this:**
+- Our extension must activate when TS/JS files are opened (not when commands are invoked)
+- Without `onLanguage` activation events, the extension won't be ready when users open TypeScript/JavaScript files
+- The `contributes.commands` entries only handle command registration, not language-based activation
+
+**References:**
+- VS Code 1.74 Release Notes: https://code.visualstudio.com/updates/v1_74
+- StackOverflow: https://stackoverflow.com/a/75303487 (about `onCommand`, NOT `onLanguage`)
+
+---
+
 ### 2. Test Harness Tests (`comparison-test-harness/`)
 
 **Purpose**: Validate backward compatibility between old and new extension