refactor: Complete taxonomy overhaul and doc update

Major changes to project nomenclature, taxonomy, and presentation:

- Replace old tag system (VISUAL/MNEM/ALT) with Peircean semiotics-based
  taxonomy (ICONIC/MNEMONIC)
- Remove all backward compatibility for old tags across all tools
- Update validator to only accept ICONIC/MNEMONIC tags
- Remove "variant" concept entirely from codebase (no traces remain)
- Update all documentation generators to use new classification system

- Remove variant column from generated HTML and Markdown tables
- Update table headers: Symbol | Code | Iconic | Mnemonic | Description
- Change sequences display to vertical layout (flex-direction: column)
- Multiple sequences for same symbol now render on separate lines
- Update HTML legend to show only 2 tag types (ICONIC/MNEMONIC)
- Remove all variant-related CSS classes (badge-variant, sequence-variant)

- tools/validate_xcompose.py: Update valid_tags to {ICONIC, MNEMONIC}
- tools/generate_xcompose_docs.py: Rewrite classification logic, remove
  variant from data structures
- tools/xcompose_lib.py: Update tag regex pattern
- All Python tools: Update module docstrings and headers
- XCompose: Update category headers and banner
- install.sh/uninstall.sh: Update all echo messages and comments
- Makefile: Update header and help text

Author: phil-bowens

CLAUDE.md

@@ -1,4 +1,4 @@
-# xcompose-stem - Developer Documentation
+# XCompose-STEM - Developer Documentation
 
 **Architecture, design decisions, and development guide for maintainers**
 
@@ -58,15 +58,16 @@ The `XCompose` file is the **only** authoritative source. All documentation is g
 
 Comment format includes type tags:
 ```
-<Multi_key> <minus> <greater> : "→" U2192  # [VISUAL] Rightwards arrow
-<Multi_key> <h> <rarrow> : "→" U2192       # [MNEM] Rightwards arrow
-<Multi_key> <g> <a> : "α" U03B1            # [MNEM] Greek small letter alpha
+<Multi_key> <minus> <greater> : "→" U2192  # [ICONIC] Rightwards arrow
+<Multi_key> <h> <rarrow> : "→" U2192       # [MNEMONIC] Rightwards arrow
+<Multi_key> <g> <a> : "α" U03B1            # [MNEMONIC] Greek small letter alpha
 ```
 
-Type tags:
-- `[VISUAL]` - Visual/ASCII shortcuts that look like the output
-- `[MNEM]` - Mnemonic letter sequences with systematic prefixes
-- `[ALT]` - Alternative patterns or edge cases
+Type tags (based on Peircean semiotics):
+- `[ICONIC]` - Sequences that visually resemble their output (self-documenting, language-independent)
+- `[MNEMONIC]` - Sequences based on linguistic/semantic associations (abbreviations, systematic prefixes)
+
+See `docs/taxonomy-refinement-proposal.md` for the theoretical foundation and rationale.
 
 #### 2. Dual Access Pattern
 Frequently-used symbols should have **both**:

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributing to xcompose-stem
+# Contributing to XCompose-STEM
 
 Thank you for your interest in contributing! This guide will help you add new sequences or improve existing ones.
 
@@ -17,34 +17,33 @@ Thank you for your interest in contributing! This guide will help you add new se
 Add your sequence to the appropriate category in `XCompose`:
 
 ```
-<Multi_key> <h> <example> : "★" U2605  # [MNEM] Black star
+<Multi_key> <h> <example> : "★" U2605  # [MNEMONIC] Black star
 ```
 
 **Format requirements:**
 - Use `<Multi_key>` prefix
 - Include Unicode codepoint (U+XXXX format)
-- Add type tag: `[VISUAL]`, `[MNEM]`, or `[ALT]`
+- Add type tag: `[ICONIC]` or `[MNEMONIC]`
 - Write clear description
 
 ### 2. Choose the Right Type Tag
 
-**`[VISUAL]`** - Visual/ASCII shortcuts that look like the output:
+**`[ICONIC]`** - Sequences that visually resemble their output:
 ```
-<Multi_key> <minus> <greater> : "→" U2192  # [VISUAL] Rightwards arrow
-<Multi_key> <less> <equal> : "≤" U2264     # [VISUAL] Less than or equal
+<Multi_key> <minus> <greater> : "→" U2192  # [ICONIC] Rightwards arrow
+<Multi_key> <less> <equal> : "≤" U2264     # [ICONIC] Less than or equal
 ```
 
