docs: update CSS_VARIABLES.md and CHANGELOG with sync script docs and version bump

- Bump CSS_VARIABLES.md version to 03.09.02, update effective date
- Add sync_custom_vars.php usage instructions to custom palette section
- Update CHANGELOG to reflect all files modified/added including standard
  theme files, script.php, and language files
- Bump CHANGELOG header version to 03.09.02

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -12,7 +12,7 @@
  BRIEF: Changelog file documenting version history of MokoCassiopeia
  -->
 
-# Changelog — MokoCassiopeia (VERSION: 03.08.03)
+# Changelog — MokoCassiopeia (VERSION: 03.09.02)
 
 All notable changes to the MokoCassiopeia Joomla template are documented in this file.
 
@@ -37,13 +37,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 #### Files Modified
 - `src/media/css/template.css` — hero variant rules, block color `:nth-child()` rules, named override rules
-- `src/templates/light.custom.css` — hero and block color variables (light mode)
-- `src/templates/dark.custom.css` — hero and block color variables (dark mode)
-- `docs/CSS_VARIABLES.md` — full variable reference for both systems
+- `src/media/css/theme/light.standard.css` — hero and block color variables (light standard)
+- `src/media/css/theme/dark.standard.css` — hero and block color variables (dark standard)
+- `src/templates/light.custom.css` — hero and block color variables (light custom starter)
+- `src/templates/dark.custom.css` — hero and block color variables (dark custom starter)
+- `src/templateDetails.xml` — Theme Preview tab, hero/block note fields, scriptfile registration, version bump to 03.09.02
+- `src/language/en-GB/tpl_mokocassiopeia.ini` — language strings for new admin fields (British English)
+- `src/language/en-US/tpl_mokocassiopeia.ini` — language strings for new admin fields (American English)
+- `docs/CSS_VARIABLES.md` — full variable reference for both systems, sync script documentation
 - `CHANGELOG.md` — this entry
 
 #### Files Added
-- `src/templates/theme-test.html` — Bootstrap-style test page showing all CSS variables and new features
+- `src/templates/theme-test.html` — Bootstrap-style test page with branded showcase, CSS variable swatches, hero demos, block color demos, and color test image
+- `src/script.php` — Joomla install/update lifecycle script (runs CSS variable sync on upgrade, checks PHP/Joomla minimum versions)
+- `src/sync_custom_vars.php` — CLI/library utility that detects missing CSS variables in user custom palettes and injects them
 
 ---
 

docs/CSS_VARIABLES.md

@@ -10,7 +10,7 @@
  INGROUP: MokoCassiopeia.Documentation
  REPO: https://github.com/mokoconsulting-tech/MokoCassiopeia
  FILE: docs/CSS_VARIABLES.md
- VERSION: 03.06.03
+ VERSION: 03.09.02
  BRIEF: Complete CSS variable reference for MokoCassiopeia template
 -->
 
@@ -60,6 +60,12 @@ To create custom color schemes:
 
 4. **Note**: Custom files are gitignored and won't be committed to the repository
 
+5. **On upgrade**: When the template is updated, `script.php` automatically runs `sync_custom_vars.php` to detect any new variables added to the starter templates and inject them into your existing custom palette files. Your existing values are never overwritten — only genuinely new variables are added. You can also run this manually:
+   ```bash
+   php templates/mokocassiopeia/sync_custom_vars.php --dry-run   # preview what would be added
+   php templates/mokocassiopeia/sync_custom_vars.php              # apply missing variables
+   ```
+
 ---
 
 ## Primary Brand Colors
@@ -1440,9 +1446,9 @@ These ensure optimal readability for links within alert boxes.
 * Repository: [https://github.com/mokoconsulting-tech/MokoCassiopeia](https://github.com/mokoconsulting-tech/MokoCassiopeia)
 * Path: /docs/CSS_VARIABLES.md
 * Owner: Moko Consulting
-* Version: 03.06.03
+* Version: 03.09.02
 * Status: Active
-* Effective Date: 2026-01-30
+* Effective Date: 2026-03-26
 * Classification: Public Open Source Documentation
 
 ## Revision History