feat(checker): New checker, doc updates.

Author: phil-bowens

CLAUDE.md

@@ -136,7 +136,11 @@ make audit
 # 4. Regenerate documentation
 make docs
 
-# 5. Commit atomically
+# 5. (Optional) Check against system defaults
+make check-defaults
+# Review: uniqueness %, overlaps, conflicts
+
+# 6. Commit atomically
 git add XCompose docs/*
 git commit -m "Add X, fix Y, update docs"
 ```
@@ -195,6 +199,7 @@ make all  # Runs validate + audit + docs
 - [ ] All validation passes
 - [ ] Documentation is comprehensive and up-to-date
 - [ ] CI pipeline passes
+- [ ] `check_system_defaults.py` shows high uniqueness (>70%)
 - [ ] Version tagged in git
 
 ---

Makefile

@@ -24,14 +24,15 @@
 #
 ################################################################################
 
-.PHONY: help validate audit docs all clean test install uninstall
+.PHONY: help validate audit docs all clean test install uninstall check-defaults
 
 # Configuration
 XCOMPOSE_FILE := XCompose
 PYTHON := python3
 VALIDATOR := tools/validate_xcompose.py
 AUDITOR := tools/audit_xcompose_design.py
 GENERATOR := tools/generate_xcompose_docs.py
+CHECKER := tools/check_system_defaults.py
 DOCS_DIR := docs
 
 help:  ## Show this help message
@@ -55,6 +56,10 @@ audit:  ## Run design quality audit
 	@echo "==> Running design audit..."
 	@$(PYTHON) $(AUDITOR) $(XCOMPOSE_FILE)
 
+check-defaults:  ## Compare against system defaults (informational)
+	@echo "==> Comparing against system defaults..."
+	@$(PYTHON) $(CHECKER) $(XCOMPOSE_FILE)
+
 docs:  ## Generate all documentation (HTML, JSON, Markdown, checklist)
 	@echo "==> Generating documentation..."
 	@$(PYTHON) $(GENERATOR) $(XCOMPOSE_FILE) --all
@@ -102,3 +107,7 @@ watch:  ## Watch XCompose file and auto-regenerate docs (requires entr)
 	@echo "Watching $(XCOMPOSE_FILE) for changes..."
 	@echo "Press Ctrl+C to stop"
 	@echo $(XCOMPOSE_FILE) | entr -c make docs
+
+.PHONY: list-locales
+list-locales:  ## List all available system Compose files
+	@$(PYTHON) $(CHECKER) --list-locales

docs/index.html

@@ -462,6 +462,10 @@ <h2>The Solution</h2>
                 <strong style="color: #f57c00;">⚠️ Work in Progress</strong><br>
                 This project is actively developed. Mappings may change, be added, or be removed until version 1.0 is released.
             </div>
+            <h2>What Symbols Can I Type?</h2>
+            <p>
+                See for yourself in in the <a href="xcompose_reference.html">Symbol Reference</a>. 
+            </p>
 
             <h2>What's a Compose Key?</h2>
             <p>

tools/README.md

@@ -9,6 +9,7 @@ This directory contains tools for validating, auditing, and documenting XCompose
 | `validate_xcompose.py` | Syntax & conflict validation | Required before every commit |
 | `audit_xcompose_design.py` | Design quality analysis | Recommended for major changes |
 | `generate_xcompose_docs.py` | Documentation generation | Run after XCompose changes |
+| `check_system_defaults.py` | Compare against system defaults | Recommended before release |
 | `auto_tag_xcompose.py` | Bulk comment tagging | One-time or migration tool |
 
 ---
@@ -112,6 +113,49 @@ This directory contains tools for validating, auditing, and documenting XCompose
 
 ---
 
+## check_system_defaults.py
+
+**Purpose**: Compares custom XCompose sequences against system defaults to identify overlaps, conflicts, and unique additions.
+
+**Usage**:
+```bash
+# Basic comparison
+./tools/check_system_defaults.py XCompose
+
+# Verbose output with all sequences
+./tools/check_system_defaults.py XCompose --verbose
+
+# Generate documentation notes for README
+./tools/check_system_defaults.py XCompose --notes
+
+# List all available system Compose files
+./tools/check_system_defaults.py --list-locales
+
+# Compare against specific locale
+./tools/check_system_defaults.py XCompose --system-file /usr/share/X11/locale/el_GR.UTF-8/Compose
+```
+
+**Identifies**:
+- **Overlaps**: Sequences producing same output as system (redundant but harmless)
+- **Conflicts**: Sequences overriding system defaults (intentional customization)
+- **Unique additions**: Sequences not in system defaults 
+
+**Multi-Platform Features**:
+- Auto-detects user's current locale
+- Falls back to common locales (en_US.UTF-8, C)
+- Lists all available system Compose files
+- Supports comparing against any locale
+
+**Output**: Analysis report with statistics, value assessment, and recommendations.
+
+**Use cases**:
+- Before public release (verify uniqueness)
+- Multi-platform testing (check against different locales)
+- Documentation generation (explain overrides)
+- Quality assessment (measure value-add)
+
+---
+
 ## auto_tag_xcompose.py
 
 **Purpose**: Automatically tags XCompose comments with type classification.