-**`[MNEM]`** - Mnemonic sequences with letter prefixes:
-```
-<Multi_key> <h> <impl> : "⇒" U21D2        # [MNEM] Implies
-<Multi_key> <g> <a> : "α" U03B1            # [MNEM] Greek small letter alpha
-```
+**Characteristics:** Self-documenting, language-independent, typically 2-3 keys
 
-**`[ALT]`** - Alternative patterns or edge cases:
+**`[MNEMONIC]`** - Sequences based on linguistic/semantic associations:
 ```
-<Multi_key> <exclam> <h> <e> : "∉" U2209  # [ALT] Not an element of
+<Multi_key> <h> <impl> : "⇒" U21D2        # [MNEMONIC] Implies
+<Multi_key> <g> <a> : "α" U03B1            # [MNEMONIC] Greek small letter alpha
 ```
 
+**Characteristics:** Abbreviations or names, systematic prefixes, discoverable patterns
+
 ### 3. Follow Prefix Conventions
 
 | Prefix | Category | Example |
@@ -187,4 +186,4 @@ By contributing, you agree that your contributions will be licensed under the MI
 
 ---
 
-**Thank you for helping make xcompose-stem better!**
+**Thank you for helping make XCompose-STEM better!**

Makefile

@@ -1,6 +1,6 @@
 ################################################################################
-# Makefile for xcompose-stem
-# Part of xcompose-stem - Keyboard shortcuts for STEM symbols on Linux
+# Makefile for XCompose-STEM
+# Part of XCompose-STEM - Easy Unicode Symbols on Linux for STEM Professionals
 #
 # Copyright (c) 2025 Phil Bowens
 # Repository: https://github.com/phil-bowens/xcompose-stem
@@ -24,7 +24,7 @@
 #
 ################################################################################
 
-.PHONY: help validate audit docs all clean test install uninstall check-defaults
+.PHONY: help validate audit docs all clean test install uninstall check-defaults comparison-table
 
 # Configuration
 XCOMPOSE_FILE := XCompose
@@ -36,7 +36,7 @@ CHECKER := tools/check_system_defaults.py
 DOCS_DIR := docs
 
 help:  ## Show this help message
-	@echo "xcompose-stem - Makefile targets"
+	@echo "XCompose-STEM - Makefile targets"
 	@echo ""
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
 		awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2}'
@@ -60,6 +60,10 @@ check-defaults:  ## Compare against system defaults (informational)
 	@echo "==> Comparing against system defaults..."
 	@$(PYTHON) $(CHECKER) $(XCOMPOSE_FILE)
 
+comparison-table:  ## Generate comparison table (saves to docs/xcompose_comparison.md)
+	@echo "==> Generating comparison table..."
+	@$(PYTHON) $(CHECKER) $(XCOMPOSE_FILE) --table --output $(DOCS_DIR)/xcompose_comparison.md
+
 docs:  ## Generate all documentation (HTML, JSON, Markdown, checklist)
 	@echo "==> Generating documentation..."
 	@$(PYTHON) $(GENERATOR) $(XCOMPOSE_FILE) --all

README.md

@@ -1,6 +1,6 @@
-# xcompose-stem
+# XCompose-STEM
 
-**Keyboard shortcuts for STEM symbols on Linux**
+**Easy Unicode Symbols on Linux for STEM Professionals**
 
 XCompose configuration providing hundreds of keyboard shortcuts for mathematical notation, Greek letters, arrows, and scientific typography.
 
@@ -27,7 +27,7 @@ This is a personal XCompose configuration, maintained for my own use and shared
 - **Systematic prefixes** - `h`=math, `g`=Greek, `k`=keyboard, `p`=IPA, `b`=box-drawing
 - **Complete symbol families** - All directional variants (arrows, inequalities, set relations)
 - **Quality tooling** - Automated validation, design audits, multi-format documentation
-- **Type-tagged sequences** - Every sequence classified as [VISUAL], [MNEM], or [ALT]
+- **Type-tagged sequences** - Every sequence classified as [ICONIC] or [MNEMONIC]
 - **Frequency-optimized** - Common symbols get shorter sequences
 - **LaTeX-inspired ergonomics** - `_` for subscripts (like LaTeX), `__` for macrons
 
@@ -291,7 +291,7 @@ Settings → Keyboard → Layout → Options → Compose key position
 **Testing your Compose key:**
 Try typing `Compose + -> ` (Compose, then minus, then greater-than). You should get: →
 
-If it works, you're ready to use xcompose-stem!
+If it works, you're ready to use XCompose-STEM!
 
 ---