diff --git a/CLAUDE.md b/CLAUDE.md
index eb24c7f..4639080 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -304,6 +304,10 @@ add_action( 'wp_prometheus_collect_metrics', function( $collector ) {
   - Settings must be inside `<form action="options.php">` with `settings_fields()` call
   - Each sub-tab needs its own form wrapper for proper saving
   - Sub-tabs use URL query parameter (`subtab`) within the main tab
+- **Key Learning**: WordPress plugin versioning requires TWO updates
+  - Plugin header comment `Version: x.x.x` (line ~6) - used by WordPress admin
+  - PHP constant `WP_PROMETHEUS_VERSION` (line ~133) - used internally
+  - CI/CD checks both must match the git tag, causing release failures if mismatched
 
 ### 2026-02-02 - Early Mode Toggle (v0.4.2)